123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410 |
- [/
- Boost.Optional
- Copyright (c) 2003-2007 Fernando Luis Cacciola Carballal
- 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 Detailed Semantics - Optional Values]
- [note
- The following section contains various `assert()` which are used only to show
- the postconditions as sample code. It is not implied that the type `T` must
- support each particular expression but that if the expression is supported,
- the implied condition holds.
- ]
- __SPACE__
- [#reference_optional_constructor]
- [: `optional<T>::optional() noexcept;`]
- * [*Effect:] Default-Constructs an `optional`.
- * [*Postconditions:] `*this` is [_uninitialized].
- * [*Notes:] T's default constructor [_is not] called.
- * [*Example:]
- ``
- optional<T> def ;
- assert ( !def ) ;
- ``
- __SPACE__
- [#reference_optional_constructor_none_t]
- [: `optional<T>::optional( none_t ) noexcept;`]
- * [*Effect:] Constructs an `optional` uninitialized.
- * [*Postconditions:] `*this` is [_uninitialized].
- * [*Notes:] `T`'s default constructor [_is not] called. The expression
- `boost::none` denotes an instance of `boost::none_t` that can be used as
- the parameter.
- * [*Example:]
- ``
- #include <boost/none.hpp>
- optional<T> n(none) ;
- assert ( !n ) ;
- ``
- __SPACE__
- [#reference_optional_constructor_value]
- [: `optional<T>::optional( T const& v )`]
- * [*Requires:] `is_copy_constructible<T>::value` is `true`.
- * [*Effect:] Directly-Constructs an `optional`.
- * [*Postconditions:] `*this` is [_initialized] and its value is a ['copy]
- of `v`.
- * [*Throws:] Whatever `T::T( T const& )` throws.
- * [*Notes: ] `T::T( T const& )` is called.
- * [*Exception Safety:] Exceptions can only be thrown during
- `T::T( T const& );` in that case, this constructor has no effect.
- * [*Example:]
- ``
- T v;
- optional<T> opt(v);
- assert ( *opt == v ) ;
- ``
- __SPACE__
- [#reference_optional_constructor_move_value]
- [: `optional<T>::optional( T&& v )`]
- * [*Requires:] `is_move_constructible<T>::value` is `true`.
- * [*Effect:] Directly-Move-Constructs an `optional`.
- * [*Postconditions:] `*this` is [_initialized] and its value is move-constructed from `v`.
- * [*Throws:] Whatever `T::T( T&& )` throws.
- * [*Notes: ] `T::T( T&& )` is called.
- * [*Exception Safety:] Exceptions can only be thrown during
- `T::T( T&& );` in that case, the state of `v` is determined by exception safety guarantees for `T::T(T&&)`.
- * [*Example:]
- ``
- T v1, v2;
- optional<T> opt(std::move(v1));
- assert ( *opt == v2 ) ;
- ``
- __SPACE__
- [#reference_optional_constructor_bool_value]
- [: `optional<T>::optional( bool condition, T const& v ) ;` ]
- * If condition is true, same as:
- [: `optional<T>::optional( T const& v )`]
- * otherwise, same as:
- [: `optional<T>::optional()`]
- __SPACE__
- [#reference_optional_constructor_optional]
- [: `optional<T>::optional( optional const& rhs );`]
- * [*Requires:] `is_copy_constructible<T>::value` is `true`.
- * [*Effect:] Copy-Constructs an `optional`.
- * [*Postconditions:] If rhs is initialized, `*this` is initialized and
- its value is a ['copy] of the value of `rhs`; else `*this` is uninitialized.
- * [*Throws:] Whatever `T::T( T const& )` throws.
- * [*Notes:] If rhs is initialized, `T::T(T const& )` is called.
- * [*Exception Safety:] Exceptions can only be thrown during
- `T::T( T const& );` in that case, this constructor has no effect.
- * [*Example:]
- ``
- optional<T> uninit ;
- assert (!uninit);
- optional<T> uinit2 ( uninit ) ;
- assert ( uninit2 == uninit );
- optional<T> init( T(2) );
- assert ( *init == T(2) ) ;
- optional<T> init2 ( init ) ;
- assert ( init2 == init ) ;
- ``
- __SPACE__
- [#reference_optional_move_constructor_optional]
- [: `optional<T>::optional( optional&& rhs ) noexcept(`['see below]`);`]
- * [*Requires:] `is_move_constructible<T>::value` is `true`.
- * [*Effect:] Move-constructs an `optional`.
- * [*Postconditions:] If `rhs` is initialized, `*this` is initialized and
- its value is move constructed from `rhs`; else `*this` is uninitialized.
- * [*Throws:] Whatever `T::T( T&& )` throws.
- * [*Remarks:] The expression inside `noexcept` is equivalent to `is_nothrow_move_constructible<T>::value`.
- * [*Notes:] If `rhs` is initialized, `T::T( T && )` is called.
- * [*Exception Safety:] Exceptions can only be thrown during
- `T::T( T&& );` in that case, `rhs` remains initialized and the value of `*rhs` is determined by exception safety of `T::T(T&&)`.
- * [*Example:]
- ``
- optional<std::unique_ptr<T>> uninit ;
- assert (!uninit);
- optional<std::unique_ptr<T>> uinit2 ( std::move(uninit) ) ;
- assert ( uninit2 == uninit );
- optional<std::unique_ptr<T>> init( std::uniqye_ptr<T>(new T(2)) );
- assert ( **init == T(2) ) ;
- optional<std::unique_ptr<T>> init2 ( std::move(init) ) ;
- assert ( init );
- assert ( *init == nullptr );
- assert ( init2 );
- assert ( **init2 == T(2) ) ;
- ``
- __SPACE__
- [#reference_optional_constructor_other_optional]
- [: `template<U> explicit optional<T>::optional( optional<U> const& rhs );`]
- * [*Effect:] Copy-Constructs an `optional`.
- * [*Postconditions:] If `rhs` is initialized, `*this` is initialized and its
- value is a ['copy] of the value of rhs converted to type `T`; else `*this` is
- uninitialized.
- * [*Throws:] Whatever `T::T( U const& )` throws.
- * [*Notes: ] `T::T( U const& )` is called if `rhs` is initialized, which requires a
- valid conversion from `U` to `T`.
- * [*Exception Safety:] Exceptions can only be thrown during `T::T( U const& );`
- in that case, this constructor has no effect.
- * [*Example:]
- ``
- optional<double> x(123.4);
- assert ( *x == 123.4 ) ;
- optional<int> y(x) ;
- assert( *y == 123 ) ;
- ``
- __SPACE__
- [#reference_optional_move_constructor_other_optional]
- [: `template<U> explicit optional<T>::optional( optional<U>&& rhs );`]
- * [*Effect:] Move-constructs an `optional`.
- * [*Postconditions:] If `rhs` is initialized, `*this` is initialized and its
- value is move-constructed from `*rhs`; else `*this` is
- uninitialized.
- * [*Throws:] Whatever `T::T( U&& )` throws.
- * [*Notes: ] `T::T( U&& )` is called if `rhs` is initialized, which requires a
- valid conversion from `U` to `T`.
- * [*Exception Safety:] Exceptions can only be thrown during `T::T( U&& );`
- in that case, `rhs` remains initialized and the value of `*rhs` is determined by exception safety guarantee of `T::T( U&& )`.
- * [*Example:]
- ``
- optional<double> x(123.4);
- assert ( *x == 123.4 ) ;
- optional<int> y(std::move(x)) ;
- assert( *y == 123 ) ;
- ``
- __SPACE__
- [#reference_optional_in_place_init]
- [: `template<class... Args> explicit optional<T>::optional( in_place_init_t, Args&&... ars );`]
- * [*Requires:] `is_constructible_v<T, Args&&...>` is `true`.
- * [*Effect:] Initializes the contained value as if direct-non-list-initializing an object of type `T` with the
- arguments `std::forward<Args>(args)...`.
- * [*Postconditions:] `*this` is initialized.
- * [*Throws:] Any exception thrown by the selected constructor of `T`.
- * [*Notes: ] `T` need not be __MOVE_CONSTRUCTIBLE__. On compilers that do not suppor variadic templates or rvalue references, this constuctor is available in limited functionality. For details [link optional_emplace_workaround see here].
- * [*Example:]
- ``
- // creates an std::mutex using its default constructor
- optional<std::mutex> om {in_place_init};
- assert (om);
- // creates a unique_lock by calling unique_lock(*om, std::defer_lock)
- optional<std::unique_lock<std::mutex>> ol {in_place_init, *om, std::defer_lock};
- assert (ol);
- assert (!ol->owns_lock());
- ``
- __SPACE__
- [#reference_optional_in_place_init_if]
- [: `template<class... Args> explicit optional<T>::optional( in_place_init_if_t, bool condition, Args&&... ars );`]
- * [*Requires:] `is_constructible_v<T, Args&&...>` is `true`.
- * [*Effect:] If `condition` is `true`, initializes the contained value as if direct-non-list-initializing an object of type `T` with the arguments `std::forward<Args>(args)...`.
- * [*Postconditions:] `bool(*this) == condition`.
- * [*Throws:] Any exception thrown by the selected constructor of `T`.
- * [*Notes: ] `T` need not be __MOVE_CONSTRUCTIBLE__. On compilers that do not suppor variadic templates or rvalue references, this constuctor is available in limited functionality. For details [link optional_emplace_workaround see here].
- * [*Example:]
- ``
- optional<std::vector<std::string>> ov1 {in_place_init_if, false, 3, "A"};
- assert (!ov1);
- optional<std::vector<std::string>> ov2 {in_place_init_if, true, 3, "A"};
- assert (ov2);
- assert (ov2->size() == 3);
- ``
- __SPACE__
- [#reference_optional_constructor_factory]
- [: `template<InPlaceFactory> explicit optional<T>::optional( InPlaceFactory const& f );`]
- [: `template<TypedInPlaceFactory> explicit optional<T>::optional( TypedInPlaceFactory const& f );`]
- * [*Effect:] Constructs an `optional` with a value of `T` obtained from the
- factory.
- * [*Postconditions: ] `*this` is [_initialized] and its value is ['directly given]
- from the factory `f` (i.e., the value [_is not copied]).
- * [*Throws:] Whatever the `T` constructor called by the factory throws.
- * [*Notes:] See [link boost_optional.tutorial.in_place_factories In-Place Factories]
- * [*Exception Safety:] Exceptions can only be thrown during the call to
- the `T` constructor used by the factory; in that case, this constructor has
- no effect.
- * [*Example:]
- ``
- class C { C ( char, double, std::string ) ; } ;
- C v('A',123.4,"hello");
- optional<C> x( in_place ('A', 123.4, "hello") ); // InPlaceFactory used
- optional<C> y( in_place<C>('A', 123.4, "hello") ); // TypedInPlaceFactory used
- assert ( *x == v ) ;
- assert ( *y == v ) ;
- ``
- __SPACE__
- [#reference_optional_operator_equal_none_t]
- [: `optional& optional<T>::operator= ( none_t ) noexcept;`]
- * [*Effect:] If `*this` is initialized destroys its contained value.
- * [*Postconditions: ] `*this` is uninitialized.
- __SPACE__
- [#reference_optional_operator_equal_value]
- [: `optional& optional<T>::operator= ( T const& rhs ) ;`]
- * [*Effect:] Assigns the value `rhs` to an `optional`.
- * [*Postconditions: ] `*this` is initialized and its value is a ['copy] of `rhs`.
- * [*Throws:] Whatever `T::operator=( T const& )` or `T::T(T const&)` throws.
- * [*Notes:] If `*this` was initialized, `T`'s assignment operator is used,
- otherwise, its copy-constructor is used.
- * [*Exception Safety:] In the event of an exception, the initialization
- state of `*this` is unchanged and its value unspecified as far as `optional`
- is concerned (it is up to `T`'s `operator=()`). If `*this` is initially
- uninitialized and `T`'s ['copy constructor] fails, `*this` is left properly
- uninitialized.
- * [*Example:]
- ``
- T x;
- optional<T> def ;
- optional<T> opt(x) ;
- T y;
- def = y ;
- assert ( *def == y ) ;
- opt = y ;
- assert ( *opt == y ) ;
- ``
- __SPACE__
- [#reference_optional_operator_move_equal_value]
- [: `optional& optional<T>::operator= ( T&& rhs ) ;`]
- * [*Effect:] Moves the value `rhs` to an `optional`.
- * [*Postconditions: ] `*this` is initialized and its value is moved from `rhs`.
- * [*Throws:] Whatever `T::operator=( T&& )` or `T::T(T &&)` throws.
- * [*Notes:] If `*this` was initialized, `T`'s move-assignment operator is used,
- otherwise, its move-constructor is used.
- * [*Exception Safety:] In the event of an exception, the initialization
- state of `*this` is unchanged and its value unspecified as far as `optional`
- is concerned (it is up to `T`'s `operator=()`). If `*this` is initially
- uninitialized and `T`'s ['move constructor] fails, `*this` is left properly
- uninitialized.
- * [*Example:]
- ``
- T x;
- optional<T> def ;
- optional<T> opt(x) ;
- T y1, y2, yR;
- def = std::move(y1) ;
- assert ( *def == yR ) ;
- opt = std::move(y2) ;
- assert ( *opt == yR ) ;
- ``
- __SPACE__
- [#reference_optional_operator_equal_optional]
- [: `optional& optional<T>::operator= ( optional const& rhs ) ;`]
- * [*Requires:] `T` is __COPY_CONSTRUCTIBLE__ and `CopyAssignable`.
- * [*Effects:]
- [table
- []
- [[][[*`*this` contains a value]][[*`*this` does not contain a value]]]
- [[[*`rhs` contains a value]][assigns `*rhs` to the contained value][initializes the contained value as if direct-initializing an object of type `T` with `*rhs`]]
- [[[*`rhs` does not contain a value]][destroys the contained value by calling `val->T::~T()`][no effect]]
- ]
- * [*Returns:] `*this`;
- * [*Postconditions:] `bool(rhs) == bool(*this)`.
- * [*Exception Safety:] If any exception is thrown, the initialization state of `*this` and `rhs` remains unchanged.
- If an exception is thrown during the call to `T`'s copy constructor, no effect.
- If an exception is thrown during the call to `T`'s copy assignment, the state of its contained value is as defined by the exception safety guarantee of `T`'s copy assignment.
- * [*Example:]
- ``
- T v;
- optional<T> opt(v);
- optional<T> def ;
- opt = def ;
- assert ( !def ) ;
- // previous value (copy of 'v') destroyed from within 'opt'.
- ``
- __SPACE__
- [#reference_optional_operator_move_equal_optional]
- [: `optional& optional<T>::operator= ( optional&& rhs ) noexcept(`['see below]`);`]
- * [*Requires:] `T` is __MOVE_CONSTRUCTIBLE__ and `MoveAssignable`.
- * [*Effects:]
- [table
- []
- [[][[*`*this` contains a value]][[*`*this` does not contain a value]]]
- [[[*`rhs` contains a value]][assigns `std::move(*rhs)` to the contained value][initializes the contained value as if direct-initializing an object of type `T` with `std::move(*rhs)`]]
- [[[*`rhs` does not contain a value]][destroys the contained value by calling `val->T::~T()`][no effect]]
- ]
- * [*Returns:] `*this`;
- * [*Postconditions:] `bool(rhs) == bool(*this)`.
- * [*Remarks:] The expression inside `noexcept` is equivalent to `is_nothrow_move_constructible<T>::value && is_nothrow_move_assignable<T>::value`.
- * [*Exception Safety:] If any exception is thrown, the initialization state of `*this` and `rhs` remains unchanged. If an exception is
- thrown during the call to `T`'s move constructor, the state of `*rhs` is determined by the exception safety guarantee
- of `T`'s move constructor. If an exception is thrown during the call to T's move-assignment, the state of `**this` and `*rhs` is determined by the exception safety guarantee of T's move assignment.
- * [*Example:]
- ``
- optional<T> opt(T(2)) ;
- optional<T> def ;
- opt = def ;
- assert ( def ) ;
- assert ( opt ) ;
- assert ( *opt == T(2) ) ;
- ``
- __SPACE__
- [#reference_optional_operator_equal_other_optional]
- [: `template<U> optional& optional<T>::operator= ( optional<U> const& rhs ) ;`]
- * [*Effect:]
- [table
- []
- [[][[*`*this` contains a value]][[*`*this` does not contain a value]]]
- [[[*`rhs` contains a value]][assigns `*rhs` to the contained value][initializes the contained value as if direct-initializing an object of type `T` with `*rhs`]]
- [[[*`rhs` does not contain a value]][destroys the contained value by calling `val->T::~T()`][no effect]]
- ]
- * [*Returns:] `*this`.
- * [*Postconditions:] `bool(rhs) == bool(*this)`.
- * [*Exception Safety:] If any exception is thrown, the result of the expression `bool(*this)` remains unchanged.
- If an exception is thrown during the call to `T`'s constructor, no effect.
- If an exception is thrown during the call to `T`'s assignment, the state of its contained value is as defined by the exception safety guarantee of `T`'s copy assignment.
- * [*Example:]
- ``
- T v;
- optional<T> opt0(v);
- optional<U> opt1;
- opt1 = opt0 ;
- assert ( *opt1 == static_cast<U>(v) ) ;
- ``
- __SPACE__
- [#reference_optional_operator_move_equal_other_optional]
- [: `template<U> optional& optional<T>::operator= ( optional<U>&& rhs ) ;`]
- * [*Effect:]
- [table
- []
- [[][[*`*this` contains a value]][[*`*this` does not contain a value]]]
- [[[*`rhs` contains a value]][assigns `std::move(*rhs)` to the contained value][initializes the contained value as if direct-initializing an object of type `T` with `std::move(*rhs)`]]
- [[[*`rhs` does not contain a value]][destroys the contained value by calling `val->T::~T()`][no effect]]
- ]
- * [*Returns:] `*this`.
- * [*Postconditions:] `bool(rhs) == bool(*this)`.
- * [*Exception Safety:] If any exception is thrown, the result of the expression `bool(*this)` remains unchanged.
- If an exception is thrown during the call to `T`'s constructor, no effect.
- If an exception is thrown during the call to `T`'s assignment, the state of its contained value is as defined by the exception safety guarantee of `T`'s copy assignment.
- * [*Example:]
- ``
- T v;
- optional<T> opt0(v);
- optional<U> opt1;
- opt1 = std::move(opt0) ;
- assert ( opt0 );
- assert ( opt1 )
- assert ( *opt1 == static_cast<U>(v) ) ;
- ``
- __SPACE__
- [#reference_optional_emplace]
- [: `template<class... Args> void optional<T>::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.
- * [*Exception Safety:] If an exception is thrown during the initialization of `T`, `*this` is ['uninitialized].
- * [*Notes:] `T` need not be __MOVE_CONSTRUCTIBLE__ or `MoveAssignable`. On compilers that do not suppor variadic templates or rvalue references, this function is available in limited functionality. For details [link optional_emplace_workaround see here].
- * [*Example:]
- ``
- T v;
- optional<const T> opt;
- opt.emplace(0); // create in-place using ctor T(int)
- opt.emplace(); // destroy previous and default-construct another T
- opt.emplace(v); // destroy and copy-construct in-place (no assignment called)
- ``
- __SPACE__
- [#reference_optional_operator_equal_factory]
- [: `template<InPlaceFactory> optional<T>& optional<T>::operator=( InPlaceFactory const& f );`]
- [: `template<TypedInPlaceFactory> optional<T>& optional<T>::operator=( TypedInPlaceFactory const& f );`]
- * [*Effect:] Assigns an `optional` with a value of `T` obtained from the
- factory.
- * [*Postconditions: ] `*this` is [_initialized] and its value is ['directly given]
- from the factory `f` (i.e., the value [_is not copied]).
- * [*Throws:] Whatever the `T` constructor called by the factory throws.
- * [*Notes:] See [link boost_optional.tutorial.in_place_factories In-Place Factories]
- * [*Exception Safety:] Exceptions can only be thrown during the call to
- the `T` constructor used by the factory; in that case, the `optional` object
- will be reset to be ['uninitialized].
- __SPACE__
- [#reference_optional_reset_value]
- [: `void optional<T>::reset( T const& v ) ;`]
- * [*Deprecated:] same as `operator= ( T const& v) ;`
- __SPACE__
- [#reference_optional_reset]
- [: `void optional<T>::reset() noexcept ;`]
- * [*Effects:] Same as `operator=( none_t );`
- __SPACE__
- [#reference_optional_get]
- [: `T const& optional<T>::get() const ;`]
- [: `T& optional<T>::get() ;`]
- [: `inline T const& get ( optional<T> const& ) ;`]
- [: `inline T& get ( optional<T> &) ;`]
- * [*Requires:] `*this` is initialized
- * [*Returns:] A reference to the contained value
- * [*Throws:] Nothing.
- * [*Notes:] The requirement is asserted via `BOOST_ASSERT()`.
- __SPACE__
- [#reference_optional_operator_asterisk]
- [: `T const& optional<T>::operator*() const& ;`]
- [: `T& optional<T>::operator*() &;`]
- * [*Requires:] `*this` is initialized
- * [*Returns:] A reference to the contained value
- * [*Throws:] Nothing.
- * [*Notes:] The requirement is asserted via `BOOST_ASSERT()`. On compilers that do not support ref-qualifiers on member functions these two overloads are replaced with the classical two: a `const` and non-`const` member functions.
- * [*Example:]
- ``
- T v ;
- optional<T> opt ( v );
- T const& u = *opt;
- assert ( u == v ) ;
- T w ;
- *opt = w ;
- assert ( *opt == w ) ;
- ``
- __SPACE__
- [#reference_optional_operator_asterisk_move]
- [: `T&& optional<T>::operator*() &&;`]
- * [*Requires:] `*this` contains a value.
- * [*Effects:] Equivalent to `return std::move(*val);`.
- * [*Notes:] The requirement is asserted via `BOOST_ASSERT()`. On compilers that do not support ref-qualifiers on member functions this overload is not present.
- __SPACE__
- [#reference_optional_value]
- [: `T const& optional<T>::value() const& ;`]
- [: `T& optional<T>::value() & ;`]
- * [*Effects:] Equivalent to `return bool(*this) ? *val : throw bad_optional_access();`.
- * [*Notes:] On compilers that do not support ref-qualifiers on member functions these two overloads are replaced with the classical two: a `const` and non-`const` member functions.
- * [*Example:]
- ``
- T v ;
- optional<T> o0, o1 ( v );
- assert ( o1.value() == v );
- try {
- o0.value(); // throws
- assert ( false );
- }
- catch(bad_optional_access&) {
- assert ( true );
- }
- ``
- __SPACE__
- [#reference_optional_value_move]
- [: `T&& optional<T>::value() && ;`]
- * [*Effects:] Equivalent to `return bool(*this) ? std::move(*val) : throw bad_optional_access();`.
- * [*Notes:] On compilers that do not support ref-qualifiers on member functions this overload is not present.
- __SPACE__
- [#reference_optional_value_or]
- [: `template<class U> T optional<T>::value_or(U && v) const& ;`]
- * [*Effects:] Equivalent to `if (*this) return **this; else return std::forward<U>(v);`.
- * [*Remarks:] If `T` is not __COPY_CONSTRUCTIBLE__ or `U &&` is not convertible to `T`, the program is ill-formed.
- * [*Notes:] On compilers that do not support ref-qualifiers on member functions this overload is replaced with the `const`-qualified member function. On compilers without rvalue reference support the type of `v` becomes `U const&`.
- __SPACE__
- [#reference_optional_value_or_move]
- [: `template<class U> T optional<T>::value_or(U && v) && ;`]
- * [*Effects:] Equivalent to `if (*this) return std::move(**this); else return std::forward<U>(v);`.
- * [*Remarks:] If `T` is not __MOVE_CONSTRUCTIBLE__ or `U &&` is not convertible to `T`, the program is ill-formed.
- * [*Notes:] On compilers that do not support ref-qualifiers on member functions this overload is not present.
- __SPACE__
- [#reference_optional_value_or_call]
- [: `template<class F> T optional<T>::value_or_eval(F f) const& ;`]
- * [*Requires:] `T` is __COPY_CONSTRUCTIBLE__ and `F` models a __SGI_GENERATOR__ whose result type is convertible to `T`.
- * [*Effects:] `if (*this) return **this; else return f();`.
- * [*Notes:] On compilers that do not support ref-qualifiers on member functions this overload is replaced with the `const`-qualified member function.
- * [*Example:]
- ``
- int complain_and_0()
- {
- clog << "no value returned, using default" << endl;
- return 0;
- }
- optional<int> o1 = 1;
- optional<int> oN = none;
- int i = o1.value_or_eval(complain_and_0); // fun not called
- assert (i == 1);
- int j = oN.value_or_eval(complain_and_0); // fun called
- assert (i == 0);
- ``
- __SPACE__
- [#reference_optional_value_or_call_move]
- [: `template<class F> T optional<T>::value_or_eval(F f) && ;`]
- * [*Requires:] `T` is __MOVE_CONSTRUCTIBLE__ and `F` models a __SGI_GENERATOR__ whose result type is convertible to `T`.
- * [*Effects:] `if (*this) return std::move(**this); else return f();`.
- * [*Notes:] On compilers that do not support ref-qualifiers on member functions this overload is not present.
- __SPACE__
- [#reference_optional_map]
- [: `template<class F> auto optional<T>::map(F f) const& -> `['see below]` ;`]
- [: `template<class F> auto optional<T>::map(F f) & -> `['see below]` ;`]
- * [*Effects:] `if (*this) return f(**this); else return none;`
- * [*Notes:] The return type of these overloads is `optional<decltype(f(**this))>`. On compilers that do not support ref-qualifiers on member functions, these two (as well as the next one) overloads are replaced with good old const and non-const overloads.
- * [*Example:]
- ``
- auto length = [](const string& s){ return s.size(); };
- optional<string> o1 {}, o2 {"cat"};
- optional<size_t> os1 = o1.map(length), os2 = o2.map(length);
- assert ( !os1 ) ;
- assert ( os2 ) ;
- assert ( *os2 == 3 ) ;
- ``
- __SPACE__
- [#reference_optional_map_move]
- [: `template<class F> auto optional<T>::map(F f) && -> `['see below]` ;`]
- * [*Effects:] `if (*this) return f(std::move(**this)); else return none;`
- * [*Notes:] The return type of this overload is `optional<decltype(f(istd::move(**this)))>`.
- __SPACE__
- [#reference_optional_flat_map]
- [: `template<class F> auto optional<T>::flat_map(F f) const& -> `['see below]` ;`]
- [: `template<class F> auto optional<T>::flat_map(F f) & -> `['see below]` ;`]
- * [*Requires:] The return type of expression `f(**this)` is `optional<U>` for some object or reference type `U`.
- * [*Effects:] `if (*this) return f(**this); else return none;`
- * [*Notes:] The return type of these overloads is `optional<U>`. On compilers that do not support ref-qualifiers on member functions, these two (as well as the next one) overloads are replaced with good old const and non-const overloads.
- * [*Example:]
- ``
- optional<char> first_char(const string& s) {
- return s.empty() ? none : optional<char>(s[0]);
- };
- optional<string> o1 {}, o2 {"cat"};
- optional<char> os1 = o1.flat_map(first_char), os2 = o2.flat_map(first_char);
- assert ( !os1 ) ;
- assert ( os2 ) ;
- assert ( *os2 == 'c' ) ;
- ``
- __SPACE__
- [#reference_optional_flat_map_move]
- [: `template<class F> auto optional<T>::flat_map(F f) && -> `['see below]` ;`]
- * [*Requires:] The return type of expression `f(std::move(**this))` is `optional<U>` for some object or reference type `U`.
- * [*Effects:] `if (*this) return f(std::move(**this)); else return none;`
- * [*Notes:] The return type of this overload is `optional<U>`.
- __SPACE__
- [#reference_optional_get_value_or_value]
- [: `T const& optional<T>::get_value_or( T const& default) const ;`]
- [: `T& optional<T>::get_value_or( T& default ) ;`]
- * [*Deprecated:] Use `value_or()` instead.
- * [*Returns:] A reference to the contained value, if any, or `default`.
- * [*Throws:] Nothing.
- * [*Example:]
- ``
- T v, z ;
- optional<T> def;
- T const& y = def.get_value_or(z);
- assert ( y == z ) ;
- optional<T> opt ( v );
- T const& u = opt.get_value_or(z);
- assert ( u == v ) ;
- assert ( u != z ) ;
- ``
- __SPACE__
- [#reference_optional_get_ptr]
- [: `T const* optional<T>::get_ptr() const ;`]
- [: `T* optional<T>::get_ptr() ;`]
- * [*Returns:] If `*this` is initialized, a pointer to the contained value;
- else `0` (['null]).
- * [*Throws:] Nothing.
- * [*Notes:] The contained value is permanently stored within `*this`, so you
- should not hold nor delete this pointer
- * [*Example:]
- ``
- T v;
- optional<T> opt(v);
- optional<T> const copt(v);
- T* p = opt.get_ptr() ;
- T const* cp = copt.get_ptr();
- assert ( p == get_pointer(opt) );
- assert ( cp == get_pointer(copt) ) ;
- ``
- __SPACE__
- [#reference_optional_operator_arrow]
- [: `T const* optional<T>::operator ->() const ;`]
- [: `T* optional<T>::operator ->() ;`]
- * [*Requires: ] `*this` is initialized.
- * [*Returns:] A pointer to the contained value.
- * [*Throws:] Nothing.
- * [*Notes:] The requirement is asserted via `BOOST_ASSERT()`.
- * [*Example:]
- ``
- struct X { int mdata ; } ;
- X x ;
- optional<X> opt (x);
- opt->mdata = 2 ;
- ``
- __SPACE__
- [#reference_optional_operator_bool]
- [: `explicit optional<T>::operator bool() const noexcept ;`]
- [: `bool optional<T>::has_value() const noexcept ;`]
- * [*Returns:] `get_ptr() != 0`.
- * [*Notes:] On compilers that do not support explicit conversion operators this falls back to safe-bool idiom.
- * [*Example:]
- ``
- optional<T> def ;
- assert ( def == 0 );
- optional<T> opt ( v ) ;
- assert ( opt );
- assert ( opt != 0 );
- ``
- __SPACE__
- [#reference_optional_operator_not]
- [: `bool optional<T>::operator!() noexcept ;`]
- * [*Returns:] If `*this` is uninitialized, `true`; else `false`.
- * [*Notes:] This operator is provided for those compilers which can't
- use the ['unspecified-bool-type operator] in certain boolean contexts.
- * [*Example:]
- ``
- optional<T> opt ;
- assert ( !opt );
- *opt = some_T ;
- // Notice the "double-bang" idiom here.
- assert ( !!opt ) ;
- ``
- __SPACE__
- [#reference_optional_is_initialized]
- [: `bool optional<T>::is_initialized() const ;`]
- * [*Deprecated:] Same as `explicit operator bool () ;`
- [endsect]
- [section Detailed Semantics - Optional References]
- __SPACE__
- [#reference_optional_ref_default_ctor]
- [: `optional<T&>::optional() noexcept;`]
- [: `optional<T&>::optional(none_t) noexcept;`]
- * [*Postconditions:] `bool(*this) == false`; `*this` refers to nothing.
- __SPACE__
- [#reference_optional_ref_value_ctor]
- [: `template<class R> optional<T&>::optional(R&& r) noexcept;`]
- * [*Postconditions:] `bool(*this) == true`; `addressof(**this) == addressof(r)`.
- * [*Remarks:] Unless `R` is an lvalue reference, the program is ill-formed. This constructor does not participate in overload resolution if `decay<R>` is an instance of `boost::optional`.
- * [*Notes:] This constructor is declared `explicit` on compilers that do not correctly suport binding to const lvalues of integral types. For more details [link optional_reference_binding see here].
- * [*Example:]
- ``
- T v;
- T& vref = v ;
- optional<T&> opt(vref);
- assert ( *opt == v ) ;
- ++ v ; // mutate referee
- assert (*opt == v);
- ``
- __SPACE__
- [#reference_optional_ref_cond_value_ctor]
- [: `template<class R> optional<T&>::optional(bool cond, R&& r) noexcept;`]
- * [*Effects: ] Initializes `ref` with expression `cond ? addressof(r) : nullptr`.
- * [*Postconditions:] `bool(*this) == cond`; If `bool(*this)`, `addressof(**this) == addressof(r)`.
- * [*Remarks:] Unless `R` is an lvalue reference, the program is ill-formed. This constructor does not participate in overload resolution if `decay<R>` is an instance of `boost::optional`.
- __SPACE__
- [#reference_optional_ref_copy_ctor]
- [: `optional<T&>::optional ( optional const& rhs ) noexcept ;`]
- * [*Effects: ] Initializes `ref` with expression `rhs.ref`.
- * [*Postconditions:] `bool(*this) == bool(rhs)`.
- * [*Example:]
- ``
- optional<T&> uninit ;
- assert (!uninit);
- optional<T&> uinit2 ( uninit ) ;
- assert ( uninit2 == uninit );
- T v = 2 ; T& ref = v ;
- optional<T> init(ref);
- assert ( *init == v ) ;
- optional<T> init2 ( init ) ;
- assert ( *init2 == v ) ;
- v = 3 ;
- assert ( *init == 3 ) ;
- assert ( *init2 == 3 ) ;
- ``
- __SPACE__
- [#reference_optional_ref_ctor_from_opt_U]
- [: `template<class U> explicit optional<T&>::optional ( optional<U&> const& rhs ) noexcept ;`]
- * [*Requires:] `is_convertible<U&, T&>::value` is `true`.
- * [*Effects: ] Initializes `ref` with expression `rhs.ref`.
- * [*Postconditions:] `bool(*this) == bool(rhs)`.
- __SPACE__
- [#reference_optional_ref_assign_none_t]
- [: `optional<T&>::operator= ( none_t ) noexcept ;`]
- * [*Effects: ] Assigns `ref` with expression `nullptr`.
- * [*returns:] `*this`.
- * [*Postconditions:] `bool(*this) == false`.
- [#reference_optional_ref_copy_assign]
- [: `optional& optional<T&>::operator= ( optional const& rhs ) noexcept ;`]
- * [*Effects: ] Assigns `ref` with expression `rhs.ref`.
- * [*returns:] `*this`.
- * [*Postconditions:] `bool(*this) == bool(rhs)`.
- * [*Notes:] This behaviour is called ['rebinding semantics]. See [link boost_optional.tutorial.optional_references.rebinding_semantics_for_assignment_of_optional_references here] for details.
- * [*Example:]
- ``
- int a = 1 ;
- int b = 2 ;
- T& ra = a ;
- T& rb = b ;
- optional<int&> def ;
- optional<int&> ora(ra) ;
- optional<int&> orb(rb) ;
- def = orb ; // binds 'def' to 'b' through 'rb' wrapped within 'orb'
- assert ( *def == b ) ;
- *def = ora ; // changes the value of 'b' to a copy of the value of 'a'
- assert ( b == a ) ;
- int c = 3;
- int& rc = c ;
- optional<int&> orc(rc) ;
- ora = orc ; // REBINDS ora to 'c' through 'rc'
- c = 4 ;
- assert ( *ora == 4 ) ;
- ``
- [#reference_optional_ref_assign_optional_U]
- [: `template<class U> optional& optional<T&>::operator= ( optional<U&> const& rhs ) noexcept ;`]
- * [*Requires:] `is_convertible<U&, T&>::value` is `true`.
- * [*Effects: ] Assigns `ref` with expression `rhs.ref`.
- * [*returns:] `*this`.
- * [*Postconditions:] `bool(*this) == bool(rhs)`.
- __SPACE__
- [#reference_optional_ref_assign_R]
- [: `template<class R> optional& optional<T&>::operator= ( R&& r ) noexcept ;`]
- * [*Effects: ] Assigns `ref` with expression `r`.
- * [*returns:] `*this`.
- * [*Postconditions:] `bool(*this) == true`.
- * [*Remarks:] Unless `R` is an lvalue reference, the program is ill-formed. This function does not participate in overload resolution if `decay<R>` is an instance of `boost::optional`.
- * [*Example:]
- ``
- int a = 1 ;
- int b = 2 ;
- T& ra = a ;
- T& rb = b ;
- optional<int&> def ;
- optional<int&> opt(ra) ;
- def = rb ; // binds 'def' to 'b' through 'rb'
- assert ( *def == b ) ;
- *def = a ; // changes the value of 'b' to a copy of the value of 'a'
- assert ( b == a ) ;
- int c = 3;
- int& rc = c ;
- opt = rc ; // REBINDS to 'c' through 'rc'
- c = 4 ;
- assert ( *opt == 4 ) ;
- ``
- __SPACE__
- [#reference_optional_ref_emplace_R]
- [: `void optional<T&>::emplace( R&& r ) noexcept ;`]
- * [*Effects: ] Assigns `ref` with expression `r`.
- * [*Postconditions:] `bool(*this) == true`.
- * [*Remarks:] Unless `R` is an lvalue reference, the program is ill-formed. This function does not participate in overload resolution if `decay<R>` is an instance of `boost::optional`.
- __SPACE__
- [#reference_optional_ref_get]
- [: `T& optional<T&>::get() const ;`]
- [: `T& optional<T&>::operator *() const ;`]
- * [*Requires:] `bool(*this) == true`.
- * [*Effects: ] Returns `*ref`.
- * [*Throws: ] Nothing.
- * [*Example:]
- ``
- T v ;
- T& vref = v ;
- optional<T&> opt ( vref );
- T const& vref2 = *opt;
- assert ( vref2 == v ) ;
- ++ v ;
- assert ( *opt == v ) ;
- ``
- __SPACE__
- [#reference_optional_ref_arrow]
- [: `T* optional<T&>::operator -> () const ;`]
- * [*Requires:] `bool(*this) == true`.
- * [*Effects: ] Returns `ref`.
- * [*Throws: ] Nothing.
- __SPACE__
- [#reference_optional_ref_value]
- [: `T& optional<T&>::value() const ;`]
- * [*Effects:] Equivalent to `return bool(*this) ? *val : throw bad_optional_access();`.
- __SPACE__
- [#reference_optional_ref_value_or]
- [: `template<class R> T& optional<T&>::value_or( R&& r ) const noexcept;`]
- * [*Effects:] Equivalent to `if (*this) return **this; else return r;`.
- * [*Remarks:] Unless `R` is an lvalue reference, the program is ill-formed.
- __SPACE__
- [#reference_optional_ref_value_or_eval]
- [: `template<class F> T& optional<T&>::value_or( F f ) const ;`]
- * [*Effects:] Equivalent to `if (*this) return **this; else return f();`.
- * [*Remarks:] Unless `decltype(f())` is an lvalue reference, the program is ill-formed.
- __SPACE__
- [#reference_optional_ref_map]
- [: `template<class F> auto optional<T&>::map( F f ) const -> `['see below]`;`]
- * [*Effects:] Equivalent to `if (*this) return f(**this); else return none;`.
- * [*Remarks:] The return type of this function is `optional<decltype(f(**this))>`.
- __SPACE__
- [#reference_optional_ref_flat_map]
- [: `template<class F> auto optional<T&>::flat_map( F f ) const -> `['see below]`;`]
- * [*Requires:] The return type of expression `f(**this)` is `optional<U>` for some object or reference type `U`.
- * [*Effects:] Equivalent to `if (*this) return f(**this); else return none;`.
- * [*Remarks:] The return type of this function is `optional<U>`.
- __SPACE__
- [#reference_optional_ref_get_ptr]
- [: `T* optional<T&>::get_ptr () const noexcept;`]
- * [*Returns:] `ref`.
- __SPACE__
- [#reference_optional_ref_operator_bool]
- [: `bool has_value() const noexcept;`]
- [: `optional<T&>::operator bool () const noexcept;`]
- * [*Returns:] `bool(ref)`.
- __SPACE__
- [#reference_optional_ref_operator_not]
- [: `optional<T&>::operator ! () const noexcept;`]
- * [*Returns:] `!bool(ref)`.
- __SPACE__
- [#reference_optional_ref_reset]
- [: `void optional<T&>::reset() noexcept;`]
- * [*Effects:] Same as `*this = none`.
- __SPACE__
- [#reference_optional_ref_reset_value]
- [: `template<class R> void optional<T&>::reset ( R&& r) noexcept;`]
- * [*Effects:] Equivalent to `*this = std::forward<R>(r)`.
- * [*Remarks:] This function is depprecated.
- __SPACE__
- [#reference_optional_ref_is_initialized]
- [: `bool optional<T&>::is_initialized() const noexcept;`]
- * [*Effects:] Equivalent to `return bool(*this)`.
- * [*Remarks:] This function is depprecated.
- __SPACE__
- [#reference_optional_ref_get_value_or_value]
- [: `template<class R> T& optional<T&>::get_value_or( R&& r ) const noexcept;`]
- * [*Effects:] Equivalent to `return value_or(std::forward<R>(r);`.
- * [*Remarks:] This function is depprecated.
- [endsect]
- [section Detailed Semantics - Free Functions]
- __SPACE__
- [#reference_make_optional_value]
- [: `optional<T> make_optional( T const& v )`]
- * [*Returns: ] `optional<T>(v)` for the ['deduced] type `T` of `v`.
- * [*Example:]
- ``
- template<class T> void foo ( optional<T> const& opt ) ;
- foo ( make_optional(1+1) ) ; // Creates an optional<int>
- ``
- __SPACE__
- [#reference_make_optional_rvalue]
- [: `optional<std::decay_t<T>> make_optional( T && v )`]
- * [*Returns: ] `optional<std::decay_t<T>>(std::move(v))` for the ['deduced] type `T` of `v`.
- __SPACE__
- [#reference_make_optional_bool_value]
- [: `optional<T> make_optional( bool condition, T const& v )`]
- * [*Returns: ] `optional<T>(condition, v)` for the ['deduced] type `T` of `v`.
- * [*Example:]
- ``
- optional<double> calculate_foo()
- {
- double val = compute_foo();
- return make_optional(is_not_nan_and_finite(val),val);
- }
- optional<double> v = calculate_foo();
- if ( !v )
- error("foo wasn't computed");
- ``
- __SPACE__
- [#reference_make_optional_bool_rvalue]
- [: `optional<std::decay_t<T>> make_optional( bool condition, T && v )`]
- * [*Returns: ] `optional<std::decay_t<T>>(condition, std::move(v))` for the ['deduced] type `T` of `v`.
- __SPACE__
- [#reference_operator_compare_equal_optional_optional]
- [: `bool operator == ( optional<T> const& x, optional<T> const& y );`]
- * [*Requires:] `T` shall meet requirements of __SGI_EQUALITY_COMPARABLE__.
- * [*Returns:] If both `x` and `y` are initialized, `(*x == *y)`. If only
- `x` or `y` is initialized, `false`. If both are uninitialized, `true`.
- * [*Notes:] This definition guarantees that `optional<T>` not containing a value is compared unequal to any `optional<T>` containing any value, and equal to any other `optional<T>` not containing a value.
- Pointers have shallow relational operators while `optional` has deep relational operators. Do not use `operator==` directly in generic code which expect to be given either an `optional<T>` or a pointer; use
- __FUNCTION_EQUAL_POINTEES__ instead
- * [*Example:]
- ``
- optional<T> oN, oN_;
- optional<T> o1(T(1)), o1_(T(1));
- optional<T> o2(T(2));
- assert ( oN == oN ); // Identity implies equality
- assert ( o1 == o1 ); //
- assert ( oN == oN_ ); // Both uninitialized compare equal
- assert ( oN != o1 ); // Initialized unequal to initialized.
- assert ( o1 == o1_ ); // Both initialized compare as (*lhs == *rhs)
- assert ( o1 != o2 ); //
- ``
- __SPACE__
- [#reference_operator_compare_less_optional_optional]
- [: `bool operator < ( optional<T> const& x, optional<T> const& y );`]
- * [*Requires:] Expression `*x < *y` shall be well-formed and its result shall be convertible to `bool`.
- * [*Returns:] `(!y) ? false : (!x) ? true : *x < *y`.
- * [*Notes:] This definition guarantees that `optional<T>` not containing a value is ordered as less than any `optional<T>` containing any value, and equivalent to any other `optional<T>` not containing a value.
- Pointers have shallow relational operators while `optional` has deep relational operators. Do not use `operator<` directly in generic code
- which expect to be given either an `optional<T>` or a pointer; use __FUNCTION_LESS_POINTEES__ instead. `T` need not be __SGI_LESS_THAN_COMPARABLE__. Only single `operator<` is required. Other relational operations are defined in terms of this one. If `T`'s `operator<` satisfies the axioms of __SGI_LESS_THAN_COMPARABLE__ (transitivity, antisymmetry and irreflexivity), `optinal<T>` is __SGI_LESS_THAN_COMPARABLE__.
- * [*Example:]
- ``
- optional<T> oN, oN_;
- optional<T> o0(T(0));
- optional<T> o1(T(1));
- assert ( !(oN < oN) ); // Identity implies equivalence
- assert ( !(o1 < o1) );
- assert ( !(oN < oN_) ); // Two uninitialized are equivalent
- assert ( !(oN_ < oN) );
- assert ( oN < o0 ); // Uninitialized is less than initialized
- assert ( !(o0 < oN) );
- assert ( o1 < o2 ) ; // Two initialized compare as (*lhs < *rhs)
- assert ( !(o2 < o1) ) ;
- assert ( !(o2 < o2) ) ;
- ``
- __SPACE__
- [#reference_operator_compare_not_equal_optional_optional]
- [: `bool operator != ( optional<T> const& x, optional<T> const& y );`]
- * [*Returns: ] `!( x == y );`
- __SPACE__
- [#reference_operator_compare_greater_optional_optional]
- [: `bool operator > ( optional<T> const& x, optional<T> const& y );`]
- * [*Returns: ] `( y < x );`
- __SPACE__
- [#reference_operator_compare_less_or_equal_optional_optional]
- [: `bool operator <= ( optional<T> const& x, optional<T> const& y );`]
- * [*Returns: ] `!( y < x );`
- __SPACE__
- [#reference_operator_compare_greater_or_equal_optional_optional]
- [: `bool operator >= ( optional<T> const& x, optional<T> const& y );`]
- * [*Returns: ] `!( x < y );`
- __SPACE__
- [#reference_operator_compare_equal_optional_none]
- [: `bool operator == ( optional<T> const& x, none_t ) noexcept;`]
- [: `bool operator == ( none_t, optional<T> const& x ) noexcept;`]
- * [*Returns:] `!x`.
- * [*Notes:] `T` need not meet requirements of __SGI_EQUALITY_COMPARABLE__.
- __SPACE__
- [#reference_operator_compare_not_equal_optional_none]
- [: `bool operator != ( optional<T> const& x, none_t ) noexcept;`]
- [: `bool operator != ( none_t, optional<T> const& x ) noexcept;`]
- * [*Returns: ] `bool(x);`
- __SPACE__
- [#reference_free_get_pointer]
- [: `auto get_pointer ( optional<T>& o ) -> typename optional<T>::pointer_type ;`]
- [: `auto get_pointer ( optional<T> const& o ) -> typename optional<T>::pointer_const_type ;`]
- * [*Returns:] `o.get_ptr()`.
- * [*Throws:] Nothing.
- __SPACE__
- [#reference_free_get_value_or]
- [: `auto get_optional_value_or ( optional<T>& o, typename optional<T>::reference_type def ) -> typename optional<T>::reference_type ;`]
- [: `auto get_optional_value_or ( optional<T> const& o, typename optional<T>::reference_const_type def ) -> typename optional<T>::reference_const_type ;`]
- * [*Returns:] `o.get_value_or(def)`.
- * [*Throws:] Nothing.
- * [*Remarks:] This function is deprecated.
- __SPACE__
- [#reference_swap_optional_optional]
- [: `void swap ( optional<T>& x, optional<T>& y ) ;`]
- * [*Requires:] Lvalues of type `T` shall be swappable and `T` shall be __MOVE_CONSTRUCTIBLE__.
- * [*Effects:]
- [table
- []
- [[][[*`*this` contains a value]][[*`*this` does not contain a value]]]
- [[[*`rhs` contains a value]][calls `swap(*(*this), *rhs)`][initializes the contained value of `*this` as if direct-initializing an object of type `T` with the expression `std::move(*rhs)`, followed by `rhs.val->T::~T()`, `*this` contains a value and `rhs` does not contain a value]]
- [[[*`rhs` does not contain a value]][initializes the contained value of `rhs` as if direct-initializing an object of type `T` with the expression `std::move(*(*this))`, followed by `val->T::~T()`, `*this` does not contain a value and `rhs` contains a value][no effect]]
- ]
- * [*Postconditions:] The states of `x` and `y` interchanged.
- * [*Throws:] If both are initialized, whatever `swap(T&,T&)` throws. If only
- one is initialized, whatever `T::T ( T&& )` throws.
- * [*Example:]
- ``
- T x(12);
- T y(21);
- optional<T> def0 ;
- optional<T> def1 ;
- optional<T> optX(x);
- optional<T> optY(y);
- boost::swap(def0,def1); // no-op
- boost::swap(def0,optX);
- assert ( *def0 == x );
- assert ( !optX );
- boost::swap(def0,optX); // Get back to original values
- boost::swap(optX,optY);
- assert ( *optX == y );
- assert ( *optY == x );
- ``
- __SPACE__
- [#reference_swap_optional_reference]
- [: `void swap ( optional<T&>& x, optional<T&>& y ) noexcept ;`]
- * [*Postconditions:] `x` refers to what `y` refererred to before the swap (if anything). `y` refers to whatever `x` referred to before the swap.
- * [*Example:]
- ``
- T x(12);
- T y(21);
- optional<T&> opt0;
- optional<T&> optX (x);
- optional<T&> optY (y);
- boost::swap(optX, optY);
- assert (addressof(*optX) == addressof(y));
- assert (addressof(*optY) == addressof(x));
- boost::swap(opt0, optX);
- assert ( opt0 );
- assert ( !optX );
- assert (addressof(*opt0) == addressof(y));
- ``
- [endsect]
|