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 9The 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 17The converter might be deployed as follows: 18 19[stream_headers1] 20[stream_example1] 21 22[section Formatting Support] 23 24Formatting 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 26The 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 30For batch-processing it might be more efficient to configure the converter once: 31 32[stream_example3] 33 34An alternative (generic) formatting interface is currently being extended and explored: 35 36[stream_headers2] 37[stream_example4] 38 39is 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 47A 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 70Locale 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 88When 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 92When 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 96constructor can be deployed in type-to-string conversions. 97 98See [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 104Due 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 111The 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 118Consequently, 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/named_req/DefaultConstructible ['Default Constructible]].] 121 122That 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 127The `direction` type has no default state. It is not [@http://en.cppreference.com/w/cpp/named_req/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 132However, ['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 136Now 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 145