Detailed Semantics

詳細語義

因為 T 可能是引用類型，所以，那些語義與 T 的類型是否為引用相關的項，將使用以下約定：

如果該項為： optional<T(not a ref)>, 則對應的描述僅適作於T不是引用類型時的情況。
如果該項為：optional<T&>, 則對應的描述僅適用於T是引用類型時的情況。
如果該項為：optional<T>, 則對應的描述適用於兩種情況。

	說明
	以下章節中包含多個 `assert()`，僅用於示範後續條件的例子代碼。它並不意味著類型 `T` 必須支持每個單獨的表達式，但是如果它支持某個表達式，則滿足相應的條件。

space

optional 類的成員函數

space

optional<T>::optional();

作用：缺省構造一個 optional.
後續條件：*this 為未初始化的。
拋出：無。
說明：T 的缺省構造函數未被調用。
例子：
```
optional<T> def ;
assert ( !def ) ;
    
```

space

optional<T>::optional( none_t );

作用：構造一個未初始化的 optional.
後續條件：*this 為未初始化的。
拋出：無。
說明：T 的缺省構造函數未被調用。表達式 boost::none 表示一個 boost::none_t 實例，可用作本構造函數的參數。

例子：

#include <boost/none.hpp>
optional<T> n(none) ;
assert ( !n ) ;

space

optional<T (not a ref)>::optional( T const& v )

作用：直接構造一個 optional.
後續條件：*this 為已初始化的，它的值為 v 的拷貝。
拋出： T::T( T const& ) 所拋出的任何異常。
說明：調用 T::T( T const& ).
異常安全性：僅會在 T::T( T const& ); 中拋出異常，這時構造函數無效。

例子：

T v;
optional<T> opt(v);
assert ( *opt == v ) ;

space

optional<T&>::optional( T& ref )

作用：直接構造一個 optional.
後續條件：*this 為已初始化的，它的值為某個內部類型的實例，包裝了引用 ref.
拋出：無。

例子：

T v;
T& vref = v ;
optional<T&> opt(vref);
assert ( *opt == v ) ;
++ v ; // mutate referee
assert (*opt == v);

space

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

optional<T&> ::optional( bool condition, T& v ) ;

如果 condition 為 true, 則相當於：

optional<T (not a ref)>::optional( T const& v )

optional<T&> ::optional( T& v )

否則相當於：

optional<T [#(not a ref)]>::optional()

optional<T&> ::optional()

space

optional<T (not a ref)>::optional( optional const& rhs );

作用：複製構造一個 optional.
後續條件：如果 rhs 是已初始化的，則 *this 為已初始化的，且值為 rhs 的值的拷貝；否則 *this 為未初始化的。
拋出：T::T( T const& ) 所拋出的任何異常。
說明：如果 rhs 是已初始化的，則調用 T::T(T const& ) .
異常安全性：僅會在 T::T( T const& ); 中拋出異常，這時構造函數無效。

例子：

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 );

作用：複製構造一個 optional.
後續條件：如果 rhs 是已初始化的，則 *this 為已初始化的，且值為 *rhs 所引用的同一個對象的另一個引用；否則 *this 為未初始化的。
拋出：無。
說明：如果 rhs 是已初始化的，則 *this 與 *rhs 均引向同一個對像(它們互為別名)。

例子：

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

template<U> explicit optional<T (not a ref)>::optional( optional<U> const& rhs );

作用：複製構造一個 optional.
後續條件：如果 rhs 是已初始化的，則 *this 為已初始化的，且值為 rhs 轉換為類型T的值的拷貝；否則 *this 為未初始化的。
拋出：T::T( U const& ) 所拋出的任何異常。
說明：如果 rhs 已初始化，則調用 T::T( U const& ), 要求有從 U 到 T 的有效轉換。
異常安全性：僅會在 T::T( U const& ); 中拋出異常，這時構造函數無效。

例子：

optional<double> x(123.4);
assert ( *x == 123.4 ) ;
optional<int> y(x) ;
assert( *y == 123 ) ;

space

template<InPlaceFactory> explicit optional<T (not a ref)>::optional( InPlaceFactory const& f );

template<TypedInPlaceFactory> explicit optional<T (not a ref)>::optional( TypedInPlaceFactory const& f );

作用：構造一個 optional，T 的值從工廠獲得。
後續條件：*this 已初始化且其值直接由工廠 f 取得(即該值不是複製的)。
拋出：由工廠所調用的 T 構造函數所拋出的任何異常。
說明：請見就地創建
異常安全性：僅會在工廠調用T的構造函數時拋出異常，這時構造函數無效。

例子：

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

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

作用：將值 rhs 賦給一個 optional.
後續條件：*this 為已初始化的，其值為 rhs 的拷貝。
拋出：由 T::operator=( T const& ) 或 T::T(T const&) 拋出的任何異常。
說明：如果 *this 是已初始化的，則使用 T 的賦值操作符，否則使用它的複製構造函數。
異常安全性：如果發生異常，*this 的初始化狀態不會改變，它的值是不確定的直至 optional 被關聯(由 T 的 operator=() 進行)。如 **this 原來是未初始化的，且 T 的複製構造函數 失敗了，則 *this 仍為未初始化的。

例子：

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 ) ;

作用：(重)綁定被包裝的引用。
後續條件：*this 已初始化且引向由 rhs 所引向的對象。
說明：如果 *this 已初始化，則重綁定到新的對象。有關細節請見這裡。

例子：

int a = 1 ;
int b = 2 ;
T& ra = a ;
T& rb = b ;
optional<int&> def ;
optional<int&> opt(ra) ;
def = rb ; // 通過 'rb' 將 'def' 綁定到 'b'
assert ( *def == b ) ;
*def = a ; // 將 'b' 的值修改為 'a' 的值的拷貝
assert ( b == a ) ;
int c = 3;
int& rc = c ;
opt = rc ; // 通過 'rc' 綁定到 'c'
c = 4 ;
assert ( *opt == 4 ) ;

space

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

作用：將另一個 optional 賦值給一個 optional.
後續條件：如果 rhs 已初始化，則 *this 為已初始化且其值為 rhs 值的拷貝；否則 *this 為未初始化。
拋出：由 T::operator( T const&) 或 T::T( T const& ) 拋出的任何異常。
說明：如果*this 和 rhs 均已初始化，則使用 T 的 賦值操作符。如果 *this 已初始化而 rhs 未初始化，則調用 T 的 析構函數。如果 *this 未初始化而 rhs 已初始化，則調用 T 的 複製構造函數。
異常安全性：發生異常時，*this 的初始化狀態不改變，其值是不確定的直至 optional 被關聯(由 T 的 operator=() 進行) [如果 *this 原來是未初始化的而且 T 的 複製構造函數 失敗，則 *this 保持為未初始化]

例子：

T v;
optional<T> opt(v);
optional<T> def ;
opt = def ;
assert ( !def ) ;
// 'opt'的原值('v'的拷貝)被銷毀

space

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

作用：(重)綁定被包裝的引用。
後續條件：如果 *rhs 已初始化，則 *this 為已初始化的且引向且引向由 *rhs 所引向的對象；否則 *this 為未初始化(不引向任何對像)。
說明：如果 *this 已初始化且 *rhs 也是，則重綁定到新的對象。有關細節請見這裡。

例子：

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 ; // 通過'orb'中包裝的'rb'將'def'綁定到'b'
assert ( *def == b ) ;
*def = ora ; // 將'b'的值修改為'a'值的拷貝
assert ( b == a ) ;
int c = 3;
int& rc = c ;
optional<int&> orc(rc) ;
ora = orc ; // 通過'rc'將ora重綁定到'c'
c = 4 ;
assert ( *ora == 4 ) ;

space

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

作用：將另一個可轉換的 optional 賦值給一個 optional.
後續條件：如果 rhs 已初始化，則 *this 也是已初始化的，且其值為 rhs 轉換為類型 T 後的值的拷貝；否則 *this 為未初始化。
拋出：由 T::operator=( U const& ) 或 T::T( U const& ) 拋出的任何異常。
說明：如果*this 和 rhs 均已初始化，則使用 T 的 賦值操作符 (from U)。如果 *this 已初始化而 rhs 未初始化，則調用 T 的 析構函數。如果 *this 未初始化而 rhs 已初始化，則調用 T 的 轉換構造函數 (從 U 轉換)。
異常安全性：發生異常時，*this 的初始化狀態不改變，其值是不確定的直至 optional 被關聯(由 T 的 operator=() 進行)。如果 *this 原來是未初始化的而且 T 的 轉換構造函數 失敗，則 *this 保持為未初始化。

例子：

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

space

void optional<T (not a ref)>::reset( T const& v ) ;

不建議使用：相當於 operator= ( T const& v) ;

space

void optional<T>::reset() ;

不建議使用：相當於 operator=( detail::none_t );

space

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)> &) ;

要求：*this 已初始化。
返回：所含值的引用。
拋出：無。
說明：以 BOOST_ASSERT() 對前提條件進行斷言。

例子：

T v ;
optional<T> opt ( v );
T const& u = *opt;
assert ( u == v ) ;
T w ;
*opt = w ;
assert ( *opt == w ) ;

space

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 ) ;

返回：如果有，則返回所含值(本身可以是引用)的引用, 否則返回 default.
拋出：無。

例子：

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&> &) ;

要求：*this 已初始化。
返回：所包含的引用。
拋出：無。
說明：以 BOOST_ASSERT() 對前提條件進行斷言。

例子：

T v ;
T& vref = v ;
optional<T&> opt ( vref );
T const& vref2 = *opt;
assert ( vref2 == v ) ;
++ v ;
assert ( *opt == v ) ;

space

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)> &) ;

返回：如果 *this 已初始化，則返回所含值的指針；否則返回 0 (null).
拋出：無。
說明：所含值被 *this 永久保留，所以你不能持有或刪除該指針。

例子：

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

T const* optional<T (not a ref)>::operator ->() const ;

T* optional<T (not a ref)>::operator ->() ;

要求：*this 已初始化。
返回：所含值的指針。
拋出：無。
說明：以 BOOST_ASSERT() 對前提條件進行斷言。

例子：

struct X { int mdata ; } ;
X x ;
optional<X> opt (x);
opt->mdata = 2 ;

space

optional<T>::operator unspecified-bool-type() const ;

返回：一個未明確規定的值，該值可用於布爾上下文中，等同於 (get() != 0)
拋出：無。

例子：

optional<T> def ;
assert ( def == 0 );
optional<T> opt ( v ) ;
assert ( opt );
assert ( opt != 0 );

space

bool optional<T>::operator!() ;

返回：如果 *this 未初始化，則返回 true; 否則返回 false.
拋出：無。
說明：該操作提供給那些不能在布爾上下文中使用 unspecified-bool-type 操作符的編譯器使用。

例子：

optional<T> opt ;
assert ( !opt );
*opt = some_T ;
// 注意這裡的 "double-bang" 用法。
assert ( !!opt ) ;

space

bool optional<T>::is_initialized() const ;

返回：true 如果 optional 已初始化，否則 false .
拋出：無。

例子：

optional<T> def ;
assert ( !def.is_initialized() );
optional<T> opt ( v ) ;
assert ( opt.is_initialized() );

space

Free functions

space

optional<T (not a ref)> make_optional( T const& v )

返回：optional<T>(v)，從 v 推斷類型 T .

例子：

template<class T> void foo ( optional<T> const& opt ) ;
foo ( make_optional(1+1) ) ; // 創建一個 optional<int>

space

optional<T (not a ref)> make_optional( bool condition, T const& v )

返回：optional<T>(condition,v)，從 v 推斷類型 T .

例子：

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

bool operator == ( optional<T> const& x, optional<T> const& y );

返回：如果 x 和 y 均已初始化，則返回 (*x == *y). 如果只有 x 或 y 已初始化，則返回 false. 如果均未初始化，則返回 true.
拋出：無。
說明：指針的比較操作符是"淺比較"的，而 optional 是"深比較"的。不要在使用 optional<T> 或指針的泛型代碼中直接使用 operator ==；應使用 equal_pointees() 來替代。

例子：

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);
// 總是保持同一性
assert ( def0 == def0 );
assert ( optX == optX );
// 未初始化的對象是相等的
assert ( def0 == def1 );
// 只有一個初始化對像則是不等的
assert ( def0 != optX );
// 已初始化的對象則要比較 (*lhs == *rhs)
assert ( optX == optY ) ;
assert ( optX != optZ ) ;

space

bool operator < ( optional<T> const& x, optional<T> const& y );

返回：如果 y 未初始化，則返回 false. 如果 y 已初始而 x 未初始化，則返回 true. 如果 x 和 y 均已初始化，則返回 (*x < *y).
拋出：無。
說明：指針的比較操作符是"淺比較"的，而 optional 是"深比較"的。不要在使用 optional<T> 或指針的泛型代碼中直接使用 operator <；應使用 less_pointees() 來替代。

例子：

T x(12);
T y(34);
optional<T> def ;
optional<T> optX(x);
optional<T> optY(y);
// 總是保持同一性
assert ( !(def < def) );
assert ( optX == optX );
// 兩個未初始化對象是相等的
assert ( def0 == def1 );
// 只有一個已初始化對像則是不等的
assert ( def0 != optX );
// 兩個已初始化對像則要比較 (*lhs == *rhs)
assert ( optX == optY ) ;
assert ( optX != optZ ) ;

space

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

返回：!( x == y );
拋出：無。

space

bool operator > ( optional<T> const& x, optional<T> const& y );

返回：( y < x );
拋出：無。

space

bool operator <= ( optional<T> const& x, optional<T> const& y );

返回：!( y<x );
拋出：無。

space

bool operator >= ( optional<T> const& x, optional<T> const& y );

返回：!( x<y );
拋出：無。

space

void swap ( optional<T>& x, optional<T>& y );

作用：如果 x 和 y 均已初始化，則調用 swap(*x,*y)，使用 std::swap. 如果只有一個已初始化，如 x, 則調用：y = *x; x = boost:none;
如果均未初始化，則為空操作。
後續條件：x 和 y 的狀態被交換。
拋出：如果均已初始化，則拋出 swap(T&,T&) 所拋出的任何異常。如果只有一個已初始化，則拋出 T::T ( T const& ) 所拋出的任何異常。
說明：如果均已初始化，則使用未限定的 swap(T&,T&)，不過 std::swap 被引入到當前域中。如果只有一個已初始化，則調用 T::~T() 和 T::T( T const& ) .
異常安全性：如果均已初始化，則該操作具有 swap(T&,T&) 的異常安全性保證。如果只有一個已初始化，則該操作具有和 optional<T>::reset( T const& ) 一樣的基本保證。

例子：

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 );