1[/ 2 Boost.Optional 3 4 Copyright (c) 2003-2007 Fernando Luis Cacciola Carballal 5 Copyright (c) 2014 Andrzej Krzemienski 6 7 Distributed under the Boost Software License, Version 1.0. 8 (See accompanying file LICENSE_1_0.txt or copy at 9 http://www.boost.org/LICENSE_1_0.txt) 10] 11 12[section Motivation] 13 14Consider these functions which should return a value but which might not have 15a value to return: 16 17* (A) `double sqrt(double n );` 18* (B) `char get_async_input();` 19* (C) `point polygon::get_any_point_effectively_inside();` 20 21There are different approaches to the issue of not having a value to return. 22 23A typical approach is to consider the existence of a valid return value as a 24postcondition, so that if the function cannot compute the value to return, it 25has either undefined behavior (and can use assert in a debug build) or uses a 26runtime check and throws an exception if the postcondition is violated. This 27is a reasonable choice for example, for function (A), because the lack of a 28proper return value is directly related to an invalid parameter (out of domain 29argument), so it is appropriate to require the callee to supply only parameters 30in a valid domain for execution to continue normally. 31 32However, function (B), because of its asynchronous nature, does not fail just 33because it can't find a value to return; so it is incorrect to consider such 34a situation an error and assert or throw an exception. This function must 35return, and somehow, must tell the callee that it is not returning a meaningful 36value. 37 38A similar situation occurs with function (C): it is conceptually an error to 39ask a ['null-area] polygon to return a point inside itself, but in many 40applications, it is just impractical for performance reasons to treat this as 41an error (because detecting that the polygon has no area might be too expensive 42to be required to be tested previously), and either an arbitrary point 43(typically at infinity) is returned, or some efficient way to tell the callee 44that there is no such point is used. 45 46There are various mechanisms to let functions communicate that the returned 47value is not valid. One such mechanism, which is quite common since it has 48zero or negligible overhead, is to use a special value which is reserved to 49communicate this. Classical examples of such special values are `EOF`, 50`string::npos`, points at infinity, etc... 51 52When those values exist, i.e. the return type can hold all meaningful values 53['plus] the ['signal] value, this mechanism is quite appropriate and well known. 54Unfortunately, there are cases when such values do not exist. In these cases, 55the usual alternative is either to use a wider type, such as `int` in place of 56`char`; or a compound type, such as `std::pair<point,bool>`. 57 58Returning a `std::pair<T,bool>`, thus attaching a boolean flag to the result 59which indicates if the result is meaningful, has the advantage that can be 60turned into a consistent idiom since the first element of the pair can be 61whatever the function would conceptually return. For example, the last two 62functions could have the following interface: 63 64 std::pair<char,bool> get_async_input(); 65 std::pair<point,bool> polygon::get_any_point_effectively_inside(); 66 67These functions use a consistent interface for dealing with possibly nonexistent 68results: 69 70 std::pair<point,bool> p = poly.get_any_point_effectively_inside(); 71 if ( p.second ) 72 flood_fill(p.first); 73 74However, not only is this quite a burden syntactically, it is also error prone 75since the user can easily use the function result (first element of the pair) 76without ever checking if it has a valid value. 77 78Clearly, we need a better idiom. 79 80[endsect] 81