| [/ |
| Boost.Optional |
| |
| Copyright (c) 2003-2007 Fernando Luis Cacciola Carballal |
| Copyright (c) 2014 Andrzej Krzemienski |
| |
| Distributed under the Boost Software License, Version 1.0. |
| (See accompanying file LICENSE_1_0.txt or copy at |
| http://www.boost.org/LICENSE_1_0.txt) |
| ] |
| |
| [section Motivation] |
| |
| Consider these functions which should return a value but which might not have |
| a value to return: |
| |
| * (A) `double sqrt(double n );` |
| * (B) `char get_async_input();` |
| * (C) `point polygon::get_any_point_effectively_inside();` |
| |
| There are different approaches to the issue of not having a value to return. |
| |
| A typical approach is to consider the existence of a valid return value as a |
| postcondition, so that if the function cannot compute the value to return, it |
| has either undefined behavior (and can use assert in a debug build) or uses a |
| runtime check and throws an exception if the postcondition is violated. This |
| is a reasonable choice for example, for function (A), because the lack of a |
| proper return value is directly related to an invalid parameter (out of domain |
| argument), so it is appropriate to require the callee to supply only parameters |
| in a valid domain for execution to continue normally. |
| |
| However, function (B), because of its asynchronous nature, does not fail just |
| because it can't find a value to return; so it is incorrect to consider such |
| a situation an error and assert or throw an exception. This function must |
| return, and somehow, must tell the callee that it is not returning a meaningful |
| value. |
| |
| A similar situation occurs with function (C): it is conceptually an error to |
| ask a ['null-area] polygon to return a point inside itself, but in many |
| applications, it is just impractical for performance reasons to treat this as |
| an error (because detecting that the polygon has no area might be too expensive |
| to be required to be tested previously), and either an arbitrary point |
| (typically at infinity) is returned, or some efficient way to tell the callee |
| that there is no such point is used. |
| |
| There are various mechanisms to let functions communicate that the returned |
| value is not valid. One such mechanism, which is quite common since it has |
| zero or negligible overhead, is to use a special value which is reserved to |
| communicate this. Classical examples of such special values are `EOF`, |
| `string::npos`, points at infinity, etc... |
| |
| When those values exist, i.e. the return type can hold all meaningful values |
| ['plus] the ['signal] value, this mechanism is quite appropriate and well known. |
| Unfortunately, there are cases when such values do not exist. In these cases, |
| the usual alternative is either to use a wider type, such as `int` in place of |
| `char`; or a compound type, such as `std::pair<point,bool>`. |
| |
| Returning a `std::pair<T,bool>`, thus attaching a boolean flag to the result |
| which indicates if the result is meaningful, has the advantage that can be |
| turned into a consistent idiom since the first element of the pair can be |
| whatever the function would conceptually return. For example, the last two |
| functions could have the following interface: |
| |
| std::pair<char,bool> get_async_input(); |
| std::pair<point,bool> polygon::get_any_point_effectively_inside(); |
| |
| These functions use a consistent interface for dealing with possibly nonexistent |
| results: |
| |
| std::pair<point,bool> p = poly.get_any_point_effectively_inside(); |
| if ( p.second ) |
| flood_fill(p.first); |
| |
| However, not only is this quite a burden syntactically, it is also error prone |
| since the user can easily use the function result (first element of the pair) |
| without ever checking if it has a valid value. |
| |
| Clearly, we need a better idiom. |
| |
| [endsect] |