123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223 |
- [/==============================================================================
- Copyright (C) 2001-2011 Hartmut Kaiser
- Copyright (C) 2001-2011 Joel de Guzman
- Distributed under the Boost Software License, Version 1.0. (See accompanying
- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
- ===============================================================================/]
- [section:stream Stream Generators]
- This module includes the description of the different variants of the `stream`
- generator. It can be used to utilize existing streaming operators
- (`operator<<(std::ostream&, ...)`) for output generation.
- [heading Header]
- // forwards to <boost/spirit/home/karma/stream.hpp>
- #include <boost/spirit/include/karma_stream.hpp>
- Also, see __include_structure__.
- [section:stream Stream Generators (`stream`, `wstream`, etc.)]
- [heading Description]
- The `stream_generator` is a primitive which allows to use pre-existing standard
- streaming operators for output generation integrated with __karma__. It
- provides a wrapper generator dispatching the value to output to the stream
- operator of the corresponding type. Any value `a` to be formatted using the
- `stream_generator` will result in invoking the standard streaming operator
- for its type `A`, for instance:
- std::ostream& operator<< (std::ostream&, A const&);
- [heading Header]
- // forwards to <boost/spirit/home/karma/stream.hpp>
- #include <boost/spirit/include/karma_stream.hpp>
- Also, see __include_structure__.
- [heading Namespace]
- [table
- [[Name]]
- [[`boost::spirit::stream // alias: boost::spirit::karma::stream`]]
- [[`boost::spirit::wstream // alias: boost::spirit::karma::wstream`]]
- ]
- [heading Synopsis]
- template <typename Char>
- struct stream_generator;
- [heading Template parameters]
- [table
- [[Parameter] [Description] [Default]]
- [[`Char`] [The character type to use to generate
- the output. This type will be used while
- assigning the generated characters to the
- underlying output iterator.] [`char`]]
- ]
- [heading Model of]
- [:__primitive_generator_concept__]
- [variablelist Notation
- [[`s`] [A variable instance of any type with a defined matching
- streaming `operator<<()` or a __karma_lazy_argument__ that
- evaluates to any type with a defined matching streaming
- `operator<<()`.]]
- ]
- [heading Expression Semantics]
- Semantics of an expression is defined only where it differs from, or is
- not defined in __primitive_generator_concept__.
- [table
- [[Expression] [Description]]
- [[`stream`] [Call the streaming `operator<<()` for the type
- of the mandatory attribute. The output emitted
- by this operator will be the result of the
- `stream` generator. This generator never fails
- (unless the underlying output stream reports an
- error). The character type of the I/O ostream
- is assumed to be `char`.]]
- [[`stream(s)`] [Call the streaming `operator<<()` for the type
- of the immediate value `s`. The output emitted
- by this operator will be the result of the
- `stream` generator. This generator never fails
- (unless the underlying output stream reports an
- error). The character type of the I/O ostream
- is assumed to be `char`.]]
- [[`wstream`] [Call the streaming `operator<<()` for the type
- of the mandatory attribute. The output emitted
- by this operator will be the result of the
- `stream` generator. This generator never fails
- (unless the underlying output stream reports an
- error). The character type of the I/O ostream
- is assumed to be `wchar_t`.]]
- [[`wstream(s)`] [Call the streaming `operator<<()` for the type
- of the immediate value `s`. The output emitted
- by this operator will be the result of the
- `stream` generator. This generator never fails
- (unless the underlying output stream reports an
- error). The character type of the I/O ostream
- is assumed to be `wchar_t`.]]
- ]
- All generators listed in the table above are predefined specializations of the
- `stream_generator<Char>` basic stream generator type described below. It is
- possible to directly use this type to create stream generators using an
- arbitrary underlying character type.
- [table
- [[Expression] [Semantics]]
- [
- [``stream_generator<
- Char
- >()``] [Call the streaming `operator<<()` for the type
- of the mandatory attribute. The output emitted
- by this operator will be the result of the
- `stream` generator. This generator never fails
- (unless the underlying output stream reports an
- error). The character type of the I/O ostream
- is assumed to be `Char`]]
- [
- [``stream_generator<
- Char
- >()(s)``] [Call the streaming `operator<<()` for the type
- of the immediate value `s`. The output emitted
- by this operator will be the result of the
- `stream` generator. This generator never fails
- (unless the underlying output stream reports an
- error). The character type of the I/O ostream
- is assumed to be `Char`.]]
- ]
- [heading Additional Requirements]
- All of the stream generators listed above require the type of the value to
- generate output for (either the immediate value or the associated attribute) to
- implement a streaming operator conforming to the usual I/O streams conventions
- (where `attribute_type` is the type of the value to generate output for):
- template <typename Ostream>
- Ostream& operator<< (Ostream& os, attribute_type const& attr)
- {
- // type specific output generation
- return os;
- }
- This operator will be called by the stream generators to gather the output for
- the attribute of type `attribute_type`. All data streamed into the given
- `Ostream` will end up being generated by the corresponding stream generator
- instance.
- [note If the `stream` generator is invoked inside a [karma_format `format`]
- (or [karma_format `format_delimited`]) stream manipulator the `Ostream`
- passed to the `operator<<()` will have registered (imbued) the same
- standard locale instance as the stream the [karma_format `format`] (or
- [karma_format `format_delimited`]) manipulator has been used with.
- This ensures all facets registered (imbued) with the original I/O
- stream object are used during output generation.
- ]
- [heading Attributes]
- [table
- [[Expression] [Attribute]]
- [[`stream`] [`hold_any`, attribute is mandatory (otherwise compilation will fail)]]
- [[`stream(s)`] [__unused__]]
- [[`wstream`] [`whold_any`, attribute is mandatory (otherwise compilation will fail)]]
- [[`wstream(s)`] [__unused__]]
- [[`stream_generator<Char>()`] [`basic_hold_any<Char>`, attribute is mandatory (otherwise compilation will fail)]]
- [[`stream_generator<Char>()(s)`] [__unused__]]
- ]
- [important The attribute type `hold_any` exposed by some of the stream
- generators is semantically and syntactically equivalent to
- the type implemented by __boost_any__. It has been added to /Spirit/
- as it has better a performance and a smaller footprint if compared to
- __boost_any__.
- ]
- [note In addition to their usual attribute of type `Attrib` all listed generators
- accept an instance of a `boost::optional<Attrib>` as well. If the
- `boost::optional<>` is initialized (holds a value) the generators behave
- as if their attribute was an instance of `Attrib` and emit the value stored
- in the `boost::optional<>`. Otherwise the generators will fail.]
- [heading Complexity]
- [:O(N), where N is the number of characters emitted by the stream generator]
- [heading Example]
- [note The test harness for the example(s) below is presented in the
- __karma_basics_examples__ section.]
- Some includes:
- [reference_karma_includes]
- Some using declarations:
- [reference_karma_using_declarations_stream]
- And a class definition used in the examples:
- [reference_karma_complex]
- [reference_karma_stream_complex]
- Basic usage of `stream` generators:
- [reference_karma_stream]
- [endsect]
- [endsect]
|