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:converters Converters] 8 9[import ../test/callable.cpp] 10 11The `boost::convert()` API plays its role by providing a ['uniform interface] and ensuring ['consistent behavior]. However, it is the respective converter which does the hard work of actual type conversion\/transformation. 12 13['Boost.Convert] design reflects the fact that no one converter is to satisfy all imaginable conversion\/transformation-related user requirements. Consequently, ['extendibility] and ['converter pluggability] are important properties of ['Boost.Convert]. The library provides several converters for common type conversions with varying degrees of formatting support and performance. However, it is an expectation that more generic-purpose and custom-specific converters are to be written and deployed with ['Boost.Convert]. 14 15For a converter to be plugged in to the ['Boost.Convert] framework it needs to be a ['callable] with one of the signatures: 16 17 template<typename TypeOut, typename TypeIn> 18 void operator()(TypeIn const& value_in, boost::optional<TypeOut>& result_out) const; 19 20 template<typename TypeOut, typename TypeIn> 21 void operator()(TypeIn value_in, boost::optional<TypeOut>& result_out) const; 22 23if that is a general-purpose converter capable of handling many types (like string-to-type and type-to-string conversions). Alternatively, a purpose-built custom converter might only care to provide 24 25 void operator()(TypeIn const&, boost::optional<TypeOut>&) const; 26 27if its sole purpose is to handle one specific conversion\/transformation of ['TypeIn] to ['TypeOut]. For example, a converter from the operating-system-specific MBCS string format to the UCS-2 or UCS-4 (depending on `wchar_t` size) might be one such example: 28 29 void operator()(std::string const&, boost::optional<std::wstring>&) const; 30 31Alternatively again, an ad-hoc in-place ['callable] might be provided as a converter. For example, 32 33[getting_started_using] 34[callable_example3] 35 36or an old-fashioned function: 37 38[callable_example1] 39[callable_example2] 40 41With regard to converters the ['Boost.Convert] framework has been designed with the following requirement in mind: 42 43[note Converters shall be independent from and must not rely on the ['Boost.Convert] infrastructure.] 44 45[heading Implicit ['TypeIn] Promotions and Conversions] 46 47It is worth remembering that ['TypeIn] in the signature should be interpreted in the context of the potential implicit type promotions and conversions allowed ['by the language]. For example, depending on the context the `take_double` and `take_int` converters below might not do what is expected of them due to implicit ['int-to-double] promotion and value-destroying ['double-to-int] conversion applied ['by the compiler]: 48 49[callable_example4] 50[callable_example5] 51 52`boost::convert()` API does not modify ['TypeIn] or interpret it in any way. The passed-in value and its type are delivered to the underlying converter as-is. Consequently, if potential implicit type promotions and conversions are not desirable, then it is the converter's responsibility to address that issue. For example, one way to disable implicit conversions might be: 53 54[callable_example6] 55[callable_example7] 56 57[endsect] 58 59