ceph/src/boost/libs/convert/doc/getting_serious.qbk

   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:error_detection Better Error Detection]
   8
   9 [:[*['"Detection is, or ought to be, an exact science, ..." Sir Arthur Conan Doyle]]]
  10
  11 [import ../example/getting_serious.cpp]
  12
  13 [getting_serious_example1]
  14
  15 The code above is straightforward and self-explanatory but, strictly speaking, is not entirely correct as -1 might be the result of a conversion failure or the successful conversion of the "-1" string. Still, in reality "spare" values (outside the valid\/sensible range) are quite often available to indicate conversion failures. If so, such simple deployment might be adequate. Alternatively, it might be not that uncommon to ignore conversion failures altogether and to simply log the failure and to proceed with the supplied fallback value.
  16
  17 Applications outside these mentioned categories still require conversion failure reliably detected and processed accordingly. The `boost::lexical_cast`'s (only) answer is to throw on failure and ['Boost.Convert] supports that behavior as well:
  18
  19 [getting_serious_example2]
  20
  21 However, to cater for a wider range of program-flow variations, ['Boost.Convert] adds the flexibility of
  22
  23 * delaying the moment when the conversion-failure exception is actually thrown or
  24 * avoiding the exception altogether.
  25
  26 [getting_serious_example3]
  27
  28 Here [@boost:/libs/optional/index.html `boost::optional`] steps forward as the actual type returned by `boost::convert()` which until now we avoided by immediately calling its value-accessor methods:
  29
  30  int i1 = boost::convert<int>(str1, cnv).value();
  31  int i2 = boost::convert<int>(str2, cnv).value_or(fallback_value);
  32  int i3 = boost::convert<int>(str3, cnv).value_or_eval(fallback_function);
  33
  34 [note One notable advantage of `value_or_eval()` over `value_or()` is that the actual calculation of the `fallback_value` is delayed and conditional on the success or failure of the conversion.]
  35
  36 From the user perspective, `boost::lexical_cast` processes failure in a somewhat one-dimensional non-negotiable manner. `boost::convert` takes a more flexible approach. It provides choice and leaves the decision to the user. It is not unimaginable that, on the library level, propagating the conversion-failure exception might be the only available option. On the application level though, in my personal experience, the choice has overwhelmingly been to handle conversion failures ['locally], i.e. to avoid conversion-failure exception propagation or, better still, to avoid exceptions altogether with program flows similar to:
  37
  38 [getting_serious_example4]
  39
  40 and
  41
  42 [getting_serious_example5]
  43 [getting_serious_example6]
  44
  45 [endsect] [/section:error_detection Better Error Detection]
  46
  47
  48