]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 | ||
11 | The `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]. ['Boost.Convert] 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 | ||
15 | For 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 | ||
23 | if 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 | ||
27 | if 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 | ||
31 | Alternatively again, an ad-hoc in-place ['callable] might be provided as a converter. For example, | |
32 | ||
33 | [getting_started_using] | |
34 | [callable_example3] | |
35 | ||
36 | or an old-fashioned function: | |
37 | ||
38 | [callable_example1] | |
39 | [callable_example2] | |
40 | ||
41 | With regard to converters the ['Boost.Convert] framework has been designed with the following requirements 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 | ||
47 | It 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]. 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 |