mirror of
https://github.com/boostorg/iostreams.git
synced 2026-02-22 03:22:24 +00:00
157 lines
9.6 KiB
HTML
Executable File
157 lines
9.6 KiB
HTML
Executable File
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML>
|
|
<HEAD>
|
|
<TITLE>The Boost Iostreams Library</TITLE>
|
|
<LINK REL='stylesheet' HREF='../../../boost.css'>
|
|
<LINK REL='stylesheet' HREF='theme/iostreams.css'>
|
|
</HEAD>
|
|
<BODY>
|
|
|
|
<!-- Begin Banner -->
|
|
|
|
<H1 CLASS='title'>The Boost Iostreams Library</H1>
|
|
<HR CLASS='banner'>
|
|
|
|
<!-- End Banner -->
|
|
|
|
<H2>Note</H2>
|
|
|
|
<P>
|
|
This library has been accepted as part of <A HREF='http://www.boost.org'>Boost</A>, but is not part of the current Boost distribution. I expect it to appear in the first major release of Boost following the upcoming 1.32 release. The release will incorporate a number of changes, mostly small.
|
|
</P>
|
|
|
|
<A NAME='overview'></A>
|
|
<H2>Overview</H2>
|
|
|
|
<P>
|
|
The Iostreams Library serves two main purposes:
|
|
<UL>
|
|
<LI CLASS='square'>
|
|
To allow the easy creation of standard C++ stream and stream buffer classes
|
|
for new data sources and sinks.
|
|
</LI>
|
|
<LI CLASS='square'>
|
|
To provide a convenient interface for defining i/o filters and attaching them to standard streams and stream buffers.
|
|
</LI>
|
|
</UL>
|
|
The library focuses on freeing users from writing boiler plate code and allowing them instead to create highly reusable components.
|
|
</P>
|
|
<P>
|
|
In addition to providing an abstract framework the library provides a number of concrete filters, sources and sinks which serve as example applications of the library but are also useful in their own right. These include components for accessing <A HREF="classes/mapped_file.html">memory-mapped files</A>, for file access <I>via</I> operating system <A HREF="classes/file_descriptor.html">file descriptors</A>, for <A HREF="code_conversion.html">code conversion</A>, for text filtering with <A HREF="classes/regex_filter.html">regular expressions</A>, for <A HREF="classes/newline_filter.html">line-ending conversion</A> and for <A HREF="compression.html">compression and decompression</A> in the zlib, gzip and bzip2 formats.
|
|
</P>
|
|
|
|
<H5>Concepts</H5>
|
|
|
|
<P>
|
|
The fundamental building blocks of the library are the concepts of a <A HREF='concepts/source.html'>Source</A>, which provides read access to a sequence of characters, a <A HREF='concepts/sink.html'>Sink</A>, which provides write access to a sequence of characters, an <A HREF='concepts/input_filter.html'>InputFilter</A>, which filters input read from a Source, and an <A HREF='concepts/output_filter.html'>OutputFilter</A>, which filters output written to a Sink. Sources, Sinks and their refinements are called <SPAN CLASS='term'>Devices</SPAN>. InputFilters, OutputFilters and their refinements are called <SPAN CLASS='term'>Filters</SPAN>.
|
|
</P>
|
|
|
|
<H5>Policy-Based Streams and Stream Buffers</H5>
|
|
|
|
<P>
|
|
The class templates <A HREF='policy_based_streams.html#streambuf_facade'><CODE>streambuf_facade</CODE></A> and <A HREF='policy_based_streams.html#stream_facade'><CODE>stream_facade</CODE></A> implement standard stream buffers and streams which perform i/o by delegating to a contained Filter or Device. The Filter or Device is accessed using member functions <CODE>open</CODE>, <CODE>is_open</CODE> and <CODE>close</CODE>, providing an interface similar to the standard file-based streams and stream buffers.
|
|
</P>
|
|
|
|
<H5>Filtering Streams and Stream Buffers</H5>
|
|
|
|
<P>
|
|
For filtering data the Iostreams Library provides the templates <A HREF="classes/filtering_streambuf.html"><CODE>filtering_streambuf</CODE></A> and <A HREF="classes/filtering_stream.html"><CODE>filtering_stream</CODE></A>. Instances of <CODE>filtering_streambuf</CODE> or <CODE>filtering_stream</CODE> contains chains of Filters and Devices accessed with an interface similar to that of <CODE>std::stack</CODE>.
|
|
</P>
|
|
|
|
<A NAME='conventions'></A>
|
|
<H2>Conventions</H2>
|
|
|
|
<UL>
|
|
<LI CLASS='square'>
|
|
All classes, functions and templates introduced in the documentation are in the
|
|
namespace <CODE>boost::io</CODE>. Namespace qualification is usually omitted.
|
|
</LI>
|
|
<LI CLASS='square'>
|
|
Specializations of <CODE>std::basic_istream</CODE> will be refered to as
|
|
<SPAN CLASS='term'>standard input streams</SPAN>, specializations of <CODE>std::basic_ostream</CODE>
|
|
as <SPAN CLASS='term'>standard output streams</SPAN>, specializations of <CODE>std::basic_iostream</CODE>
|
|
as <SPAN CLASS='term'>standard i/o streams</SPAN>, and specializations of <CODE>std::basic_streambuf</CODE>
|
|
as <SPAN CLASS='term'>standard stream buffers</SPAN>. Together, standard input streams, standard output streams and standard i/o streams will be refered to as <SPAN CLASS='term'>standard streams</SPAN>. Sometimes the qualifier <I>standard</I> will be omitted for brevity.
|
|
</LI>
|
|
</UL>
|
|
|
|
<A NAME='acknowledgments'></A>
|
|
<H2>Acknowledgments</H2>
|
|
|
|
The original idea for the library came from Angelika Langer and Klaus Kreft (<A CLASS='bib_ref' HREF='bibliography.html#langer'>[Langer]</A>, <I>pp.</I> 228-43). <A HREF='http://lists.boost.org/MailArchives/boost/msg48300.php' TARGET='_top'>Robert Ramey</A> suggested extending the library to handle filtering.
|
|
|
|
<UL>
|
|
<LI CLASS='square'>
|
|
The implementation of <A HREF='policy_based_streams.html#streambuf_facade'><CODE>streambuf_facade</CODE></A> is heavily indebted to work of Angelika Langer and Klaus Kreft (<A CLASS='bib_ref' HREF='bibliography.html#langer'>[Langer]</A>, <I>pp.</I> 228-43).
|
|
</LI>
|
|
<LI CLASS='square'>
|
|
The concepts <A HREF='concepts/input_filter.html'>InputFilter</A> and <A HREF='concepts/output_filter.html'>OutputFilter</A> are based on the <I>extractors</I> and <I>inserters</I> introduced by James Kanze in <A CLASS='bib_ref' HREF='bibliography.html#kanze'>[Kanze]</A>. The names of the filtering stream and stream buffer templates also come from Kanze.
|
|
</LI>
|
|
<LI CLASS='square'>
|
|
Three of the <A HREF='examples.html'>examples</A> are due to James Kanze (<A CLASS='bib_ref' HREF='bibliography.html#kanze'>[Kanze]</A>).
|
|
</LI>
|
|
<LI CLASS='square'>
|
|
The <A HREF='adapters.html'>sequence adapters</A> were inspired by the work of Maxim Egorushkin (<A CLASS='bib_ref' HREF='bibliography.html#egorushkin'>[Egorushkin]</A>). He also suggested parameterizing the filtering streams and stream buffers by i/o mode, greatly reducing the number of library templates.
|
|
</LI>
|
|
<LI CLASS='square'>
|
|
The treatment of <A HREF='classes/mapped_file.html'>memory mapped files</A> is based on work of Craig Henderson (<A CLASS='bib_ref' HREF='bibliography.html#henderson'>[Henderson]</A>).
|
|
</LI>
|
|
<LI CLASS='square'>
|
|
The <A HREF='classes/file_descriptor.html'>file descriptor Devices</A> are based on work of Nicolai Josuttis (<A CLASS='bib_ref' HREF='bibliography.html#josuttis1'>[Josuttis1]</A> and <A CLASS='bib_ref' HREF='bibliography.html#josuttis2'>[Josuttis2]</A>).
|
|
</LI>
|
|
<LI CLASS='square'>
|
|
The Filters for <A HREF='compression.html'>compression and decompression</A> were influenced by the work of Jeff Garland (<A CLASS='bib_ref' HREF='bibliography.html#garland'>[Garland]</A>) and Jonathan de Halleux (<A CLASS='bib_ref' HREF='bibliography.html#de_halleux'>[de Halleux]</A>).
|
|
</LI>
|
|
<LI CLASS='square'>
|
|
Larry Evans, John Torjo and Maxim Egorushkin gave detailed critiques of prior versions of the library.
|
|
</LI>
|
|
<LI CLASS='square'>
|
|
The treamtent of <A HREF='exceptions.html'>exceptions</A> in the documentation benefited from discussions with Angelika Langer and John Torjo.
|
|
</LI>
|
|
<LI CLASS='square'>
|
|
Denis Bider offered useful insights about the implications of using Filters and Devices allocated inline with <CODE>new</CODE>.
|
|
</LI>
|
|
<LI CLASS='square'>
|
|
Others who made helpful comments or whose code was influential include Paul Bristow, Robert Ramey and Daryle Walker.
|
|
</LI>
|
|
<LI CLASS='square'>
|
|
The templates <A HREF='policy_based_streams.html#streambuf_facade'><CODE>streambuf_facade</CODE></A> and <A HREF='policy_based_streams.html#stream_facade'><CODE>stream_facade</CODE></A> are named after the template <A HREF='http://www.boost.org/libs/iterator/doc/iterator_facade.html' TARGET='_top'><CODE>iterator_facade</CODE></A> from <A HREF='http://www.boost.org/libs/iterator/doc/index.html' TARGET='_top'><CODE>The Boost.Iterator Library</CODE></A> (<I>see</I> <A CLASS='bib_ref' HREF='bibliography.html#abrahams2'>[Abrahams2]</A>).
|
|
</LI>
|
|
</UL>
|
|
|
|
<!-- Begin Footnotes -->
|
|
|
|
<HR>
|
|
|
|
<P>
|
|
<A CLASS='footnote_ref' NAME='note_1' HREF='#note_1_ref'><SUP>[1]</SUP></A>This is an instance of a limitation of C++ known as the <I>forwarding problem</I> (<I>see</I> <A CLASS='bib_ref' HREF='bibliography.html#dimov'>[Dimov]</A>).
|
|
</P>
|
|
|
|
<P>
|
|
<A CLASS='footnote_ref' NAME='note_2' HREF='#note_2_ref'><SUP>[2]</SUP></A>Technically, <CODE>boost::iostreams::get</CODE> and <CODE>boost::iostreams::read</CODE> require that a Source be <A HREF='concepts/direct.html'><I>indirect</I></A>.
|
|
</P>
|
|
|
|
<P>
|
|
<A CLASS='footnote_ref' NAME='note_3' HREF='#note_3_ref'><SUP>[3]</SUP></A>Technically, <CODE>boost::iostreams::put</CODE> requires that a Sink be <A HREF='concepts/direct.html'><I>indirect</I></A>.
|
|
</P>
|
|
|
|
<!-- End Footnotes -->
|
|
|
|
|
|
<!-- Begin Footer -->
|
|
|
|
<HR>
|
|
|
|
<P CLASS='copyright'>Revised
|
|
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
|
|
20 May, 2004
|
|
<!--webbot bot="Timestamp" endspan i-checksum="38504" -->
|
|
</P>
|
|
|
|
<P CLASS='copyright'>© Copyright Jonathan Turkanis, 2004</P>
|
|
<P CLASS='copyright'>
|
|
Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at <A HREF='http://www.boost.org/LICENSE_1_0.txt'>http://www.boost.org/LICENSE_1_0.txt</A>)
|
|
</P>
|
|
<!-- End Footer -->
|
|
|
|
</BODY> |