ceph/src/boost/libs/convert/doc/stream_converter.qbk

   1 [/
   2   Copyright (c) Vladimir Batov 2009-2016
   3   Distributed under the Boost Software License, Version 1.0.
   4   See copy at http://www.boost.org/LICENSE_1_0.txt.
   5 ]
   6
   7 [section:stream_converter ['boost::cnv::stream] Converter]
   8
   9 The purpose of the converter is to provide conversion-related formatting and locale support not available with `boost::lexical_cast`. Advantages of deploying a `std::stream`-based conversion engine are:
  10
  11 * availability and maturity;
  12 * formatting and locale support;
  13 * familiar interface and deployment;
  14 * instant re-use of available standard manipulators (`std::hex`, `std::setprecision`, `std::skipws`, etc.);
  15 * extendibility via custom manipulators (see [@http://www.cecalc.ula.ve/documentacion/tutoriales/PGICDK/doc/pgC++_lib/stdlibug/str_5412.htm Stream Storage for Private Use: iword, pword, and xalloc] by Rogue Wave Software).
  16
  17 The converter might be deployed as follows:
  18
  19 [stream_headers1]
  20 [stream_example1]
  21
  22 [section Formatting Support]
  23
  24 Formatting support is provided by the underlying `std::stringstream`. Consequently, the API heavily borrows formatting metaphors from this underlying component. One such metaphor is the ['manipulator] represented by `std::hex`, `std::dec`, `std::uppercase`, `std::scientific`, etc.
  25
  26 The following code demonstrates how `char` and `wchar_t` strings can be read in the `std::hex` or `std::dec` format:
  27
  28 [stream_example2]
  29
  30 For batch-processing it might be more efficient to configure the converter once:
  31
  32 [stream_example3]
  33
  34 An alternative (generic) formatting interface is currently being extended and explored:
  35
  36 [stream_headers2]
  37 [stream_example4]
  38
  39 is equivalent to the following ['std::manipulator]-based variant:
  40
  41 [stream_example5]
  42
  43 [section Numeric Base]
  44 [stream_using]
  45 [stream_numbase_example1]
  46
  47 A more generic interface is also supported:
  48
  49 [stream_cnv_namespace_shortcut]
  50 [stream_numbase_example2]
  51 [endsect]
  52
  53 [section Field Width, Fill Character and Adjustment]
  54 [stream_width_example]
  55 [endsect]
  56
  57 [section Leading Whitespace Characters]
  58 [stream_using]
  59 [stream_skipws_example]
  60 [endsect]
  61
  62 [section Format of Boolean Values]
  63 [stream_using]
  64 [stream_boolalpha_example]
  65 [endsect]
  66 [endsect]
  67
  68 [section Locale Support]
  69
  70 Locale support is similar to the formatting support as demonstrated by the following example:
  71
  72 [stream_headers2]
  73 [stream_locale_example1]
  74
  75 [endsect]
  76 [section Supported String Types]
  77 [section Wide String]
  78 [wide_stream_numeric_base]
  79 [wide_stream_skipws]
  80 [endsect]
  81
  82 [section Custom String Types]
  83
  84 `boost::cnv::stream` accepts custom string and string-like types as input or output as long as they satisfy certain requirements.
  85
  86 [stream_my_string]
  87
  88 When a string-like type is the source, then it needs to be a ['contiguous sequence] of the corresponding character type (`char` or `wchar_t`) accessible via `begin()` and `end()`.
  89
  90 `std::stringstream` is implemented entirely in terms of `std::basic_streambuf` which, in turn, operates on a ['contiguous character sequence], also called the ['buffer] (see [@http://en.cppreference.com/w/cpp/io/basic_streambuf `std::basic_streambuf`] for details). For efficiency reasons `boost::cnv::stream` uses the provided (read-only) input string as the ['buffer] and, consequently, requires that provided input string to be a contiguous character sequence.
  91
  92 When a string is the target, then the described ['contiguous character sequence] requirement does not apply. Any type that provides
  93
  94  MyType::MyType(char const* beg, char const* end)
  95
  96 constructor can be deployed in type-to-string conversions.
  97
  98 See [link boost_convert.performance.the_bigger_picture The Bigger Picture] chapter for the discussion of potential advantages of deploying custom strings.
  99
 100 [endsect]
 101 [endsect]
 102 [section The ['Default Constructible] Type Requirement]
 103
 104 Due to `std::stream` design it requires an ['initialized] temporary storage of ['TypeOut] type to put the result of the requested conversion to. Conceptually `boost::cnv::cstream` achieves that with:
 105
 106  istream_type& istream = stream_;
 107  TypeOut        result = boost::make_default<TypeOut>();
 108
 109  istream >> result;
 110
 111 The temporary storage `result` is initialized with `boost::make_default()` the default implementation of which is
 112
 113  namespace boost
 114  {
 115     template<typename T> T make_default() { return T(); }
 116  }
 117
 118 Consequently,
 119
 120 [note [*By default] the `boost::cnv::cstream` and `boost::cnv::wstream` converters require the ['TypeOut] type to be [@http://en.cppreference.com/w/cpp/concept/DefaultConstructible ['Default Constructible]].]
 121
 122 That said, a well-designed type (in my opinion, anyway) should only have meaningful and unambiguous constructors... and the default constructor is not always and necessarily one of them. Consider the following as one such example:
 123
 124 [direction_declaration]
 125 [direction_stream_operators]
 126
 127 The `direction` type has no default state. It is not [@http://en.cppreference.com/w/cpp/concept/DefaultConstructible ['Default Constructible]] and, consequently, the following does not compile:
 128
 129  direction dir1 = convert<direction>(str, cnv).value(); // Does not compile
 130  direction dir2 = lexical_cast<direction>(str);         // Does not compile
 131
 132 However, ['Boost.Convert] is able to handle such a type with little help from the user -- the instructions ['how] to create that mentioned temporary storage:
 133
 134 [direction_declaration_make_default]
 135
 136 Now such class can be deployed with `boost::cnv::cstream`:
 137
 138  direction dir1 = convert<direction>(str, cnv).value(); // Compiles
 139  direction dir2 = lexical_cast<direction>(str); // Does not compile
 140
 141 [endsect]
 142 [endsect]
 143
 144