Merge lexical_cast library from trunk:

* multiple optimizations and bugfixes for boost::iterator_range (refs #6786, refs #6430, refs #6663)
* documentation update
* new Unicode characters support updated
* much more tests, removed incorrect tests

[SVN r78059]

doc/lexical_cast.qbk

@@ -97,7 +97,21 @@ The requirements on the argument and result types are:
 * 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`
+* `boost::iterator_range<WideCharPtr>`, where `WideCharPtr` is a pointer to wide-character or pointer to const wide-character
+
+[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:
+`` 
+    std::cout 
+        << 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.
 [endsect]
@@ -115,6 +129,7 @@ Exception used to indicate runtime lexical_cast failure.
 
 [endsect]
 
+[/ Commenting out bad advise (this will break the ability to get correct function pointers via &lexical_cast<Target, Source>)
 [section Tuning classes for fast lexical conversions]
 Because of `boost::lexical_cast` optimizations for `boost::iterator_range<character_type*>`, it is possibile to make very fast lexical conversions for non zero terminated strings, substrings and user-defined classes.
 
@@ -145,9 +160,9 @@ Consider the following example:
 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`:
 ``
@@ -162,7 +177,7 @@ namespace boost {
 ``
 Now `boost::lexical_cast<some_type>(example_class_instance)` conversions won't copy data and construct heavy STL stream objects. See [link boost_lexical_cast.performance Performance] section for info on `boost::iterator_range` conversion performance.
 [endsect]
-
+]
 
 [section Frequently Asked Questions]