[/
    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)];
  };

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]