converters.qbk
3.27 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
[/
Copyright (c) Vladimir Batov 2009-2022
Distributed under the Boost Software License, Version 1.0.
See copy at http://www.boost.org/LICENSE_1_0.txt.
]
[section:converters Converters]
[import ../test/callable.cpp]
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.
['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].
For a converter to be plugged in to the ['Boost.Convert] framework it needs to be a ['callable] with one of the signatures:
template<typename TypeOut, typename TypeIn>
void operator()(TypeIn const& value_in, boost::optional<TypeOut>& result_out) const;
template<typename TypeOut, typename TypeIn>
void operator()(TypeIn value_in, boost::optional<TypeOut>& result_out) const;
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
void operator()(TypeIn const&, boost::optional<TypeOut>&) const;
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:
void operator()(std::string const&, boost::optional<std::wstring>&) const;
Alternatively again, an ad-hoc in-place ['callable] might be provided as a converter. For example,
[getting_started_using]
[callable_example3]
or an old-fashioned function:
[callable_example1]
[callable_example2]
With regard to converters the ['Boost.Convert] framework has been designed with the following requirement in mind:
[note Converters shall be independent from and must not rely on the ['Boost.Convert] infrastructure.]
[heading Implicit ['TypeIn] Promotions and Conversions]
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]. 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]:
[callable_example4]
[callable_example5]
`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:
[callable_example6]
[callable_example7]
[endsect]