boost_1_45_0/libs/optional/doc/special_cases.qbk - nest-learning-thermostat/5.0/boost - Git at Google


 [section Optional references]

 This library allows the template parameter `T` to be of reference type:
 `T&`, and to some extent, `T const&`.

 However, since references are not real objects some restrictions apply and
 some operations are not available in this case:

 * Converting constructors
 * Converting assignment
 * InPlace construction
 * InPlace assignment
 * Value-access via pointer

 Also, even though `optional<T&>` treats it wrapped pseudo-object much as
 a real value, a true real reference is stored so aliasing will ocurr:

 * Copies of `optional<T&>` will copy the references but all these references
 will nonetheless reefer to the same object.
 * Value-access will actually provide access to the referenced object
 rather than the reference itself.

 [endsect]

 [section Rebinding semantics for assignment of optional references]

 If you assign to an ['uninitialized ] `optional<T&>` the effect is to bind (for
 the first time) to the object. Clearly, there is no other choice.

     int x = 1 ;
     int& rx = x ;
     optional<int&> ora ;
     optional<int&> orb(x) ;
     ora = orb ; // now 'ora' is bound to 'x' through 'rx'
     *ora = 2 ; // Changes value of 'x' through 'ora'
     assert(x==2);

 If you assign to a bare C++ reference, the assignment is forwarded to the
 referenced object; it's value changes but the reference is never rebound.

     int a = 1 ;
     int& ra = a ;
     int b = 2 ;
     int& rb = b ;
     ra = rb ; // Changes the value of 'a' to 'b'
     assert(a==b);
     b = 3 ;
     assert(ra!=b); // 'ra' is not rebound to 'b'

 Now, if you assign to an ['initialized ] `optional<T&>`, the effect is to
 [*rebind] to the new object instead of assigning the referee. This is unlike
 bare C++ references.

     int a = 1 ;
     int b = 2 ;
     int& ra = a ;
     int& rb = b ;
     optional<int&> ora(ra) ;
     optional<int&> orb(rb) ;
     ora = orb ; // 'ora' is rebound to 'b'
     *ora = 3 ; // Changes value of 'b' (not 'a')
     assert(a==1);
     assert(b==3);

 [heading Rationale]

 Rebinding semantics for the assignment of ['initialized ] `optional` references has
 been chosen to provide [*consistency among initialization states] even at the
 expense of lack of consistency with the semantics of bare C++ references.
 It is true that `optional<U>` strives to behave as much as possible as `U`
 does whenever it is initialized; but in the case when `U` is `T&`, doing so would
 result in inconsistent behavior w.r.t to the lvalue initialization state.

 Imagine `optional<T&>` forwarding assignment to the referenced object (thus
 changing the referenced object value but not rebinding), and consider the
 following code:

     optional<int&> a = get();
     int x = 1 ;
     int& rx = x ;
     optional<int&> b(rx);
     a = b ;

 What does the assignment do?

 If `a` is ['uninitialized], the answer is clear: it binds to `x` (we now have
 another reference to `x`).
 But what if `a` is already ['initialized]? it would change the value of the
 referenced object (whatever that is); which is inconsistent with the other
 possible case.

 If `optional<T&>` would assign just like `T&` does, you would never be able to
 use Optional's assignment without explicitly handling the previous
 initialization state unless your code is capable of functioning whether
 after the assignment, `a` aliases the same object as `b` or not.

 That is, you would have to discriminate in order to be consistency.

 If in your code rebinding to another object is not an option, then is very
 likely that binding for the fist time isn't either. In such case, assignment
 to an ['uninitialized ] `optional<T&>` shall be prohibited. It is quite possible
 that in such scenario the precondition that the lvalue must be already
 initialized exist. If it doesn't, then binding for the first time is OK
 while rebinding is not which is IMO very unlikely.
 In such scenario, you can assign the value itself directly, as in:

     assert(!!opt);
     *opt=value;

 [endsect]

 [section In-Place Factories]

 One of the typical problems with wrappers and containers is that their
 interfaces usually provide an operation to initialize or assign the
 contained object as a copy of some other object. This not only requires the
 underlying type to be __COPY_CONSTRUCTIBLE__, but also requires the existence of
 a fully constructed object, often temporary, just to follow the copy from:

     struct X
     {
         X ( int, std:::string ) ;
     } ;

     class W
     {
         X wrapped_ ;

         public:

         W ( X const& x ) : wrapped_(x) {}
     } ;

     void foo()
     {
         // Temporary object created.
         W ( X(123,"hello") ) ;
     }

 A solution to this problem is to support direct construction of the
 contained object right in the container's storage.
 In this scheme, the user only needs to supply the arguments to the
 constructor to use in the wrapped object construction.

     class W
     {
         X wrapped_ ;

         public:

         W ( X const& x ) : wrapped_(x) {}
         W ( int a0, std::string a1) : wrapped_(a0,a1) {}
     } ;

     void foo()
     {
         // Wrapped object constructed in-place
         // No temporary created.
         W (123,"hello") ;
     }

 A limitation of this method is that it doesn't scale well to wrapped
 objects with multiple constructors nor to generic code were the constructor
 overloads are unknown.

 The solution presented in this library is the family of [*InPlaceFactories]
 and [*TypedInPlaceFactories].
 These factories are a family of classes which encapsulate an increasing
 number of arbitrary constructor parameters and supply a method to construct
 an object of a given type using those parameters at an address specified by
 the user via placement new.

 For example, one member of this family looks like:

     template<class T,class A0, class A1>
     class TypedInPlaceFactory2
     {
         A0 m_a0 ; A1 m_a1 ;

         public:

         TypedInPlaceFactory2( A0 const& a0, A1 const& a1 ) : m_a0(a0), m_a1(a1) {}

         void construct ( void* p ) { new (p) T(m_a0,m_a1) ; }
      } ;

 A wrapper class aware of this can use it as:

     class W
     {
         X wrapped_ ;

         public:

         W ( X const& x ) : wrapped_(x) {}
         W ( TypedInPlaceFactory2 const& fac ) { fac.construct(&wrapped_) ; }
     } ;

     void foo()
     {
         // Wrapped object constructed in-place via a TypedInPlaceFactory.
         // No temporary created.
         W ( TypedInPlaceFactory2<X,int,std::string>(123,"hello")) ;
     }

 The factories are divided in two groups:

 * [_TypedInPlaceFactories]: those which take the target type as a primary
 template parameter.
 * [_InPlaceFactories]: those with a template `construct(void*)` member
 function taking the target type.

 Within each group, all the family members differ only in the number of
 parameters allowed.

 This library provides an overloaded set of helper template functions to
 construct these factories without requiring unnecessary template parameters:

     template<class A0,...,class AN>
     InPlaceFactoryN <A0,...,AN> in_place ( A0 const& a0, ..., AN const& aN) ;

     template<class T,class A0,...,class AN>
     TypedInPlaceFactoryN <T,A0,...,AN> in_place ( T const& a0, A0 const& a0, ..., AN const& aN) ;

 In-place factories can be used generically by the wrapper and user as follows:

     class W
     {
         X wrapped_ ;

         public:

         W ( X const& x ) : wrapped_(x) {}

         template< class InPlaceFactory >
         W ( InPlaceFactory const& fac ) { fac.template <X>construct(&wrapped_) ; }

     } ;

     void foo()
     {
         // Wrapped object constructed in-place via a InPlaceFactory.
         // No temporary created.
         W ( in_place(123,"hello") ) ;
     }

 The factories are implemented in the headers: __IN_PLACE_FACTORY_HPP__ and __TYPED_IN_PLACE_FACTORY_HPP__

 [endsect]

 [section A note about optional<bool>]

 `optional<bool>` should be used with special caution and consideration.

 First, it is functionally similar to a tristate boolean (false,maybe,true)
 —such as __BOOST_TRIBOOL__— except that in a tristate boolean, the maybe state
 [_represents a valid value], unlike the corresponding state of an uninitialized
 `optional<bool>`.
 It should be carefully considered if an `optional<bool>` instead of a `tribool`
 is really needed.

 Second, `optional<>` provides an implicit conversion to `bool`. This
 conversion refers to the initialization state and not to the contained value.
 Using `optional<bool>` can lead to subtle errors due to the implicit `bool`
 conversion:

     void foo ( bool v ) ;
     void bar()
     {
         optional<bool> v = try();

         // The following intended to pass the value of 'v' to foo():
         foo(v);
         // But instead, the initialization state is passed
         // due to a typo: it should have been foo(*v).
     }

 The only implicit conversion is to `bool`, and it is safe in the sense that
 typical integral promotions don't apply (i.e. if `foo()` takes an `int`
 instead, it won't compile).

 [endsect]

 [section Exception Safety Guarantees]

 Because of the current implementation (see [link boost_optional.implementation_notes Implementation Notes]), all of the assignment methods:

 * `optional<T>::operator= ( optional<T> const& )`
 * `optional<T>::operator= ( T const& )`
 * `template<class U> optional<T>::operator= ( optional<U> const& )`
 * `template<class InPlaceFactory> optional<T>::operator= ( InPlaceFactory const& )`
 * `template<class TypedInPlaceFactory> optional<T>::operator= ( TypedInPlaceFactory const& ) `
 * `optional<T>:::reset ( T const&)`

 Can only ['guarantee] the [_basic exception safety]: The lvalue optional is
 left [_uninitialized] if an exception is thrown (any previous value is ['first]
 destroyed using `T::~T()`)

 On the other hand, the ['uninitializing] methods:

 * `optional<T>::operator= ( detail::none_t )`
 * `optional<T>::reset()`

 Provide the no-throw guarantee (assuming a no-throw `T::~T()`)

 However, since `optional<>` itself doesn't throw any exceptions, the only
 source for exceptions here are `T`'s constructor, so if you know the exception
 guarantees for `T::T ( T const& )`, you know that `optional`'s assignment and
 reset has the same guarantees.

     //
     // Case 1: Exception thrown during assignment.
     //
     T v0(123);
     optional<T> opt0(v0);
     try
     {
         T v1(456);
         optional<T> opt1(v1);
         opt0 = opt1 ;

         // If no exception was thrown, assignment succeeded.
         assert( *opt0 == v1 ) ;
     }
     catch(...)
     {
         // If any exception was thrown, 'opt0' is reset to uninitialized.
         assert( !opt0 ) ;
     }

     //
     // Case 2: Exception thrown during reset(v)
     //
     T v0(123);
     optional<T> opt(v0);
     try
     {
         T v1(456);
         opt.reset ( v1 ) ;

         // If no exception was thrown, reset succeeded.
         assert( *opt == v1 ) ;
     }
     catch(...)
     {
         // If any exception was thrown, 'opt' is reset to uninitialized.
         assert( !opt ) ;
     }

 [heading Swap]

 `void swap( optional<T>&, optional<T>& )` has the same exception guarantee
 as `swap(T&,T&)` when both optionals are initialized.
 If only one of the optionals is initialized, it gives the same ['basic]
 exception guarantee as `optional<T>::reset( T const& )` (since
 `optional<T>::reset()` doesn't throw).
 If none of the optionals is initialized, it has no-throw guarantee
 since it is a no-op.

 [endsect]

 [section Type requirements]

 In general, `T` must be __COPY_CONSTRUCTIBLE__ and have a no-throw destructor.
 The copy-constructible requirement is not needed if [*InPlaceFactories] are used.

 `T` [_is not] required to be __SGI_DEFAULT_CONSTRUCTIBLE__.

 [endsect]

	[section Optional references]

	This library allows the template parameter `T` to be of reference type:
	`T&`, and to some extent, `T const&`.

	However, since references are not real objects some restrictions apply and
	some operations are not available in this case:

	* Converting constructors
	* Converting assignment
	* InPlace construction
	* InPlace assignment
	* Value-access via pointer

	Also, even though `optional<T&>` treats it wrapped pseudo-object much as
	a real value, a true real reference is stored so aliasing will ocurr:

	* Copies of `optional<T&>` will copy the references but all these references
	will nonetheless reefer to the same object.
	* Value-access will actually provide access to the referenced object
	rather than the reference itself.

	[endsect]

	[section Rebinding semantics for assignment of optional references]

	If you assign to an ['uninitialized ] `optional<T&>` the effect is to bind (for
	the first time) to the object. Clearly, there is no other choice.

	int x = 1 ;
	int& rx = x ;
	optional<int&> ora ;
	optional<int&> orb(x) ;
	ora = orb ; // now 'ora' is bound to 'x' through 'rx'
	*ora = 2 ; // Changes value of 'x' through 'ora'
	assert(x==2);

	If you assign to a bare C++ reference, the assignment is forwarded to the
	referenced object; it's value changes but the reference is never rebound.

	int a = 1 ;
	int& ra = a ;
	int b = 2 ;
	int& rb = b ;
	ra = rb ; // Changes the value of 'a' to 'b'
	assert(a==b);
	b = 3 ;
	assert(ra!=b); // 'ra' is not rebound to 'b'

	Now, if you assign to an ['initialized ] `optional<T&>`, the effect is to
	[*rebind] to the new object instead of assigning the referee. This is unlike
	bare C++ references.

	int a = 1 ;
	int b = 2 ;
	int& ra = a ;
	int& rb = b ;
	optional<int&> ora(ra) ;
	optional<int&> orb(rb) ;
	ora = orb ; // 'ora' is rebound to 'b'
	*ora = 3 ; // Changes value of 'b' (not 'a')
	assert(a==1);
	assert(b==3);

	[heading Rationale]

	Rebinding semantics for the assignment of ['initialized ] `optional` references has
	been chosen to provide [*consistency among initialization states] even at the
	expense of lack of consistency with the semantics of bare C++ references.
	It is true that `optional<U>` strives to behave as much as possible as `U`
	does whenever it is initialized; but in the case when `U` is `T&`, doing so would
	result in inconsistent behavior w.r.t to the lvalue initialization state.

	Imagine `optional<T&>` forwarding assignment to the referenced object (thus
	changing the referenced object value but not rebinding), and consider the
	following code:

	optional<int&> a = get();
	int x = 1 ;
	int& rx = x ;
	optional<int&> b(rx);
	a = b ;

	What does the assignment do?

	If `a` is ['uninitialized], the answer is clear: it binds to `x` (we now have
	another reference to `x`).
	But what if `a` is already ['initialized]? it would change the value of the
	referenced object (whatever that is); which is inconsistent with the other
	possible case.

	If `optional<T&>` would assign just like `T&` does, you would never be able to
	use Optional's assignment without explicitly handling the previous
	initialization state unless your code is capable of functioning whether
	after the assignment, `a` aliases the same object as `b` or not.

	That is, you would have to discriminate in order to be consistency.

	If in your code rebinding to another object is not an option, then is very
	likely that binding for the fist time isn't either. In such case, assignment
	to an ['uninitialized ] `optional<T&>` shall be prohibited. It is quite possible
	that in such scenario the precondition that the lvalue must be already
	initialized exist. If it doesn't, then binding for the first time is OK
	while rebinding is not which is IMO very unlikely.
	In such scenario, you can assign the value itself directly, as in:

	assert(!!opt);
	*opt=value;

	[endsect]

	[section In-Place Factories]

	One of the typical problems with wrappers and containers is that their
	interfaces usually provide an operation to initialize or assign the
	contained object as a copy of some other object. This not only requires the
	underlying type to be __COPY_CONSTRUCTIBLE__, but also requires the existence of
	a fully constructed object, often temporary, just to follow the copy from:

	struct X
	{
	X ( int, std:::string ) ;
	} ;

	class W
	{
	X wrapped_ ;

	public:

	W ( X const& x ) : wrapped_(x) {}
	} ;

	void foo()
	{
	// Temporary object created.
	W ( X(123,"hello") ) ;
	}

	A solution to this problem is to support direct construction of the
	contained object right in the container's storage.
	In this scheme, the user only needs to supply the arguments to the
	constructor to use in the wrapped object construction.

	class W
	{
	X wrapped_ ;

	public:

	W ( X const& x ) : wrapped_(x) {}
	W ( int a0, std::string a1) : wrapped_(a0,a1) {}
	} ;

	void foo()
	{
	// Wrapped object constructed in-place
	// No temporary created.
	W (123,"hello") ;
	}

	A limitation of this method is that it doesn't scale well to wrapped
	objects with multiple constructors nor to generic code were the constructor
	overloads are unknown.

	The solution presented in this library is the family of [*InPlaceFactories]
	and [*TypedInPlaceFactories].
	These factories are a family of classes which encapsulate an increasing
	number of arbitrary constructor parameters and supply a method to construct
	an object of a given type using those parameters at an address specified by
	the user via placement new.

	For example, one member of this family looks like:

	template<class T,class A0, class A1>
	class TypedInPlaceFactory2
	{
	A0 m_a0 ; A1 m_a1 ;

	public:

	TypedInPlaceFactory2( A0 const& a0, A1 const& a1 ) : m_a0(a0), m_a1(a1) {}

	void construct ( void* p ) { new (p) T(m_a0,m_a1) ; }
	} ;

	A wrapper class aware of this can use it as:

	class W
	{
	X wrapped_ ;

	public:

	W ( X const& x ) : wrapped_(x) {}
	W ( TypedInPlaceFactory2 const& fac ) { fac.construct(&wrapped_) ; }
	} ;

	void foo()
	{
	// Wrapped object constructed in-place via a TypedInPlaceFactory.
	// No temporary created.
	W ( TypedInPlaceFactory2<X,int,std::string>(123,"hello")) ;
	}

	The factories are divided in two groups:

	* [_TypedInPlaceFactories]: those which take the target type as a primary
	template parameter.
	* [_InPlaceFactories]: those with a template `construct(void*)` member
	function taking the target type.

	Within each group, all the family members differ only in the number of
	parameters allowed.

	This library provides an overloaded set of helper template functions to
	construct these factories without requiring unnecessary template parameters:

	template<class A0,...,class AN>
	InPlaceFactoryN <A0,...,AN> in_place ( A0 const& a0, ..., AN const& aN) ;

	template<class T,class A0,...,class AN>
	TypedInPlaceFactoryN <T,A0,...,AN> in_place ( T const& a0, A0 const& a0, ..., AN const& aN) ;

	In-place factories can be used generically by the wrapper and user as follows:

	class W
	{
	X wrapped_ ;

	public:

	W ( X const& x ) : wrapped_(x) {}

	template< class InPlaceFactory >
	W ( InPlaceFactory const& fac ) { fac.template <X>construct(&wrapped_) ; }

	} ;

	void foo()
	{
	// Wrapped object constructed in-place via a InPlaceFactory.
	// No temporary created.
	W ( in_place(123,"hello") ) ;
	}

	The factories are implemented in the headers: __IN_PLACE_FACTORY_HPP__ and __TYPED_IN_PLACE_FACTORY_HPP__

	[endsect]

	[section A note about optional<bool>]

	`optional<bool>` should be used with special caution and consideration.

	First, it is functionally similar to a tristate boolean (false,maybe,true)
	—such as __BOOST_TRIBOOL__— except that in a tristate boolean, the maybe state
	[_represents a valid value], unlike the corresponding state of an uninitialized
	`optional<bool>`.
	It should be carefully considered if an `optional<bool>` instead of a `tribool`
	is really needed.

	Second, `optional<>` provides an implicit conversion to `bool`. This
	conversion refers to the initialization state and not to the contained value.
	Using `optional<bool>` can lead to subtle errors due to the implicit `bool`
	conversion:

	void foo ( bool v ) ;
	void bar()
	{
	optional<bool> v = try();

	// The following intended to pass the value of 'v' to foo():
	foo(v);
	// But instead, the initialization state is passed
	// due to a typo: it should have been foo(*v).
	}

	The only implicit conversion is to `bool`, and it is safe in the sense that
	typical integral promotions don't apply (i.e. if `foo()` takes an `int`
	instead, it won't compile).

	[endsect]

	[section Exception Safety Guarantees]

	Because of the current implementation (see [link boost_optional.implementation_notes Implementation Notes]), all of the assignment methods:

	* `optional<T>::operator= ( optional<T> const& )`
	* `optional<T>::operator= ( T const& )`
	* `template<class U> optional<T>::operator= ( optional<U> const& )`
	* `template<class InPlaceFactory> optional<T>::operator= ( InPlaceFactory const& )`
	* `template<class TypedInPlaceFactory> optional<T>::operator= ( TypedInPlaceFactory const& ) `
	* `optional<T>:::reset ( T const&)`

	Can only ['guarantee] the [_basic exception safety]: The lvalue optional is
	left [_uninitialized] if an exception is thrown (any previous value is ['first]
	destroyed using `T::~T()`)

	On the other hand, the ['uninitializing] methods:

	* `optional<T>::operator= ( detail::none_t )`
	* `optional<T>::reset()`

	Provide the no-throw guarantee (assuming a no-throw `T::~T()`)

	However, since `optional<>` itself doesn't throw any exceptions, the only
	source for exceptions here are `T`'s constructor, so if you know the exception
	guarantees for `T::T ( T const& )`, you know that `optional`'s assignment and
	reset has the same guarantees.

	//
	// Case 1: Exception thrown during assignment.
	//
	T v0(123);
	optional<T> opt0(v0);
	try
	{
	T v1(456);
	optional<T> opt1(v1);
	opt0 = opt1 ;

	// If no exception was thrown, assignment succeeded.
	assert( *opt0 == v1 ) ;
	}
	catch(...)
	{
	// If any exception was thrown, 'opt0' is reset to uninitialized.
	assert( !opt0 ) ;
	}

	//
	// Case 2: Exception thrown during reset(v)
	//
	T v0(123);
	optional<T> opt(v0);
	try
	{
	T v1(456);
	opt.reset ( v1 ) ;

	// If no exception was thrown, reset succeeded.
	assert( *opt == v1 ) ;
	}
	catch(...)
	{
	// If any exception was thrown, 'opt' is reset to uninitialized.
	assert( !opt ) ;
	}

	[heading Swap]

	`void swap( optional<T>&, optional<T>& )` has the same exception guarantee
	as `swap(T&,T&)` when both optionals are initialized.
	If only one of the optionals is initialized, it gives the same ['basic]
	exception guarantee as `optional<T>::reset( T const& )` (since
	`optional<T>::reset()` doesn't throw).
	If none of the optionals is initialized, it has no-throw guarantee
	since it is a no-op.

	[endsect]

	[section Type requirements]

	In general, `T` must be __COPY_CONSTRUCTIBLE__ and have a no-throw destructor.
	The copy-constructible requirement is not needed if [*InPlaceFactories] are used.

	`T` [_is not] required to be __SGI_DEFAULT_CONSTRUCTIBLE__.

	[endsect]