1<?xml version="1.0" encoding="UTF-8"?> 2<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.1//EN" 3"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> 4<section id="safenumerics.checked_result"> 5 <title>checked_result<R></title> 6 7 <?dbhtml stop-chunking?> 8 9 <section> 10 <title>Description</title> 11 12 <para>checked_result is a special kind of variant class designed to hold 13 the result of some operation. It can hold either the result of the 14 operation or information on why the operation failed to produce a valid 15 result. It is similar to other types proposed for and/or included to the 16 C++ standard library or Boost such as<code> expected</code>, 17 <code>variant</code>, <code>optional</code> and <code>outcome</code>. In 18 some circumstances it may be referred to as a "monad".</para> 19 20 <para><itemizedlist> 21 <listitem> 22 <para>All instances of <code>checked_result<R></code> are 23 immutable. That is, once constructed, they cannot be altered.</para> 24 </listitem> 25 26 <listitem> 27 <para>There is no default constructor.</para> 28 </listitem> 29 30 <listitem> 31 <para><code>checked_result<R></code> is never empty.</para> 32 </listitem> 33 34 <listitem> 35 <para>Binary operations supported by type R are guaranteed to be 36 supported by checked_result<R>.</para> 37 </listitem> 38 39 <listitem> 40 <para>Binary operations can be invoked on a pair of 41 <code>checked_result<R></code> instances if and only if the 42 underlying type (R) is identical for both instances. They will 43 return a value of type <code>checked_result<R></code>.</para> 44 </listitem> 45 46 <listitem> 47 <para>Unary operations can be invoked on 48 <code>checked_result<R></code> instances. They will return a 49 value of type <code>checked_result<R></code>.</para> 50 </listitem> 51 52 <listitem> 53 <para>Comparison operations will return a 54 <code>boost::logic::tribool</code>. Other binary operations will a 55 value of the same type as the arguments.</para> 56 </listitem> 57 </itemizedlist></para> 58 59 <para>Think of <code>checked<R></code> as an "extended" version of R 60 which can hold all the values that R can hold in addition other "special 61 values". For example, consider checked<int>.</para> 62 </section> 63 64 <section> 65 <title>Notation</title> 66 67 <informaltable> 68 <tgroup cols="2"> 69 <colspec align="left" colwidth="1*"/> 70 71 <colspec align="left" colwidth="4*"/> 72 73 <thead> 74 <row> 75 <entry align="left">Symbol</entry> 76 77 <entry align="left">Description</entry> 78 </row> 79 </thead> 80 81 <tbody> 82 <row> 83 <entry><code>R</code></entry> 84 85 <entry>Underlying type</entry> 86 </row> 87 88 <row> 89 <entry><code>r</code></entry> 90 91 <entry>An instance of type R</entry> 92 </row> 93 94 <row> 95 <entry><code>c, c1, c2</code></entry> 96 97 <entry>an instance of checked_result<R></entry> 98 </row> 99 100 <row> 101 <entry><code>t</code></entry> 102 103 <entry>an instance of checked_result<T> for some type T not 104 necessarily the same as R</entry> 105 </row> 106 107 <row> 108 <entry><code>e</code></entry> 109 110 <entry>An instance of type <link 111 linkend="safe_numerics.safe_numerics_error"><code>safe_numerics_error</code></link></entry> 112 </row> 113 114 <row> 115 <entry><code>msg</code></entry> 116 117 <entry>An instance of type const char *</entry> 118 </row> 119 120 <row> 121 <entry><code>OS</code></entry> 122 123 <entry>A type convertible to <link 124 linkend="safe_numerics.safe_numerics_error"><code>std::basic_ostream</code></link></entry> 125 </row> 126 127 <row> 128 <entry><code>os</code></entry> 129 130 <entry>An instance of type convertible to <link 131 linkend="safe_numerics.safe_numerics_error"><code>std::basic_ostream</code></link></entry> 132 </row> 133 </tbody> 134 </tgroup> 135 </informaltable> 136 </section> 137 138 <section> 139 <title>Template Parameters</title> 140 141 <para>R must model the type requirements of <link 142 linkend="safe_numerics.numeric">Numeric</link></para> 143 144 <informaltable> 145 <tgroup cols="2"> 146 <colspec align="left" colwidth="1*"/> 147 148 <colspec align="left" colwidth="4*"/> 149 150 <thead> 151 <row> 152 <entry align="left">Parameter</entry> 153 154 <entry>Description</entry> 155 </row> 156 </thead> 157 158 <tbody> 159 <row> 160 <entry><code>R</code></entry> 161 162 <entry>Underlying type</entry> 163 </row> 164 </tbody> 165 </tgroup> 166 </informaltable> 167 </section> 168 169 <section> 170 <title>Model of</title> 171 172 <para><link linkend="safe_numerics.numeric">Numeric</link></para> 173 </section> 174 175 <section> 176 <title>Valid Expressions</title> 177 178 <para>All expressions are <code>constexpr</code>.</para> 179 180 <para><informaltable> 181 <tgroup cols="3"> 182 <colspec align="left" colwidth="2*"/> 183 184 <colspec align="left" colwidth="1*"/> 185 186 <colspec align="left" colwidth="3*"/> 187 188 <thead> 189 <row> 190 <entry align="left">Expression</entry> 191 192 <entry>Return Type</entry> 193 194 <entry>Semantics</entry> 195 </row> 196 </thead> 197 198 <tbody> 199 <row> 200 <entry><code>checked_result(r)</code></entry> 201 202 <entry><code>checked_result<R></code></entry> 203 204 <entry>constructor with valid instance of R</entry> 205 </row> 206 207 <row> 208 <entry><code>checked_result<R>(t)</code></entry> 209 210 <entry><code>checked_result<R></code></entry> 211 212 <entry>constructor with <code>checked_result<T></code> 213 where T is not R. T must be convertible to R.</entry> 214 </row> 215 216 <row> 217 <entry><code>checked_result(e, msg)</code></entry> 218 219 <entry><code>checked_result<R></code></entry> 220 221 <entry>constructor with error information</entry> 222 </row> 223 224 <row> 225 <entry><code>static_cast<R>(c)</code></entry> 226 227 <entry>R</entry> 228 229 <entry>extract wrapped value - compile time error if not 230 possible</entry> 231 </row> 232 233 <row> 234 <entry><code>static_cast<<code><link 235 linkend="safe_numerics.safe_numerics_error"><code>safe_numerics_error</code></link></code>>(c)</code></entry> 236 237 <entry><link 238 linkend="safe_numerics.safe_numerics_error"><code>safe_numerics_error</code></link></entry> 239 240 <entry>extract wrapped value - may return <link 241 linkend="safe_numerics.safe_numerics_error"><code>safe_numerics_error</code></link><code>::success</code> 242 if there is no error</entry> 243 </row> 244 245 <row> 246 <entry><code>static_cast<const char *>(c)</code></entry> 247 248 <entry><code>const char *</code></entry> 249 250 <entry>returns pointer to the included error message</entry> 251 </row> 252 253 <row> 254 <entry><code>c.exception()</code></entry> 255 256 <entry><code>bool</code></entry> 257 258 <entry>true if <code>checked_result</code> contains an error 259 condition.</entry> 260 </row> 261 262 <row> 263 <entry><code><simplelist> 264 <member>c1 < c2</member> 265 266 <member>c1 >= c2</member> 267 268 <member>c1 > c2</member> 269 270 <member>c1 <= c2</member> 271 272 <member>c1 == c2</member> 273 274 <member>c1 != c2</member> 275 </simplelist></code></entry> 276 277 <entry><code>boost::logic::tribool</code></entry> 278 279 <entry>compare the wrapped values of two checked_result 280 instances. If the values are such that the result of such a 281 comparison cannot be reasonably defined, The result of the 282 comparison is 283 <code>boost::logic::tribool::indeterminant</code>.</entry> 284 </row> 285 286 <row> 287 <entry><code><simplelist> 288 <member>c1 + c2</member> 289 290 <member>c1 - c2</member> 291 292 <member>c1 * c2</member> 293 294 <member>c1 / c2</member> 295 296 <member>c1 % c2</member> 297 298 <member>c1 | c2</member> 299 300 <member>c1 & c2</member> 301 302 <member>c1 ^ c2</member> 303 304 <member>c1 << c2</member> 305 306 <member>c1 >> c2</member> 307 </simplelist></code></entry> 308 309 <entry><code>checked_result<R></code></entry> 310 311 <entry>returns a new instance of 312 <code>checked_result<R>.</code></entry> 313 </row> 314 315 <row> 316 <entry><code><simplelist> 317 <member>os << c</member> 318 </simplelist></code></entry> 319 320 <entry><code>OS</code></entry> 321 322 <entry>writes result to output stream. If the result is an error 323 it writes the string corresponding to the error message. 324 Otherwise, it writes the numeric value resulting from the 325 operation. Returns reference to output stream.</entry> 326 </row> 327 </tbody> 328 </tgroup> 329 </informaltable></para> 330 </section> 331 332 <section> 333 <title>Example of use</title> 334 335 <programlisting><xi:include href="../../example/example20.cpp" 336 parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"/></programlisting> 337 </section> 338 339 <section> 340 <title>See Also</title> 341 342 <para><link 343 linkend="safe_numerics.exception_policy">ExceptionPolicy</link></para> 344 </section> 345 346 <section> 347 <title>Header</title> 348 349 <para><ulink 350 url="../../include/boost/safe_numerics/checked_result.hpp"><code>#include 351 <boost/numeric/safe_numerics/checked_result.hpp></code></ulink></para> 352 353 <para><ulink 354 url="../../include/boost/safe_numerics/checked_result_operations.hpp"><code>#include 355 <boost/numeric/safe_numerics/checked_result_operations.hpp> 356 </code></ulink></para> 357 </section> 358</section> 359