Subject: [Boost-commit] svn:boost r78044 - trunk/libs/conversion/doc
Date: 2012-04-17 12:27:51
Date: 2012-04-17 12:27:50 EDT (Tue, 17 Apr 2012)
New Revision: 78044
Update documentation ( more info about stream character type detection + warn about new unicode types support; refs #6786, refs #6663)
Text files modified:
trunk/libs/conversion/doc/lexical_cast.qbk | 22 ++++++++++++++++++----
1 files changed, 18 insertions(+), 4 deletions(-)
--- trunk/libs/conversion/doc/lexical_cast.qbk (original)
+++ trunk/libs/conversion/doc/lexical_cast.qbk 2012-04-17 12:27:50 EDT (Tue, 17 Apr 2012)
@@ -97,7 +97,21 @@
* Target is CopyConstructible [20.1.3].
* Target is DefaultConstructible, meaning that it is possible to default-initialize an object of that type [8.5, 20.1.4].
-The character type of the underlying stream is assumed to be char unless either the Source or the Target requires wide-character streaming, in which case the underlying stream uses `wchar_t`. Source types that require wide-character streaming are `wchar_t`, `wchar_t *`, and `std::wstring`. Target types that require wide-character streaming are `wchar_t` and `std::wstring`.
+The character type of the underlying stream is assumed to be `char` unless either the `Source` or the `Target` requires wide-character streaming, in which case the underlying stream uses `wchar_t`, `char16_t` or `char32_t`. Wide-character streaming is currently detected for:
+* Single character: `wchar_t`, `char16_t`, `char32_t`
+* Arrays of characters: `wchar_t *`, `char16_t *`, `char32_t *`, `const wchar_t *`, `const char16_t *`, `const char32_t *`
+* Strings: `std::basic_string`, `boost::containers::basic_string`
+* Character ranges: `boost::iterator_range`, `boost::iterator_range`
+[important Many compilers and runtime libraries fail to make conversions using new Unicode characters. Make shure that the following code compiles and outputs nonzero values, before using new types:
+ << booat::lexical_cast<std::u32string>(1.0).size()
+ << " "
+ << booat::lexical_cast<std::u16string>(1.0).size();
Where a higher degree of control is required over conversions, `std::stringstream` and `std::wstringstream` offer a more appropriate path. Where non-stream-based conversions are required, `lexical_cast` is the wrong tool for the job and is not special-cased for such scenarios.
@@ -146,9 +160,9 @@
This is a good generic solution for most use cases.
But we can make it even faster for some performance critical applications. During conversion, we loose speed at:
-* `std::ostream` construction (it makes some heap allocations)
-* `operator <<` (it copyies one by one all the symbols to an instance of `std::ostream`)
-* `std::ostream` destruction (it makes some heap deallocations)
+ * `std::ostream` construction (it makes some heap allocations)
+ * `operator <<` (it copyies one by one all the symbols to an instance of `std::ostream`)
+ * `std::ostream` destruction (it makes some heap deallocations)
We can avoid all of this, by specifieng an overload for `boost::lexical_cast`:
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk