reference.qbk

来自「Boost provides free peer-reviewed portab」· QBK 代码 · 共 882 行 · 第 1/2 页

[/
    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 Synopsis]

    namespace boost {

    template<class T>
    class optional
    {
        public :

        // (If T is of reference type, the parameters and results by reference are by value)

        optional () ; ``[link reference_optional_constructor __GO_TO__]``

        optional ( none_t ) ; ``[link reference_optional_constructor_none_t __GO_TO__]``

        optional ( T const& v ) ; ``[link reference_optional_constructor_value __GO_TO__]``

        // [new in 1.34]
        optional ( bool condition, T const& v ) ; ``[link reference_optional_constructor_bool_value __GO_TO__]`` 

        optional ( optional const& rhs ) ; ``[link reference_optional_constructor_optional __GO_TO__]``

        template<class U> explicit optional ( optional<U> const& rhs ) ; ``[link reference_optional_constructor_other_optional __GO_TO__]``

        template<class InPlaceFactory> explicit optional ( InPlaceFactory const& f ) ; ``[link reference_optional_constructor_factory __GO_TO__]``

        template<class TypedInPlaceFactory> explicit optional ( TypedInPlaceFactory const& f ) ; ``[link reference_optional_constructor_factory __GO_TO__]``

        optional& operator = ( none_t ) ; ``[/[link reference_optional_operator_equal_none_t __GO_TO__]]``

        optional& operator = ( T const& v ) ; ``[link reference_optional_operator_equal_value __GO_TO__]``

        optional& operator = ( optional const& rhs ) ; ``[link reference_optional_operator_equal_optional __GO_TO__]``

        template<class U> optional& operator = ( optional<U> const& rhs ) ; ``[link reference_optional_operator_equal_other_optional __GO_TO__]``

        template<class InPlaceFactory> optional& operator = ( InPlaceFactory const& f ) ; ``[/[link reference_optional_operator_equal_factory __GO_TO__]]``

        template<class TypedInPlaceFactory> optional& operator = ( TypedInPlaceFactory const& f ) ; ``[/[link reference_optional_operator_equal_factory __GO_TO__]]``

        T const& get() const ; ``[link reference_optional_get __GO_TO__]``
        T&       get() ; ``[link reference_optional_get __GO_TO__]``

        // [new in 1.34]
        T const& get_value_or( T const& default ) const ; ``[link reference_optional_get_value_or_value __GO_TO__]`` 

        T const* operator ->() const ; ``[link reference_optional_operator_arrow __GO_TO__]``
        T*       operator ->() ; ``[link reference_optional_operator_arrow __GO_TO__]``

        T const& operator *() const ; ``[link reference_optional_get __GO_TO__]``
        T&       operator *() ; ``[link reference_optional_get __GO_TO__]``

        T const* get_ptr() const ; ``[link reference_optional_get_ptr __GO_TO__]``
        T*       get_ptr() ; ``[link reference_optional_get_ptr __GO_TO__]``

        operator unspecified-bool-type() const ; ``[link reference_optional_operator_bool __GO_TO__]``

        bool operator!() const ; ``[link reference_optional_operator_not __GO_TO__]``

        // deprecated methods

        // (deprecated)
        void reset() ; ``[link reference_optional_reset __GO_TO__]``

        // (deprecated)
        void reset ( T const& ) ; ``[link reference_optional_reset_value __GO_TO__]``

        // (deprecated)
        bool is_initialized() const ; ``[link reference_optional_is_initialized __GO_TO__]``

    };

    template<class T> inline bool operator == ( optional<T> const& x, optional<T> const& y ) ; ``[link reference_operator_compare_equal_optional_optional __GO_TO__]``

    template<class T> inline bool operator != ( optional<T> const& x, optional<T> const& y ) ; ``[link reference_operator_compare_not_equal_optional_optional __GO_TO__]``

    template<class T> inline bool operator <  ( optional<T> const& x, optional<T> const& y ) ; ``[link reference_operator_compare_less_optional_optional __GO_TO__]``

    template<class T> inline bool operator >  ( optional<T> const& x, optional<T> const& y ) ; ``[link reference_operator_compare_greater_optional_optional __GO_TO__]``

    template<class T> inline bool operator <= ( optional<T> const& x, optional<T> const& y ) ; ``[link reference_operator_compare_less_or_equal_optional_optional __GO_TO__]``

    template<class T> inline bool operator >= ( optional<T> const& x, optional<T> const& y ) ; ``[link reference_operator_compare_greater_or_equal_optional_optional __GO_TO__]``

    // [new in 1.34]
    template<class T> inline optional<T> make_optional ( T const& v ) ; ``[link reference_make_optional_value __GO_TO__]``

    // [new in 1.34]
    template<class T> inline optional<T> make_optional ( bool condition, T const& v ) ; ``[link reference_make_optional_bool_value __GO_TO__]``

    // [new in 1.34]
    template<class T> inline T const& get_optional_value_or ( optional<T> const& opt, T const& default ) ; ``[link reference_optional_get_value_or_value __GO_TO__]`` 

    template<class T> inline T const& get ( optional<T> const& opt ) ; ``[link reference_optional_get __GO_TO__]``

    template<class T> inline T& get ( optional<T> & opt ) ; ``[link reference_optional_get __GO_TO__]``

    template<class T> inline T const* get ( optional<T> const* opt ) ; ``[link reference_optional_get __GO_TO__]``

    template<class T> inline T* get ( optional<T>* opt ) ; ``[link reference_optional_get __GO_TO__]``

    template<class T> inline T const* get_pointer ( optional<T> const& opt ) ; ``[link reference_optional_get_ptr __GO_TO__]``

    template<class T> inline T* get_pointer ( optional<T> & opt ) ; ``[link reference_optional_get_ptr __GO_TO__]``

    template<class T> inline void swap( optional<T>& x, optional<T>& y ) ; ``[link reference_swap_optional_optional __GO_TO__]``

    } // namespace boost


[endsect]

[section Detailed Semantics]

Because `T` might be of reference type, in the sequel, those entries whose
semantic depends on `T` being of reference type or not will be distinguished
using the following convention:

* If the entry reads: `optional<T`['(not a ref)]`>`, the description
corresponds only to the case where `T` is not of reference type.
* If the entry reads: `optional<T&>`, the description corresponds only to
the case where `T` is of reference type.
* If the entry reads: `optional<T>`, the description is the same for both
cases.

[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__

[heading optional class member functions]

__SPACE__

[#reference_optional_constructor]

[: `optional<T>::optional();`]

* [*Effect:] Default-Constructs an `optional`.
* [*Postconditions:] `*this` is [_uninitialized].
* [*Throws:] Nothing.
* 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 );`]

* [*Effect:] Constructs an `optional` uninitialized.
* [*Postconditions:] `*this` is [_uninitialized].
* [*Throws:] Nothing.
* [*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 `['(not a ref)]`>::optional( T const& v )`]

* [*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__

[: `optional<T&>::optional( T& ref )`]

* [*Effect:] Directly-Constructs an `optional`.
* [*Postconditions:] `*this` is [_initialized] and its value is an instance
of an internal type wrapping the reference `ref`.
* [*Throws:] Nothing.
* [*Example:]
``
T v;
T& vref = v ;
optional<T&> opt(vref);
assert ( *opt == v ) ;
++ v ; // mutate referee
assert (*opt == v);
``

__SPACE__

[#reference_optional_constructor_bool_value]

[: `optional<T` ['(not a ref)]`>::optional( bool condition, T const& v ) ;` ]
[: `optional<T&>           ::optional( bool condition, T&       v ) ;` ]

* If condition is true, same as:

[: `optional<T` ['(not a ref)]`>::optional( T const& v )`]
[: `optional<T&>           ::optional( T&       v )`]

* otherwise, same as:

[: `optional<T ['(not a ref)]>::optional()`]
[: `optional<T&>           ::optional()`]

__SPACE__

[#reference_optional_constructor_optional]

[: `optional<T `['(not a ref)]`>::optional( optional 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`; 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__

[: `optional<T&>::optional( optional const& rhs );`]

* [*Effect:] Copy-Constructs an `optional`.
* [*Postconditions:] If `rhs` is initialized, `*this` is initialized and its
value is another reference to the same object referenced by `*rhs`; else
`*this` is uninitialized.
* [*Throws:] Nothing.
* [*Notes:] If `rhs` is initialized, both `*this` and `*rhs` will reefer to the
same object (they alias).
* [*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_constructor_other_optional]

[: `template<U> explicit optional<T` ['(not a ref)]`>::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_constructor_factory]

[: `template<InPlaceFactory> explicit optional<T` ['(not a ref)]`>::optional( InPlaceFactory const& f );`]
[: `template<TypedInPlaceFactory> explicit optional<T` ['(not a ref)]`>::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 optional_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_value]

[: `optional& optional<T` ['(not a ref)]`>::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__

[: `optional<T&>& optional<T&>::operator= ( T& const& rhs ) ;`]

* [*Effect:] (Re)binds thee wrapped reference.
* [*Postconditions: ] `*this` is initialized and it references the same
object referenced by `rhs`.
* [*Notes:] If `*this` was initialized, is is ['rebound] to the new object.
See [link optional_refassign here] for details on this behavior.
* [*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_operator_equal_optional]

[: `optional& optional<T` ['(not a ref)]`>::operator= ( optional const& rhs ) ;`]

* [*Effect:] Assigns another `optional` to 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::operator( T const&)` or  `T::T( T const& )` throws.
* [*Notes:] If both `*this` and `rhs` are initially initialized, `T`'s
['assignment operator] is used. If `*this` is initially initialized but `rhs` is
uninitialized, `T`'s [destructor] is called. If `*this` is initially uninitialized
but `rhs` is initialized, `T`'s ['copy constructor] is called.
* [*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 v;
optional<T> opt(v);
optional<T> def ;

opt = def ;
assert ( !def ) ;
// previous value (copy of 'v') destroyed from within 'opt'.
``

__SPACE__

[: `optional<T&> & optional<T&>::operator= ( optional<T&> const& rhs ) ;`]