1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Converters</title> 5<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../index.html" title="Chapter 1. Boost.Convert 2.0"> 8<link rel="up" href="../index.html" title="Chapter 1. Boost.Convert 2.0"> 9<link rel="prev" href="alternative_interface.html" title="Alternative Interface"> 10<link rel="next" href="integration_of_user_types.html" title="Integration of User-Defined Types"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<table cellpadding="2" width="100%"><tr> 14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> 15<td align="center"><a href="../../../../../index.html">Home</a></td> 16<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> 17<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 18<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 19<td align="center"><a href="../../../../../more/index.htm">More</a></td> 20</tr></table> 21<hr> 22<div class="spirit-nav"> 23<a accesskey="p" href="alternative_interface.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="integration_of_user_types.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 27<a name="boost_convert.converters"></a><a class="link" href="converters.html" title="Converters">Converters</a> 28</h2></div></div></div> 29<p> 30 The <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">convert</span><span class="special">()</span></code> 31 API plays its role by providing a <span class="emphasis"><em>uniform interface</em></span> and 32 ensuring <span class="emphasis"><em>consistent behavior</em></span>. However, it is the respective 33 converter which does the hard work of actual type conversion/transformation. 34 </p> 35<p> 36 <span class="emphasis"><em>Boost.Convert</em></span> design reflects the fact that no one converter 37 is to satisfy all imaginable conversion/transformation-related user requirements. 38 Consequently, <span class="emphasis"><em>extendibility</em></span> and <span class="emphasis"><em>converter pluggability</em></span> 39 are important properties of <span class="emphasis"><em>Boost.Convert</em></span>. The library 40 provides several converters for common type conversions with varying degrees 41 of formatting support and performance. However, it is an expectation that more 42 generic-purpose and custom-specific converters are to be written and deployed 43 with <span class="emphasis"><em>Boost.Convert</em></span>. 44 </p> 45<p> 46 For a converter to be plugged in to the <span class="emphasis"><em>Boost.Convert</em></span> 47 framework it needs to be a <span class="emphasis"><em>callable</em></span> with one of the signatures: 48 </p> 49<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">TypeOut</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">TypeIn</span><span class="special">></span> 50<span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">TypeIn</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">value_in</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special"><</span><span class="identifier">TypeOut</span><span class="special">>&</span> <span class="identifier">result_out</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> 51 52<span class="keyword">template</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">TypeOut</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">TypeIn</span><span class="special">></span> 53<span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">TypeIn</span> <span class="identifier">value_in</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special"><</span><span class="identifier">TypeOut</span><span class="special">>&</span> <span class="identifier">result_out</span><span class="special">)</span> <span class="keyword">const</span><span class="special">;</span> 54</pre> 55<p> 56 if that is a general-purpose converter capable of handling many types (like 57 string-to-type and type-to-string conversions). Alternatively, a purpose-built 58 custom converter might only care to provide 59 </p> 60<pre class="programlisting"><span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">TypeIn</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special"><</span><span class="identifier">TypeOut</span><span class="special">>&)</span> <span class="keyword">const</span><span class="special">;</span> 61</pre> 62<p> 63 if its sole purpose is to handle one specific conversion/transformation of 64 <span class="emphasis"><em>TypeIn</em></span> to <span class="emphasis"><em>TypeOut</em></span>. For example, a 65 converter from the operating-system-specific MBCS string format to the UCS-2 66 or UCS-4 (depending on <code class="computeroutput"><span class="keyword">wchar_t</span></code> 67 size) might be one such example: 68 </p> 69<pre class="programlisting"><span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="keyword">const</span><span class="special">&,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">wstring</span><span class="special">>&)</span> <span class="keyword">const</span><span class="special">;</span> 70</pre> 71<p> 72 Alternatively again, an ad-hoc in-place <span class="emphasis"><em>callable</em></span> might 73 be provided as a converter. For example, 74 </p> 75<p> 76</p> 77<pre class="programlisting"><span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">;</span> 78<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">lexical_cast</span><span class="special">;</span> 79<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">convert</span><span class="special">;</span> 80</pre> 81<p> 82 </p> 83<p> 84</p> 85<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">v03</span> <span class="special">=</span> <span class="identifier">convert</span><span class="special"><</span><span class="keyword">int</span><span class="special">>(</span><span class="identifier">str</span><span class="special">,</span> 86 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">assign</span><span class="special"><</span><span class="keyword">int</span><span class="special">>,</span> <span class="identifier">_2</span><span class="special">,</span> 87 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bind</span><span class="special">(</span><span class="identifier">lexical_cast</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">string</span><span class="special">>,</span> <span class="identifier">_1</span><span class="special">))).</span><span class="identifier">value_or</span><span class="special">(-</span><span class="number">1</span><span class="special">);</span> 88</pre> 89<p> 90 </p> 91<p> 92 or an old-fashioned function: 93 </p> 94<p> 95</p> 96<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">plain_old_func</span><span class="special">(</span><span class="identifier">string</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">value_in</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special"><</span><span class="keyword">int</span><span class="special">>&</span> <span class="identifier">value_out</span><span class="special">)</span> 97</pre> 98<p> 99 </p> 100<p> 101</p> 102<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">v01</span> <span class="special">=</span> <span class="identifier">convert</span><span class="special"><</span><span class="keyword">int</span><span class="special">>(</span><span class="identifier">str</span><span class="special">,</span> <span class="identifier">plain_old_func</span><span class="special">).</span><span class="identifier">value_or</span><span class="special">(-</span><span class="number">1</span><span class="special">);</span> 103</pre> 104<p> 105 </p> 106<p> 107 With regard to converters the <span class="emphasis"><em>Boost.Convert</em></span> framework 108 has been designed with the following requirement in mind: 109 </p> 110<div class="note"><table border="0" summary="Note"> 111<tr> 112<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td> 113<th align="left">Note</th> 114</tr> 115<tr><td align="left" valign="top"><p> 116 Converters shall be independent from and must not rely on the <span class="emphasis"><em>Boost.Convert</em></span> 117 infrastructure. 118 </p></td></tr> 119</table></div> 120<h4> 121<a name="boost_convert.converters.h0"></a> 122 <span class="phrase"><a name="boost_convert.converters.implicit__emphasis_typein__emphasis__promotions_and_conversions"></a></span><a class="link" href="converters.html#boost_convert.converters.implicit__emphasis_typein__emphasis__promotions_and_conversions">Implicit 123 <span class="emphasis"><em>TypeIn</em></span> Promotions and Conversions</a> 124 </h4> 125<p> 126 It is worth remembering that <span class="emphasis"><em>TypeIn</em></span> in the signature should 127 be interpreted in the context of the potential implicit type promotions and 128 conversions allowed <span class="emphasis"><em>by the language</em></span>. For example, depending 129 on the context the <code class="computeroutput"><span class="identifier">take_double</span></code> 130 and <code class="computeroutput"><span class="identifier">take_int</span></code> converters below 131 might not do what is expected of them due to implicit <span class="emphasis"><em>int-to-double</em></span> 132 promotion and value-destroying <span class="emphasis"><em>double-to-int</em></span> conversion 133 applied <span class="emphasis"><em>by the compiler</em></span>: 134 </p> 135<p> 136</p> 137<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">take_double</span> <span class="special">{</span> <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span><span class="keyword">double</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special"><</span><span class="identifier">string</span><span class="special">>&)</span> <span class="keyword">const</span> <span class="special">{}};</span> 138<span class="keyword">struct</span> <span class="identifier">take_int</span> <span class="special">{</span> <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special"><</span><span class="identifier">string</span><span class="special">>&)</span> <span class="keyword">const</span> <span class="special">{}};</span> 139</pre> 140<p> 141 </p> 142<p> 143</p> 144<pre class="programlisting"><span class="identifier">convert</span><span class="special"><</span><span class="identifier">string</span><span class="special">>(</span><span class="number">11</span><span class="special">,</span> <span class="identifier">take_double</span><span class="special">());</span> <span class="comment">// Compiler applies int-to-double promotion to call the converter.</span> 145<span class="identifier">convert</span><span class="special"><</span><span class="identifier">string</span><span class="special">>(</span><span class="number">11.23</span><span class="special">,</span> <span class="identifier">take_int</span><span class="special">());</span> <span class="comment">// Compiler applies double-to-int implicit truncation.</span> 146</pre> 147<p> 148 </p> 149<p> 150 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">convert</span><span class="special">()</span></code> 151 API does not modify <span class="emphasis"><em>TypeIn</em></span> or interpret it in any way. 152 The passed-in value and its type are delivered to the underlying converter 153 as-is. Consequently, if potential implicit type promotions and conversions 154 are not desirable, then it is the converter's responsibility to address that 155 issue. For example, one way to disable implicit conversions might be: 156 </p> 157<p> 158</p> 159<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">double_only</span> 160<span class="special">{</span> 161 <span class="comment">// Declared for all types.</span> 162 <span class="keyword">template</span><span class="special"><</span><span class="keyword">typename</span> <span class="identifier">TypeIn</span><span class="special">></span> <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">TypeIn</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special"><</span><span class="identifier">string</span><span class="special">>&)</span> <span class="keyword">const</span><span class="special">;</span> 163<span class="special">};</span> 164 165<span class="comment">// Defined only for certain types.</span> 166<span class="keyword">template</span><span class="special"><></span> <span class="keyword">void</span> <span class="identifier">double_only</span><span class="special">::</span><span class="keyword">operator</span><span class="special">()<</span><span class="keyword">double</span><span class="special">>(</span><span class="keyword">double</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special"><</span><span class="identifier">string</span><span class="special">>&)</span> <span class="keyword">const</span> <span class="special">{}</span> 167</pre> 168<p> 169 </p> 170<p> 171</p> 172<pre class="programlisting"> <span class="identifier">convert</span><span class="special"><</span><span class="identifier">string</span><span class="special">>(</span><span class="number">11.23</span><span class="special">,</span> <span class="identifier">double_only</span><span class="special">());</span> <span class="comment">// Fine.</span> 173<span class="comment">// convert<string>(11, double_only()); // Fails: undefined reference to double_only::operator()<int></span> 174</pre> 175<p> 176 </p> 177</div> 178<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 179<td align="left"></td> 180<td align="right"><div class="copyright-footer">Copyright © 2009-2016 Vladimir Batov<p> 181 Distributed under the Boost Software License, Version 1.0. See copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>. 182 </p> 183</div></td> 184</tr></table> 185<hr> 186<div class="spirit-nav"> 187<a accesskey="p" href="alternative_interface.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="integration_of_user_types.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 188</div> 189</body> 190</html> 191
