From e8954f3868abe71e769c1de7d7519a8bb53bc460 Mon Sep 17 00:00:00 2001
From: Antony Polukhin <antoshkka@gmail.com>
Date: Sat, 4 Jan 2014 20:26:19 +0400
Subject: [PATCH] Added docs for try_lexical_convert

---
 doc/lexical_cast.qbk | 48 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 47 insertions(+), 1 deletion(-)

diff --git a/doc/lexical_cast.qbk b/doc/lexical_cast.qbk
index 2006405..11f119d 100644
--- a/doc/lexical_cast.qbk
+++ b/doc/lexical_cast.qbk
@@ -68,7 +68,17 @@ Library features defined in [@boost:boost/lexical_cast.hpp boost/lexical_cast.hp
 
         template <typename Target>
           Target lexical_cast(const AnyCharacterType* chars, std::size_t count);
-    }
+
+        namespace conversion
+        {
+            template<typename Target, typename Source>
+                bool try_lexical_convert(Source&& arg, Target& result);
+
+            template <typename AnyCharacterType, typename Target>
+                bool try_lexical_convert(const AnyCharacterType* chars, std::size_t count, Target& result);
+
+        } // namespace conversion
+    } // namespace boost
 ``
 
 [section lexical_cast]
@@ -122,6 +132,38 @@ Where a higher degree of control is required over conversions, `std::stringstrea
 Exception used to indicate runtime lexical_cast failure.
 [endsect]
 
+[section try_lexical_convert]
+`boost::lexical_cast` remains the main interface for lexical conversions. It must be used by default in most cases. However
+some developers wish to make their own conversion functions, reusing all the optimizations of `boost::lexical_cast`. That's
+where the `boost::conversion::try_lexical_convert` function steps in.
+
+`try_lexical_convert` returns `true` if conversion succeeded, otherwise returns `false`. If conversion failed and `false` was returned,
+state of `result` output variable is undefined.
+
+Actually, `boost::lexical_cast` is implemented using `try_lexical_convert`:
+``
+    template <typename Target, typename Source>
+    inline Target lexical_cast(const Source &arg)
+    {
+        Target result;
+
+        if (!conversion::try_lexical_convert(arg, result))
+            throw bad_lexical_cast();
+
+        return result;
+    }
+``
+
+`try_lexical_convert` relaxes the requirements for `Target` type. `Target` must not be CopyConstructible or DefaultConstructible.
+
+Following requirements for `Target` and `Source` remain:
+
+* Source must be OutputStreamable, meaning that an `operator<<` is defined that takes a `std::ostream` or `std::wostream` object on the left hand side and an instance of the argument type on the right.
+* Target must be InputStreamable, meaning that an `operator>>` is defined that takes a `std::istream` or `std::wistream` object on the left hand side and an instance of the result type on the right.
+
+[endsect]
+
+
 [endsect]
 
 [section Frequently Asked Questions]
@@ -194,6 +236,10 @@ limitation of compiler options that you use.
 
 [section Changes]
 
+* [*boost 1.56.0 :]
+
+    * Added `try_lexical_convert` functions.
+
 * [*boost 1.54.0 :]
 
     * Fix some issues with `boost::int128_type` and `boost::uint128_type` conversions. Notify user at compile time