optional/doc/00_optional.qbk

[library Boost.Optional
    [quickbook 1.4]
    [authors [Cacciola Carballal, Fernando Luis]]
    [copyright 2003-2007 Fernando Luis Cacciola Carballal]
    [copyright 2014 Andrzej Krzemieński]
    [category miscellaneous]
    [id optional]
    [dirname optional]
    [purpose
        Discriminated-union wrapper for optional values
    ]
    [source-mode c++]
    [license
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])
    ]
]

[/ Macros will be used for links so we have a central place to change them ]


[/ Cited Boost resources ]

[def __BOOST_VARIANT__ [@../../../variant/index.html Boost.Variant]]
[def __BOOST_TRIBOOL__ [@../../../../doc/html/tribool.html boost::tribool]]

[def __OPTIONAL_POINTEE__ [@../../../utility/OptionalPointee.html OptionalPointee]]
[def __COPY_CONSTRUCTIBLE__ [@../../../utility/CopyConstructible.html Copy Constructible]]
[def __FUNCTION_EQUAL_POINTEES__ [@../../../utility/OptionalPointee.html#equal `equal_pointees()`]]
[def __FUNCTION_LESS_POINTEES__ [@../../../utility/OptionalPointee.html#less `less_pointees()`]]

[def __IN_PLACE_FACTORY_HPP__ [@../../../../boost/utility/in_place_factory.hpp in_place_factory.hpp]]
[def __TYPED_IN_PLACE_FACTORY_HPP__ [@../../../../boost/utility/typed_in_place_factory.hpp typed_in_place_factory.hpp]]

[/ Other web resources ]

[def __HASKELL__ [@http://www.haskell.org/ Haskell]]
[def __SGI_DEFAULT_CONSTRUCTIBLE__ [@http://www.sgi.com/tech/stl/DefaultConstructible.html Default Constructible]]


[/ Icons ]

[def __SPACE__ [$images/space.png]]
[def __GO_TO__ [$images/callouts/R.png]]


[section Introduction]
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] 
[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]