reference.qbk

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

* [*Effect:] (Re)binds thee wrapped reference.
* [*Postconditions:] If `*rhs` is initialized, `*this` is initialized and it
references the same object referenced by `*rhs`; otherwise, `*this` is
uninitialized (and references no object).
* [*Notes:] If `*this` was initialized and so is *rhs, this 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&> 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 ) ;
``

__SPACE__

[#reference_optional_operator_equal_other_optional]

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

* [*Effect:] Assigns another convertible optional to 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::operator=( U const& )` or `T::T( U const& )` throws.
* [*Notes:] If both `*this` and rhs are initially initialized, `T`'s
['assignment operator] (from `U`) 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 ['converting constructor]
(from `U`) 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 converting constructor fails, `*this` is left properly
uninitialized.
* [*Example:]
``
T v;
optional<T> opt0(v);
optional<U> opt1;

opt1 = opt0 ;
assert ( *opt1 == static_cast<U>(v) ) ;
``

__SPACE__

[#reference_optional_reset_value]

[: `void optional<T` ['(not a ref)]`>::reset( T const& v ) ;`]
* [*Deprecated:] same as `operator= ( T const& v) ;`

__SPACE__

[#reference_optional_reset]

[: `void optional<T>::reset() ;`]
* [*Deprecated:] Same as `operator=( detail::none_t );`

__SPACE__

[#reference_optional_get]

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

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

* [*Requirements:] `*this` is initialized
* [*Returns:] A reference to the contained value
* [*Throws:] Nothing.
* [*Notes:] The requirement is asserted via `BOOST_ASSERT()`.
* [*Example:]
``
T v ;
optional<T> opt ( v );
T const& u = *opt;
assert ( u == v ) ;
T w ;
*opt = w ;
assert ( *opt == w ) ;
``

__SPACE__

[#reference_optional_get_value_or_value]

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

[: `inline T const& get_optional_value_or ( optional<T` ['(not a ref)]`> const& o, T const& default ) ;`]
[: `inline T&       get_optional_value_or ( optional<T` ['(not a ref)]`>&       o, T&       default ) ;`]

* [*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 = get_optional_value_or(opt,z);
assert ( u == v ) ;
assert ( u != z ) ;
``

__SPACE__

[: `T const& optional<T&>::operator*() const ;`]
[: `T      & optional<T&>::operator*();`]
[: `T const& optional<T&>::get() const ;`]
[: `T&       optional<T&>::get() ;`]

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

* [*Requirements: ] `*this` is initialized
* [*Returns:] [_The] reference contained.
* [*Throws:] Nothing.
* [*Notes:] The requirement is asserted via `BOOST_ASSERT()`.
* [*Example:]
``
T v ;
T& vref = v ;
optional<T&> opt ( vref );
T const& vref2 = *opt;
assert ( vref2 == v ) ;
++ v ;
assert ( *opt == v ) ;
``

__SPACE__

[#reference_optional_get_ptr]

[: `T const* optional<T` ['(not a ref)]`>::get_ptr() const ;`]
[: `T*       optional<T` ['(not a ref)]`>::get_ptr() ;`]

[: `inline T const* get_pointer ( optional<T` ['(not a ref)]`> const& ) ;`]
[: `inline T*       get_pointer ( optional<T` ['(not a ref)]`> &) ;`]

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

* [*Requirements: ] `*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]

[: `optional<T>::operator `['unspecified-bool-type]`() const ;`]

* [*Returns:] An unspecified value which if used on a boolean context
is equivalent to (`get() != 0`)
* [*Throws:] Nothing.
* [*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!() ;`]

* [*Returns:] If `*this` is uninitialized, `true`; else `false`.
* [*Throws:] Nothing.
* [*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 ;`]

* [*Returns: ] `true` if the `optional` is initialized, `false` otherwise.
* [*Throws:] Nothing.
* [*Example:]
``
optional<T> def ;
assert ( !def.is_initialized() );
optional<T> opt ( v ) ;
assert ( opt.is_initialized() );
``

__SPACE__

[heading Free functions]

__SPACE__

[#reference_make_optional_value]

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

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

[: `bool operator == ( optional<T> const& x, optional<T> const& y );`]

* [*Returns:] If both `x` and `y` are initialized, `(*x == *y)`. If only
`x` or `y` is initialized, `false`. If both are uninitialized, `true`.
* [*Throws:] Nothing.
* [*Notes:] 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:]
``
T x(12);
T y(12);
T z(21);
optional<T> def0 ;
optional<T> def1 ;
optional<T> optX(x);
optional<T> optY(y);
optional<T> optZ(z);

// Identity always hold
assert ( def0 == def0 );
assert ( optX == optX );

// Both uninitialized compare equal
assert ( def0 == def1 );

// Only one initialized compare unequal.
assert ( def0 != optX );

// Both initialized compare as (*lhs == *rhs)
assert ( optX == optY ) ;
assert ( optX != optZ ) ;
``

__SPACE__

[#reference_operator_compare_less_optional_optional]

[: `bool operator < ( optional<T> const& x, optional<T> const& y );`]

* [*Returns:] If `y` is not initialized, `false`. If `y` is initialized
and `x` is not initialized, `true`. If both `x` and `y` are initialized,
`(*x < *y)`.
* [*Throws:] Nothing.
* [*Notes:] 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.
* [*Example:]
``
T x(12);
T y(34);
optional<T> def ;
optional<T> optX(x);
optional<T> optY(y);

// Identity always hold
assert ( !(def < def) );
assert ( optX == optX );

// Both uninitialized compare equal
assert ( def0 == def1 );

// Only one initialized compare unequal.
assert ( def0 != optX );

// Both initialized compare as (*lhs == *rhs)
assert ( optX == optY ) ;
assert ( optX != optZ ) ;
``

__SPACE__

[#reference_operator_compare_not_equal_optional_optional]

[: `bool operator != ( optional<T> const& x, optional<T> const& y );`]

* [*Returns: ] `!( x == y );`
* [*Throws:] Nothing.

__SPACE__

[#reference_operator_compare_greater_optional_optional]

[: `bool operator > ( optional<T> const& x, optional<T> const& y );`]

* [*Returns: ] `( y < x );`
* [*Throws:] Nothing.

__SPACE__

[#reference_operator_compare_less_or_equal_optional_optional]

[: `bool operator <= ( optional<T> const& x, optional<T> const& y );`]

* [*Returns: ] `!( y<x );`
* [*Throws:] Nothing.

__SPACE__

[#reference_operator_compare_greater_or_equal_optional_optional]

[: `bool operator >= ( optional<T> const& x, optional<T> const& y );`]

* [*Returns: ] `!( x<y );`
* [*Throws:] Nothing.

__SPACE__

[#reference_swap_optional_optional]

[: `void swap ( optional<T>& x, optional<T>& y );`]

* [*Effect:] If both `x` and `y` are initialized, calls `swap(*x,*y)`
using `std::swap`. If only one is initialized, say `x`, calls:
`y.reset(*x); x.reset();` If none is initialized, does nothing.
* [*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 const& )` throws.
* [*Notes:] If both are initialized, `swap(T&,T&)` is used unqualified but
with `std::swap` introduced in scope.
If only one is initialized, `T::~T()` and `T::T( T const& )` is called.
* [*Exception Safety:] If both are initialized, this operation has the
exception safety guarantees of `swap(T&,T&)`.
If only one is initialized, it has the same basic guarantee as
`optional<T>::reset( T const& )`.
* [*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 );
``

[endsect]