Class template `optional` is a wrapper for representing 'optional' (or 'nullable') objects who may not (yet) contain a valid value. Optional objects offer full value semantics; they are good for passing by value and usage inside STL containers. This is a header-only library.

[section Problem]

Suppose we want to read a parameter form a config file which represents some integral value, let's call it `"MaxValue"`. It is possible that this parameter is not specified; such situation is no error. It is valid to not specify the parameter and in that case the program is supposed to behave slightly different. Also suppose that any possible value of type `int` is a valid value for `"MaxValue"`, so we cannot jut use `-1` to represent the absence of the parameter in the config file.

[endsect]

[section Solution]

This is how you solve it with `boost::optional`:

#include <boost/optional.hpp>

boost::optional<int> getConfigParam(std::string name); // return either an int or a `not-an-int`

int main()

{

if (boost::optional<int> oi = getConfigParam("MaxValue")) // did I get a real int?

runWithMax(*oi); // use my int

else

runWithNoMax();

}

[endsect]

[include 01_tutorial.qbk]

[include 02_discussion.qbk]

[include 03_development.qbk]

[include 04_reference.qbk]

[include 05_examples.qbk]

[include 10_optional_references.qbk]

[include 11_special_cases.qbk]

[include 90_dependencies.qbk]

[include 91_acknowledgments.qbk]

[/

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 Tutorial]

[section Optional return values]

Let's write and use a converter function that converts an a `std::string` to an `int`. It is possible that for a given string (e.g. `"cat"`) there exist no value of type `int` capable of representing the conversion result. We do not consider such situation an error. We expect that the converter can be used only to check if the conversion is possible. A natural signature for this function can be:

#include <boost/optional.hpp>

boost::optionl<int> convert(const std::string& text);

All necessary functionality can be included with one header `<boost/optional.hpp>`. The above function signature means that the function can either return a value of type `int` or a flag indicating that no value of `int` is available. This does not indicate an error. It is like one additional value of `int`. This is how we can use our function:

const std::string& text = /*... */;

boost::optionl<int> oi = convert(text); // move-construct

if (oi) // contextual conversion to bool

int i = *oi; // operator*

In order to test if `optional` contains a value, we use the contextual conversion to type `bool`. Because of this we can combine the initialization of the optional object and the test into one instruction:

if (boost::optionl<int> oi = convert(text))

int i = *oi;

We extract the contained value with `operator*` (and with `operator->` where it makes sense). An attempt to extract the contained value of an uninitialized optional object is an ['undefined behaviour] (UB). This implementation guards the call with `BOOST_ASSERT`. Therefore you should be sure that the contained value is there before extracting. For instance, the following code is reasonably UB-safe:

int i = *convert("100");

This is because we know that string value `"100"` converts to a valid value of `int`. If you do not like this potential UB, you can use an alternative way of extracting the contained value:

try {

int j = convert(text).value();

}

catch (const boost::bad_optional_access&) {

// deal with it

}

This version throws an exception upon an attempt to access a non-existent contained value. If your way of dealing with the missing value is to use some default, like `0`, there exists a yet another alternative:

int k = convert(text).value_or(0);

This uses the `atoi`-like approach to conversions: if `text` does not represent an integral number just return `0`. Now, let's consider how function `convert` can be implemented.

boost::optionl<int> convert(const std::string& text)

{

std::stringstream s(text);

int i;

if ((s >> i) && s.get() == std::char_traits<char>::eof())

return i;

else

return boost::none;

}

Observe the two return statements. `return i` uses the converting constructor that can create `optional<T>` from `T`. Thus constructed optional object is initialized and its value is a copy of `i`. The other return statement uses another converting constructor from a special tag `boost::none`. It is used to indicate that we want to create an uninitialized optional object.

[endsect]

[section Optional data members]

Suppose we want to implement a ['lazy load] optimization. This is because we do not want to perform an expensive initialization of our `Resource` until (if at all) it is really used. We can do it this way:

class Widget

{

boost::optional<Resource> resource_;

public:

Widget() {}

Resource& getResource() // not thread-safe

{

if (resource_ == boost::none)

resource_.emplace("resource", "arguments");

return *resource_;

}

};

`optional`'s default constructor creates an uninitialized optional. No call to `Resource`'s default constructor is attempted. `Resource` doesn't have to be __SGI_DEFAULT_CONSTRUCTIBLE__. In function `getResource` we first check if `resource_` is initialized. This time we do not use the contextual conversion to `bool`, but a comparison with `boost::none`. These two ways are equivalent. Function `emplace` initializes the optional in-place by perfect-forwarding the arguments to the constructor of `Resource`. No copy- or move-construction is involved here. `Resource` doesn't even have to be `MoveConstructible`.

[note Function `emplace` is only available on compilers that support rvalue references and variadic templates. If your compiler does not support these features and you still need to avoid any move-constructions, use [link boost_optional.in_place_factories In-Place Factories].]

[endsect]

[section Bypassing unnecessary default construction]

Suppose we have class `Date`, which does not have a default constructor: there is no good candidate for a default date. We have a function that returns two dates in form of a `boost::tuple`:

boost::tuple<Date, Date> getPeriod();

In other place we want to use the result of `getPeriod`, but want the two dates to be named: `begin` and `end`. We want to implement something like 'multiple return values':

Date begin, end; // Error: no default ctor!

boost::tie(begin, end) = getPeriod();

The second line works already, this is the capability of Boost.Tuple library, but the first line won't work. We could set some initial invented dates, but it is confusing and may be an unacceptable cost, given that these values will be overwritten in the next line anyway. This is where `optional` can help:

boost::optional<Date> begin, end;

boost::tie(begin, end) = getPeriod();

It works because inside `boost::tie` a move-assignment from `T` is invoked on `optional<T>`, which internally calls a move-constructor of `T`.

[endsect]

[endsect]

[section Discussion]

variable an ['initial value] (through an ['initializer]. (cf. 8.5)).

(cf. 8.5/11).

`T` plus some ['nil_t]—where `nil_t` is some stateless POD—can be modeled in modern

contextual conversion to `bool` to convey the notion of optionality.

template<class... Args> void emplace ( Args...&& args ) ; ``[link reference_optional_emplace __GO_TO__]``

[#reference_optional_emplace]

[: `template<class... Args> void optional<T` ['(not a ref)]`>::emplace( Args...&& args );`]

* [*Requires:] The compiler supports rvalue references and variadic templates.

* [*Effect:] If `*this` is initialized calls `*this = none`.

Then initializes in-place the contained value as if direct-initializing an object

of type `T` with `std::forward<Args>(args)...`.

* [*Postconditions: ] `*this` is [_initialized].

* [*Throws:] Whatever the selected `T`'s constructor throws.

* [*Notes:] `T` need not be `MoveConstructible` or `MoveAssignable`.

* [*Exception Safety:] If an exception is thrown during the initialization of `T`, `*this` is ['uninitialized].

__SPACE__

assert ( true );



[section Optional references]

This library allows the template parameter `T` to be of reference type:

`T&`, and to some extent, `T const&`.

However, since references are not real objects some restrictions apply and

some operations are not available in this case:

* Converting constructors

* Converting assignment

* InPlace construction

* InPlace assignment

* Value-access via pointer

Also, even though `optional<T&>` treats it wrapped pseudo-object much as

a real value, a true real reference is stored so aliasing will ocurr:

* Copies of `optional<T&>` will copy the references but all these references

will nonetheless refer to the same object.

* Value-access will actually provide access to the referenced object

rather than the reference itself.

[warning On compilers that do not conform to Standard C++ rules of reference binding, operations on optional references might give adverse results: rather than binding a reference to a designated object they may create an unexpected temporary and bind to it. For more details see [link boost_optional.dependencies_and_portability.optional_reference_binding Dependencies and Portability section].]

[heading Rvalue references]

Rvalue references and lvalue references to const have the ability in C++ to extend the life time of a temporary they bind to. Optional references do not have this capability, therefore to avoid surprising effects it is not possible to initialize an optional references from a temporary. Optional rvalue references are disabled altogether. Also, the initialization and assignment of an optional reference to const from rvalue reference is disabled.

const int& i = 1; // legal

optional<const int&> oi = 1; // illegal

[endsect]

[section Rebinding semantics for assignment of optional references]

If you assign to an ['uninitialized ] `optional<T&>` the effect is to bind (for

the first time) to the object. Clearly, there is no other choice.

int x = 1 ;

int& rx = x ;

optional<int&> ora ;

optional<int&> orb(x) ;

ora = orb ; // now 'ora' is bound to 'x' through 'rx'

*ora = 2 ; // Changes value of 'x' through 'ora'

assert(x==2);

If you assign to a bare C++ reference, the assignment is forwarded to the

referenced object; its value changes but the reference is never rebound.

int a = 1 ;

int& ra = a ;

int b = 2 ;

int& rb = b ;

ra = rb ; // Changes the value of 'a' to 'b'

assert(a==b);

b = 3 ;

assert(ra!=b); // 'ra' is not rebound to 'b'

Now, if you assign to an ['initialized ] `optional<T&>`, the effect is to

[*rebind] to the new object instead of assigning the referee. This is unlike

bare C++ references.

int a = 1 ;

int b = 2 ;

int& ra = a ;

int& rb = b ;

optional<int&> ora(ra) ;

optional<int&> orb(rb) ;

ora = orb ; // 'ora' is rebound to 'b'

*ora = 3 ; // Changes value of 'b' (not 'a')

assert(a==1);

assert(b==3);

[heading Rationale]

Rebinding semantics for the assignment of ['initialized ] `optional` references has

been chosen to provide [*consistency among initialization states] even at the

expense of lack of consistency with the semantics of bare C++ references.

It is true that `optional<U>` strives to behave as much as possible as `U`

does whenever it is initialized; but in the case when `U` is `T&`, doing so would

result in inconsistent behavior w.r.t to the lvalue initialization state.

Imagine `optional<T&>` forwarding assignment to the referenced object (thus

changing the referenced object value but not rebinding), and consider the

following code:

optional<int&> a = get();

int x = 1 ;

int& rx = x ;

optional<int&> b(rx);

a = b ;

What does the assignment do?

If `a` is ['uninitialized], the answer is clear: it binds to `x` (we now have

another reference to `x`).

But what if `a` is already ['initialized]? it would change the value of the

referenced object (whatever that is); which is inconsistent with the other

possible case.

If `optional<T&>` would assign just like `T&` does, you would never be able to

use Optional's assignment without explicitly handling the previous

initialization state unless your code is capable of functioning whether

after the assignment, `a` aliases the same object as `b` or not.

That is, you would have to discriminate in order to be consistent.

If in your code rebinding to another object is not an option, then it is very

likely that binding for the first time isn't either. In such case, assignment

to an ['uninitialized ] `optional<T&>` shall be prohibited. It is quite possible

that in such a scenario it is a precondition that the lvalue must be already

initialized. If it isn't, then binding for the first time is OK

while rebinding is not which is IMO very unlikely.

In such a scenario, you can assign the value itself directly, as in:

assert(!!opt);

*opt=value;

[endsect]