1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN">
4 <TITLE>Tutorial
</TITLE>
5 <LINK REL=
"stylesheet" HREF=
"../../../../boost.css">
6 <LINK REL=
"stylesheet" HREF=
"../theme/iostreams.css">
12 <H1 CLASS=
"title">Tutorial
</H1>
20 <A><IMG WIDTH=
19 HEIGHT=
19 SRC='../../../../doc/src/images/prev_disabled.png'
></A>
21 <A HREF='tutorial.html'
><IMG BORDER=
0 WIDTH=
19 HEIGHT=
19 SRC='../../../../doc/src/images/up.png'
></A>
22 <A HREF='container_source.html'
><IMG BORDER=
0 WIDTH=
19 HEIGHT=
19 SRC='../../../../doc/src/images/next.png'
></A>
27 <A NAME=
"device_overview"></A>
28 <H2 CLEAR='right'
>2.1.1. Overview: Devices,
<CODE>stream_buffer
</CODE> and
<CODE>stream
</CODE></H2>
30 <P>Writing a new stream or stream buffer class using the Boost Iostreams library is easy: you simply write a class modeling the
<A HREF=
"../concepts/device.html">Device
</A> concept, then use that class as the template argument to
<A HREF=
"../guide/generic_streams.html#stream"><CODE>stream
</CODE></A> or
<A HREF=
"../guide/generic_streams.html#stream_buffer"><CODE>stream_buffer
</CODE></A>:
32 <PRE CLASS=
"broken_ie"><SPAN CLASS='preprocessor'
>#include
</SPAN> <A CLASS=
"HEADER" HREF=
"../../../../boost/iostreams/stream.hpp"><SPAN CLASS='literal'
><boost/iostreams/stream.hpp
></SPAN></A>
33 <SPAN CLASS='preprocessor'
>#include
</SPAN> <A HREF=
"../../../../boost/iostreams/stream_buffer.hpp"><SPAN CLASS='literal'
><boost/iostreams/stream_buffer.hpp
></SPAN></A>
35 <SPAN CLASS='keyword'
>namespace
</SPAN> io = boost::iostreams;
37 <SPAN CLASS='keyword'
>class
</SPAN> my_device {
<SPAN CLASS='comment'
>/* */
</SPAN> };
39 <SPAN CLASS='keyword'
>typedef
</SPAN> io::stream
<my_device
> my_stream;
40 <SPAN CLASS='keyword'
>typedef
</SPAN> io::stream_buffer
<my_device
> my_streambuf;
</PRE>
42 <P>Here
<CODE>io::stream_buffer
<my_device
></CODE> is a derived class of
<CODE>std::basic_streambuf
</CODE>, and
<CODE>io::stream
<my_device
></CODE> is a derived class of
<CODE>std::basic_istream
</CODE>,
<CODE>std::basic_ostream
</CODE> or
<CODE>std::basic_iostream
</CODE> depending on the
<A HREF=
"../guide/modes.html">mode
</A> of my_device,
<I>i.e.
</I>, depending on which of the fundamental i/o operations
<A HREF=
"../functions/read.html"><CODE>read
</CODE></A>,
<A HREF=
"../functions/write.html"><CODE>write
</CODE></A> and
<A HREF=
"../functions/seek.html"><CODE>seek
</CODE></A> it supports.
44 <P>The template
<CODE>io::stream
</CODE> is provided as a convenience. It's always possible to avoid
<CODE>io::stream
</CODE> and simply use
<CODE>io::stream_buffer
</CODE> together with one of the standard library stream templates.
<I>E.g.
</I>,
46 <PRE CLASS=
"broken_ie"><SPAN CLASS='preprocessor'
>#include
</SPAN> <SPAN CLASS='literal'
><ostream
></SPAN>
47 <SPAN CLASS='preprocessor'
>#include
</SPAN> <A CLASS=
"HEADER" HREF=
"../../../../boost/iostreams/device/file.hpp"><SPAN CLASS='literal'
><boost/iostreams/device/file.hpp
></SPAN></A>
48 <SPAN CLASS='preprocessor'
>#include
</SPAN> <A CLASS=
"HEADER" HREF=
"../../../../boost/iostreams/stream.hpp"><SPAN CLASS='literal'
><boost/iostreams/stream.hpp
></SPAN></A>
50 <SPAN CLASS='keyword'
>namespace
</SPAN> io = boost::iostreams;
52 <SPAN CLASS='keyword'
>int
</SPAN> main()
54 io::stream_buffer
<io::file_sink
> buf(
<SPAN CLASS='literal'
>"log.txt"</SPAN>);
55 std::ostream out(
&buf);
56 <SPAN CLASS='comment'
>// out writes to log.txt
</SPAN>
59 <P>In this example, the
<CODE>ostream
</CODE> <CODE>out
</CODE> uses the
<CODE>stream_buffer
</CODE> <CODE>buf
</CODE> as its underlying data sink, so that data written to
<CODE>out
</CODE> goes to the file
<I>log.txt
</I>. The same effect could be achieved by default constructing
<CODE>out
</CODE> and telling it to use stream buffer
<CODE>buf
</CODE> by invoking
<CODE>out.rdbuf(
&buf)
</CODE>.
61 <P>Another way to define a new stream or stream buffer class using the Boost Iostreams library is to derive from
<A HREF=
"../classes/filtering_stream.html"><CODE>filtering_stream
</CODE></A> or
<A HREF=
"../classes/filtering_streambuf.html"><CODE>filtering_streambuf
</CODE></A>.
62 <P>The next three items will demonstrate how to write Devices for accessing STL-compatible containers. The source code for the examples can be found in the header
<A HREF=
"../../example/container_device.hpp"><<CODE>libs/iostreams/example/container_device.hpp
</CODE>></A></P>
67 <IMG WIDTH=
19 HEIGHT=
19 SRC='../../../../doc/src/images/prev_disabled.png'
>
68 <A HREF='tutorial.html'
><IMG BORDER=
0 WIDTH=
19 HEIGHT=
19 SRC='../../../../doc/src/images/up.png'
></A>
69 <A HREF='container_source.html'
><IMG BORDER=
0 WIDTH=
19 HEIGHT=
19 SRC='../../../../doc/src/images/next.png'
></A>
79 <P CLASS=
"copyright">© Copyright
2008 <a href=
"http://www.coderage.com/" target=
"_top">CodeRage, LLC
</a><br/>© Copyright
2004-
2007 <a href=
"http://www.coderage.com/turkanis/" target=
"_top">Jonathan Turkanis
</a></P>
81 Use, modification, and distribution are subject to the Boost Software License, Version
2.0. (See accompanying file
<A HREF=
"../../../../LICENSE_1_0.txt">LICENSE_1_0.txt
</A> or copy at
<A HREF=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt
</A>)