ceph/src/boost/libs/spirit/doc/karma/stream.qbk

   1 [/==============================================================================
   2     Copyright (C) 2001-2011 Hartmut Kaiser
   3     Copyright (C) 2001-2011 Joel de Guzman
   4
   5     Distributed under the Boost Software License, Version 1.0. (See accompanying
   6     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   7 ===============================================================================/]
   8
   9 [section:stream Stream Generators]
  10
  11 This module includes the description of the different variants of the `stream`
  12 generator. It can be used to utilize existing streaming operators
  13 (`operator<<(std::ostream&, ...)`) for output generation.
  14
  15 [heading Header]
  16
  17     // forwards to <boost/spirit/home/karma/stream.hpp>
  18     #include <boost/spirit/include/karma_stream.hpp>
  19
  20 Also, see __include_structure__.
  21
  22 [section:stream Stream Generators (`stream`, `wstream`, etc.)]
  23
  24 [heading Description]
  25
  26 The `stream_generator` is a primitive which allows to use pre-existing standard
  27 streaming operators for output generation integrated with __karma__. It
  28 provides a wrapper generator dispatching the value to output to the stream
  29 operator of the corresponding type. Any value `a` to be formatted using the
  30 `stream_generator` will result in invoking the standard streaming operator
  31 for its type `A`, for instance:
  32
  33     std::ostream& operator<< (std::ostream&, A const&);
  34
  35 [heading Header]
  36
  37     // forwards to <boost/spirit/home/karma/stream.hpp>
  38     #include <boost/spirit/include/karma_stream.hpp>
  39
  40 Also, see __include_structure__.
  41
  42 [heading Namespace]
  43
  44 [table
  45     [[Name]]
  46     [[`boost::spirit::stream  // alias: boost::spirit::karma::stream`]]
  47     [[`boost::spirit::wstream // alias: boost::spirit::karma::wstream`]]
  48 ]
  49
  50 [heading Synopsis]
  51
  52     template <typename Char>
  53     struct stream_generator;
  54
  55 [heading Template parameters]
  56
  57 [table
  58     [[Parameter]    [Description]                       [Default]]
  59     [[`Char`]   [The character type to use to generate
  60                  the output. This type will be used while
  61                  assigning the generated characters to the
  62                  underlying output iterator.]           [`char`]]
  63 ]
  64
  65 [heading Model of]
  66
  67 [:__primitive_generator_concept__]
  68
  69 [variablelist Notation
  70     [[`s`]      [A variable instance of any type with a defined matching
  71                  streaming `operator<<()` or a __karma_lazy_argument__ that
  72                  evaluates to any type with a defined matching streaming
  73                  `operator<<()`.]]
  74 ]
  75
  76 [heading Expression Semantics]
  77
  78 Semantics of an expression is defined only where it differs from, or is
  79 not defined in __primitive_generator_concept__.
  80
  81 [table
  82     [[Expression]           [Description]]
  83     [[`stream`]             [Call the streaming `operator<<()` for the type
  84                              of the mandatory attribute. The output emitted
  85                              by this operator will be the result of the
  86                              `stream` generator. This generator never fails
  87                              (unless the underlying output stream reports an
  88                              error). The character type of the I/O ostream
  89                              is assumed to be `char`.]]
  90     [[`stream(s)`]          [Call the streaming `operator<<()` for the type
  91                              of the immediate value `s`. The output emitted
  92                              by this operator will be the result of the
  93                              `stream` generator. This generator never fails
  94                              (unless the underlying output stream reports an
  95                              error). The character type of the I/O ostream
  96                              is assumed to be `char`.]]
  97     [[`wstream`]            [Call the streaming `operator<<()` for the type
  98                              of the mandatory attribute. The output emitted
  99                              by this operator will be the result of the
 100                              `stream` generator. This generator never fails
 101                              (unless the underlying output stream reports an
 102                              error). The character type of the I/O ostream
 103                              is assumed to be `wchar_t`.]]
 104     [[`wstream(s)`]         [Call the streaming `operator<<()` for the type
 105                              of the immediate value `s`. The output emitted
 106                              by this operator will be the result of the
 107                              `stream` generator. This generator never fails
 108                              (unless the underlying output stream reports an
 109                              error). The character type of the I/O ostream
 110                              is assumed to be `wchar_t`.]]
 111 ]
 112
 113 All generators listed in the table above are predefined specializations of the
 114 `stream_generator<Char>` basic stream generator type described below. It is
 115 possible to directly use this type to create stream generators using an
 116 arbitrary underlying character type.
 117
 118 [table
 119     [[Expression]       [Semantics]]
 120     [
 121 [``stream_generator<
 122     Char
 123 >()``]                      [Call the streaming `operator<<()` for the type
 124                              of the mandatory attribute. The output emitted
 125                              by this operator will be the result of the
 126                              `stream` generator. This generator never fails
 127                              (unless the underlying output stream reports an
 128                              error). The character type of the I/O ostream
 129                              is assumed to be `Char`]]
 130     [
 131 [``stream_generator<
 132     Char
 133 >()(s)``]                   [Call the streaming `operator<<()` for the type
 134                              of the immediate value `s`. The output emitted
 135                              by this operator will be the result of the
 136                              `stream` generator. This generator never fails
 137                              (unless the underlying output stream reports an
 138                              error). The character type of the I/O ostream
 139                              is assumed to be `Char`.]]
 140 ]
 141
 142 [heading Additional Requirements]
 143
 144 All of the stream generators listed above require the type of the value to
 145 generate output for (either the immediate value or the associated attribute) to
 146 implement a streaming operator conforming to the usual I/O streams conventions
 147 (where `attribute_type` is the type of the value to generate output for):
 148
 149     template <typename Ostream>
 150     Ostream& operator<< (Ostream& os, attribute_type const& attr)
 151     {
 152         // type specific output generation
 153         return os;
 154     }
 155
 156 This operator will be called by the stream generators to gather the output for
 157 the attribute of type `attribute_type`. All data streamed into the given
 158 `Ostream` will end up being generated by the corresponding stream generator
 159 instance.
 160
 161 [note   If the `stream` generator is invoked inside a [karma_format `format`]
 162         (or [karma_format `format_delimited`]) stream manipulator the `Ostream`
 163         passed to the `operator<<()` will have registered (imbued) the same
 164         standard locale instance as the stream the [karma_format `format`] (or
 165         [karma_format `format_delimited`]) manipulator has been used with.
 166         This ensures all facets registered (imbued) with the original I/O
 167         stream object are used during output generation.
 168 ]
 169
 170 [heading Attributes]
 171
 172 [table
 173     [[Expression]           [Attribute]]
 174     [[`stream`]             [`hold_any`, attribute is mandatory (otherwise compilation will fail)]]
 175     [[`stream(s)`]          [__unused__]]
 176     [[`wstream`]            [`whold_any`, attribute is mandatory (otherwise compilation will fail)]]
 177     [[`wstream(s)`]         [__unused__]]
 178     [[`stream_generator<Char>()`]    [`basic_hold_any<Char>`, attribute is mandatory (otherwise compilation will fail)]]
 179     [[`stream_generator<Char>()(s)`] [__unused__]]
 180 ]
 181
 182 [important The attribute type `hold_any` exposed by some of the stream
 183            generators is semantically and syntactically equivalent to
 184            the type implemented by __boost_any__. It has been added to /Spirit/
 185            as it has better a performance and a smaller footprint if compared to
 186            __boost_any__.
 187 ]
 188
 189 [note  In addition to their usual attribute of type `Attrib` all listed generators
 190        accept an instance of a `boost::optional<Attrib>` as well. If the
 191        `boost::optional<>` is initialized (holds a value) the generators behave
 192        as if their attribute was an instance of `Attrib` and emit the value stored
 193        in the `boost::optional<>`. Otherwise the generators will fail.]
 194
 195 [heading Complexity]
 196
 197 [:O(N), where N is the number of characters emitted by the stream generator]
 198
 199 [heading Example]
 200
 201 [note The test harness for the example(s) below is presented in the
 202       __karma_basics_examples__ section.]
 203
 204 Some includes:
 205
 206 [reference_karma_includes]
 207
 208 Some using declarations:
 209
 210 [reference_karma_using_declarations_stream]
 211
 212 And a class definition used in the examples:
 213
 214 [reference_karma_complex]
 215 [reference_karma_stream_complex]
 216
 217 Basic usage of `stream` generators:
 218
 219 [reference_karma_stream]
 220
 221 [endsect]
 222
 223 [endsect]