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.

[heading 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.

[heading 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_quick_start.qbk]
[section Tutorial]
[include 12_motivation.qbk]
[include 13_development.qbk]
[include 14_optional_references.qbk]
[include 15_in_place_factories.qbk]
[include 16_optional_bool.qbk]
[include 17_exception_safety.qbk]
[include 18_type_requirements.qbk]
[endsect]
[section Reference]
[include 20_reference.qbk]
[endsect]
[include 90_dependencies.qbk]
[include 91_acknowledgments.qbk]