mirror of
https://github.com/boostorg/iostreams.git
synced 2026-02-27 17:12:17 +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> |