libs/optional/doc/optional.qbk

   1 [library Boost.Optional
   2     [quickbook 1.4]
   3     [authors [Cacciola Carballal, Fernando Luis]]
   4     [copyright 2003-2007 Fernando Luis Cacciola Carballal]
   5     [category miscellaneous]
   6     [id optional]
   7     [dirname optional]
   8     [purpose
   9         Discriminated-union wrapper for optional values
  10     ]
  11     [source-mode c++]
  12     [license
  13 Distributed under the Boost Software License, Version 1.0.
  14 (See accompanying file LICENSE_1_0.txt or copy at
  15 [@http://www.boost.org/LICENSE_1_0.txt])
  16     ]
  17 ]
  18
  19 [/ Macros will be used for links so we have a central place to change them ]
  20
  21
  22 [/ Cited Boost resources ]
  23
  24 [def __BOOST_VARIANT__ [@../../../variant/index.html Boost.Variant]]
  25 [def __BOOST_TRIBOOL__ [@../../../../doc/html/tribool.html boost::tribool]]
  26
  27 [def __OPTIONAL_POINTEE__ [@../../../utility/OptionalPointee.html OptionalPointee]]
  28 [def __COPY_CONSTRUCTIBLE__ [@../../../utility/CopyConstructible.html Copy Constructible]]
  29 [def __FUNCTION_EQUAL_POINTEES__ [@../../../utility/OptionalPointee.html#equal `equal_pointees()`]]
  30 [def __FUNCTION_LESS_POINTEES__ [@../../../utility/OptionalPointee.html#less `less_pointees()`]]
  31
  32 [def __IN_PLACE_FACTORY_HPP__ [@../../../../boost/utility/in_place_factory.hpp in_place_factory.hpp]]
  33 [def __TYPED_IN_PLACE_FACTORY_HPP__ [@../../../../boost/utility/typed_in_place_factory.hpp typed_in_place_factory.hpp]]
  34
  35 [/ Other web resources ]
  36
  37 [def __HASKELL__ [@http://www.haskell.org/ Haskell]]
  38 [def __SGI_DEFAULT_CONSTRUCTIBLE__ [@http://www.sgi.com/tech/stl/DefaultConstructible.html Default Constructible]]
  39
  40
  41 [/ Icons ]
  42
  43 [def __SPACE__ [$images/space.png]]
  44 [def __GO_TO__ [$images/callouts/R.png]]
  45
  46
  47 [section Motivation]
  48
  49 Consider these functions which should return a value but which might not have
  50 a value to return:
  51
  52 * (A) `double sqrt(double n );`
  53 * (B) `char get_async_input();`
  54 * (C) `point polygon::get_any_point_effectively_inside();`
  55
  56 There are different approaches to the issue of not having a value to return.
  57
  58 A typical approach is to consider the existence of a valid return value as a
  59 postcondition, so that if the function cannot compute the value to return, it
  60 has either undefined behavior (and can use assert in a debug build) or uses a
  61 runtime check and throws an exception if the postcondition is violated. This
  62 is a reasonable choice for example, for function (A), because the lack of a
  63 proper return value is directly related to an invalid parameter (out of domain
  64 argument), so it is appropriate to require the callee to supply only parameters
  65 in a valid domain for execution to continue normally.
  66
  67 However, function (B), because of its asynchronous nature, does not fail just
  68 because it can't find a value to return; so it is incorrect to consider such
  69 a situation an error and assert or throw an exception. This function must
  70 return, and somehow, must tell the callee that it is not returning a meaningful
  71 value.
  72
  73 A similar situation occurs with function (C): it is conceptually an error to
  74 ask a ['null-area] polygon to return a point inside itself, but in many
  75 applications, it is just impractical for performance reasons to treat this as
  76 an error (because detecting that the polygon has no area might be too expensive
  77 to be required to be tested previously), and either an arbitrary point
  78 (typically at infinity) is returned, or some efficient way to tell the callee
  79 that there is no such point is used.
  80
  81 There are various mechanisms to let functions communicate that the returned
  82 value is not valid. One such mechanism, which is quite common since it has
  83 zero or negligible overhead, is to use a special value which is reserved to
  84 communicate this. Classical examples of such special values are `EOF`,
  85 `string::npos`, points at infinity, etc...
  86
  87 When those values exist, i.e. the return type can hold all meaningful values
  88 ['plus] the ['signal] value, this mechanism is quite appropriate and well known.
  89 Unfortunately, there are cases when such values do not exist. In these cases,
  90 the usual alternative is either to use a wider type, such as `int` in place of
  91 `char`; or a compound type, such as `std::pair<point,bool>`.
  92
  93 Returning a `std::pair<T,bool>`, thus attaching a boolean flag to the result
  94 which indicates if the result is meaningful, has the advantage that can be
  95 turned into a consistent idiom since the first element of the pair can be
  96 whatever the function would conceptually return. For example, the last two
  97 functions could have the following interface:
  98
  99     std::pair<char,bool> get_async_input();
 100     std::pair<point,bool> polygon::get_any_point_effectively_inside();
 101
 102 These functions use a consistent interface for dealing with possibly inexistent
 103 results:
 104
 105     std::pair<point,bool> p = poly.get_any_point_effectively_inside();
 106     if ( p.second )
 107         flood_fill(p.first);
 108
 109 However, not only is this quite a burden syntactically, it is also error prone
 110 since the user can easily use the function result (first element of the pair)
 111 without ever checking if it has a valid value.
 112
 113 Clearly, we need a better idiom.
 114
 115 [endsect]
 116
 117
 118 [include development.qbk]
 119 [include reference.qbk]
 120 [include examples.qbk]
 121 [include special_cases.qbk]
 122 [include implementation_notes.qbk]
 123 [include dependencies.qbk]
 124 [include acknowledgments.qbk]
 125
 126