[/

Boost.Optional

Copyright (c) 2003-2007 Fernando Luis Cacciola Carballal

Copyright (c) 2024 andrzej Krzemieński

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 Design Goals]

In C++ you can create an automatic object of a scalar type, and manipulate it,

without assigning it the initial value.

{

int i; // indeterminate value

populate(&i);

cout << i;

}

Such an object is said to have ['indeterminate value]. If you subsequently

assign a proper value to the object, all is fine; but if the program tries to

read an indeterminate value, this is ['undefined behavior'], and since C++26

this is ['erroneous behavior].

In any case, the program is now likely to do something else than what the

programmer intended. In case you have some object `i`, and you do not know if it

has an indeterminate value, or a normal, intended, value, there is no way to

check it, because the checking would require reading the value.

This is one of the primary problems that `optional` was intended to address: so

that you may have a type that knows whether it has been assigned a proper value,

and it can tell you that if requested.

In the case of type `int` the internal representation of such a class could be:

class OptionalInt

{

bool _has_value = false;

int _value;

};

In the general case, the internal representation is something equivalent to:

template <typename T>

class Optional

{

bool _has_value = false;

alignas(T) char _value [sizeof(T)];

};

or:

template <typename T>

class Optional

{

bool _has_value = false;

union {

T _value;

DummyType _non_value;

};

};

Next, because we need to pass around these "optional" `int`s as normal `int`s,

like returning them from functions, when copying, we need to copy `_has_value`,

which indicates whether we have the value or not, and, if we do have value, and

only then, to also copy `_value`.

This means that our type requires ['deep copy] semantics.

[note

This is a C++ equivalent of a

[@https://hackage.haskell.org/package/base-4.20.0.1/docs/Data-Maybe.html Maybe]

monad in [@http://www.haskell.org/ Haskell].

]

[endsect]

[section:iface Interface Design]

One part of the interface is for modifying and setting the initial state of

the object. It has to be able to say that

* we want to store a specific value of type `T`,

* we want to store no value.

The default constructor stores no value. Other than that, we require that

the assignment and construction from a `T` reflects the former, while assignment

and construction of a special ['tag] value `none` reflect the latter need.

optional<int> o1; // contains no value

optional<int> o2 = 2; // contains value 2

optional<int> o3 = none; // contains no value

o1 = 1; // assign value 1

o2 = none; // assign a no-value

o3 = {}; // assign a no-value

[heading Inspecting the State]

Inspecting the state of an optional object requires two steps:

* check if we have the value or not,

* if so, read the stored value.

This 'procedure' is characteristic of inspecting pointers in C++, therefore the

pointer-like syntax was chosen to represent this.

void inspect (optional<string> os)

{

if (os) { // contextual conversion to `bool`

read_string(*os); // `operator*` to access the stored value

read_int(os->size()); // `operator->` as shortcut for accessing members

}

}

Also, similarly to pointers, if you access the value when it is not there,

you trigger __UB__.

This library detects and reports it via

[@../../../assert/assert.html `BOOST_ASSERT()`]. This common property of

pointers and `optional<>` has been formalized into a concept __OPTIONAL_POINTEE__.

However, there is also the counter-intuitive part. All pointers embed ['shallow-copy]

semantics: when you copy a pointer, the pointed-to object stays at the same location

and you can access it via either of the pointers. This is unlike optional objects

where the represented value is copied along.

[caution

Optional objects are not pointers.

]

There is a similar difference in relational operations: they compare deeply for

`optional<>`, while they are shallow for pointers.

[note

When you need a deep relational operations that work uniformly for `optional<>`

and pointers in generic contexts, use functions

[@../../../utility/OptionalPointee.html#equal `equal_pointees()`] and

[@../../../utility/OptionalPointee.html#less `less_pointees()`].

]

[endsect]