add subtree-ish sources for 12.0.3

[ceph.git] / ceph / src / boost / libs / convert / doc / introduction.qbk

diff --git a/ceph/src/boost/libs/convert/doc/introduction.qbk b/ceph/src/boost/libs/convert/doc/introduction.qbk
new file mode 100644 (file)
index 0000000..348fd28
--- /dev/null
+++ b/ceph/src/boost/libs/convert/doc/introduction.qbk
@@ -0,0 +1,59 @@
+[/
+  Copyright (c) Vladimir Batov 2009-2016
+  Distributed under the Boost Software License, Version 1.0.
+  See copy at http://www.boost.org/LICENSE_1_0.txt.
+]
+
+[section Introduction]
+
+['Boost.Convert] builds on the `boost::lexical_cast` experience and takes those type conversion\/transformation-related ideas further
+
+* to be applicable to a wider range of conversion-related deployment scenarios,
+* to provide a more flexible, configurable and extendible type-conversion framework,
+* to provide generic consistent behavior,
+* to ['unify and to uniformly deploy] various conversion facilities ['through one consistent interface].
+
+['Boost.Convert] provides new and familiar conversion\/transformation-related functionality such as:
+
+* means to deploy types that do not meet the [@http://en.cppreference.com/w/cpp/concept/DefaultConstructible ['Default Constructibility]] requirement;
+* four types of the conversion-failure ['detection]:
+    * as part of the same process flow -- basic and generic;
+    * as a branched process flow -- exception-based and function-based;
+* the choice of immediate or delayed exception-throwing and non-throwing conversion-failure ['processing];
+* flexibility of conversion-failure ['processing] via:
+    * an exception thrown;
+    * the fallback value returned;
+    * the fallback function called;
+* support for standard algorithms.
+
+['Boost.Convert] consists of two components:
+
+* the `boost::convert()` interface;
+* an extendible collection of pluggable converters.
+
+The `boost::convert()` interface
+
+* advertises, provides and ensures certain ['consistent behavior];
+* unifies and provides ['one consistent interface] to various conversion facilities.
+
+The collection of pluggable converters is independent of the `boost::convert()` API facade and is designed to be ['extendible] and extended over time. Currently the following converters are provided:
+
+* `boost::lexical_cast`-based,
+* `printf/scanf`-based,
+* `strtol`-inspired,
+* `std::stringstream`-based,
+* `boost::spirit`-based.
+
+The converters provide new and familiar functionality and demonstrate how existing and independent conversion facilities might be incorporated in to the ['Boost.Convert] framework. For example, the `std::stream`-based converter draws on the standard `std::streams` functionality and provides:
+
+* string-to-type and type-to-string conversions;
+* formatting support (`std::ios`-based precision, base, upper/lower-case, scientific, etc.);
+* support for different `locale`s;
+* `char` and `wchar_t` support.
+
+[import ../example/algorithms.cpp]
+
+[algorithm_introduction]
+
+[endsect] [/section Introduction]
+