libs/optional/doc/reference.qbk

   1 [/
   2     Boost.Optional
   3
   4     Copyright (c) 2003-2007 Fernando Luis Cacciola Carballal
   5
   6     Distributed under the Boost Software License, Version 1.0.
   7     (See accompanying file LICENSE_1_0.txt or copy at
   8     http://www.boost.org/LICENSE_1_0.txt)
   9 ]
  10
  11
  12 [section Synopsis]
  13
  14     namespace boost {
  15
  16     template<class T>
  17     class optional
  18     {
  19         public :
  20
  21         // (If T is of reference type, the parameters and results by reference are by value)
  22
  23         optional () ; ``[link reference_optional_constructor __GO_TO__]``
  24
  25         optional ( none_t ) ; ``[link reference_optional_constructor_none_t __GO_TO__]``
  26
  27         optional ( T const& v ) ; ``[link reference_optional_constructor_value __GO_TO__]``
  28
  29         // [new in 1.34]
  30         optional ( bool condition, T const& v ) ; ``[link reference_optional_constructor_bool_value __GO_TO__]``
  31
  32         optional ( optional const& rhs ) ; ``[link reference_optional_constructor_optional __GO_TO__]``
  33
  34         template<class U> explicit optional ( optional<U> const& rhs ) ; ``[link reference_optional_constructor_other_optional __GO_TO__]``
  35
  36         template<class InPlaceFactory> explicit optional ( InPlaceFactory const& f ) ; ``[link reference_optional_constructor_factory __GO_TO__]``
  37
  38         template<class TypedInPlaceFactory> explicit optional ( TypedInPlaceFactory const& f ) ; ``[link reference_optional_constructor_factory __GO_TO__]``
  39
  40         optional& operator = ( none_t ) ; ``[/[link reference_optional_operator_equal_none_t __GO_TO__]]``
  41
  42         optional& operator = ( T const& v ) ; ``[link reference_optional_operator_equal_value __GO_TO__]``
  43
  44         optional& operator = ( optional const& rhs ) ; ``[link reference_optional_operator_equal_optional __GO_TO__]``
  45
  46         template<class U> optional& operator = ( optional<U> const& rhs ) ; ``[link reference_optional_operator_equal_other_optional __GO_TO__]``
  47
  48         template<class InPlaceFactory> optional& operator = ( InPlaceFactory const& f ) ; ``[/[link reference_optional_operator_equal_factory __GO_TO__]]``
  49
  50         template<class TypedInPlaceFactory> optional& operator = ( TypedInPlaceFactory const& f ) ; ``[/[link reference_optional_operator_equal_factory __GO_TO__]]``
  51
  52         T const& get() const ; ``[link reference_optional_get __GO_TO__]``
  53         T&       get() ; ``[link reference_optional_get __GO_TO__]``
  54
  55         // [new in 1.34]
  56         T const& get_value_or( T const& default ) const ; ``[link reference_optional_get_value_or_value __GO_TO__]``
  57
  58         T const* operator ->() const ; ``[link reference_optional_operator_arrow __GO_TO__]``
  59         T*       operator ->() ; ``[link reference_optional_operator_arrow __GO_TO__]``
  60
  61         T const& operator *() const ; ``[link reference_optional_get __GO_TO__]``
  62         T&       operator *() ; ``[link reference_optional_get __GO_TO__]``
  63
  64         T const* get_ptr() const ; ``[link reference_optional_get_ptr __GO_TO__]``
  65         T*       get_ptr() ; ``[link reference_optional_get_ptr __GO_TO__]``
  66
  67         operator unspecified-bool-type() const ; ``[link reference_optional_operator_bool __GO_TO__]``
  68
  69         bool operator!() const ; ``[link reference_optional_operator_not __GO_TO__]``
  70
  71         // deprecated methods
  72
  73         // (deprecated)
  74         void reset() ; ``[link reference_optional_reset __GO_TO__]``
  75
  76         // (deprecated)
  77         void reset ( T const& ) ; ``[link reference_optional_reset_value __GO_TO__]``
  78
  79         // (deprecated)
  80         bool is_initialized() const ; ``[link reference_optional_is_initialized __GO_TO__]``
  81
  82     };
  83
  84     template<class T> inline bool operator == ( optional<T> const& x, optional<T> const& y ) ; ``[link reference_operator_compare_equal_optional_optional __GO_TO__]``
  85
  86     template<class T> inline bool operator != ( optional<T> const& x, optional<T> const& y ) ; ``[link reference_operator_compare_not_equal_optional_optional __GO_TO__]``
  87
  88     template<class T> inline bool operator <  ( optional<T> const& x, optional<T> const& y ) ; ``[link reference_operator_compare_less_optional_optional __GO_TO__]``
  89
  90     template<class T> inline bool operator >  ( optional<T> const& x, optional<T> const& y ) ; ``[link reference_operator_compare_greater_optional_optional __GO_TO__]``
  91
  92     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__]``
  93
  94     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__]``
  95
  96     // [new in 1.34]
  97     template<class T> inline optional<T> make_optional ( T const& v ) ; ``[link reference_make_optional_value __GO_TO__]``
  98
  99     // [new in 1.34]
 100     template<class T> inline optional<T> make_optional ( bool condition, T const& v ) ; ``[link reference_make_optional_bool_value __GO_TO__]``
 101
 102     // [new in 1.34]
 103     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__]``
 104
 105     template<class T> inline T const& get ( optional<T> const& opt ) ; ``[link reference_optional_get __GO_TO__]``
 106
 107     template<class T> inline T& get ( optional<T> & opt ) ; ``[link reference_optional_get __GO_TO__]``
 108
 109     template<class T> inline T const* get ( optional<T> const* opt ) ; ``[link reference_optional_get __GO_TO__]``
 110
 111     template<class T> inline T* get ( optional<T>* opt ) ; ``[link reference_optional_get __GO_TO__]``
 112
 113     template<class T> inline T const* get_pointer ( optional<T> const& opt ) ; ``[link reference_optional_get_ptr __GO_TO__]``
 114
 115     template<class T> inline T* get_pointer ( optional<T> & opt ) ; ``[link reference_optional_get_ptr __GO_TO__]``
 116
 117     template<class T> inline void swap( optional<T>& x, optional<T>& y ) ; ``[link reference_swap_optional_optional __GO_TO__]``
 118
 119     } // namespace boost
 120
 121
 122 [endsect]
 123
 124 [section Detailed Semantics]
 125
 126 Because `T` might be of reference type, in the sequel, those entries whose
 127 semantic depends on `T` being of reference type or not will be distinguished
 128 using the following convention:
 129
 130 * If the entry reads: `optional<T`['(not a ref)]`>`, the description
 131 corresponds only to the case where `T` is not of reference type.
 132 * If the entry reads: `optional<T&>`, the description corresponds only to
 133 the case where `T` is of reference type.
 134 * If the entry reads: `optional<T>`, the description is the same for both
 135 cases.
 136
 137 [note
 138 The following section contains various `assert()` which are used only to show
 139 the postconditions as sample code. It is not implied that the type `T` must
 140 support each particular expression but that if the expression is supported,
 141 the implied condition holds.
 142 ]
 143
 144 __SPACE__
 145
 146 [heading optional class member functions]
 147
 148 __SPACE__
 149
 150 [#reference_optional_constructor]
 151
 152 [: `optional<T>::optional();`]
 153
 154 * [*Effect:] Default-Constructs an `optional`.
 155 * [*Postconditions:] `*this` is [_uninitialized].
 156 * [*Throws:] Nothing.
 157 * Notes: T's default constructor [_is not] called.
 158 * [*Example:]
 159 ``
 160 optional<T> def ;
 161 assert ( !def ) ;
 162 ``
 163
 164 __SPACE__
 165
 166 [#reference_optional_constructor_none_t]
 167
 168 [: `optional<T>::optional( none_t );`]
 169
 170 * [*Effect:] Constructs an `optional` uninitialized.
 171 * [*Postconditions:] `*this` is [_uninitialized].
 172 * [*Throws:] Nothing.
 173 * [*Notes:] `T`'s default constructor [_is not] called. The expression
 174 `boost::none` denotes an instance of `boost::none_t` that can be used as
 175 the parameter.
 176 * [*Example:]
 177 ``
 178 #include <boost/none.hpp>
 179 optional<T> n(none) ;
 180 assert ( !n ) ;
 181 ``
 182
 183 __SPACE__
 184
 185 [#reference_optional_constructor_value]
 186
 187 [: `optional<T `['(not a ref)]`>::optional( T const& v )`]
 188
 189 * [*Effect:] Directly-Constructs an `optional`.
 190 * [*Postconditions:] `*this` is [_initialized] and its value is a['copy]
 191 of `v`.
 192 * [*Throws:] Whatever `T::T( T const& )` throws.
 193 * [*Notes: ] `T::T( T const& )` is called.
 194 * [*Exception Safety:] Exceptions can only be thrown during
 195 `T::T( T const& );` in that case, this constructor has no effect.
 196 * [*Example:]
 197 ``
 198 T v;
 199 optional<T> opt(v);
 200 assert ( *opt == v ) ;
 201 ``
 202
 203 __SPACE__
 204
 205 [: `optional<T&>::optional( T& ref )`]
 206
 207 * [*Effect:] Directly-Constructs an `optional`.
 208 * [*Postconditions:] `*this` is [_initialized] and its value is an instance
 209 of an internal type wrapping the reference `ref`.
 210 * [*Throws:] Nothing.
 211 * [*Example:]
 212 ``
 213 T v;
 214 T& vref = v ;
 215 optional<T&> opt(vref);
 216 assert ( *opt == v ) ;
 217 ++ v ; // mutate referee
 218 assert (*opt == v);
 219 ``
 220
 221 __SPACE__
 222
 223 [#reference_optional_constructor_bool_value]
 224
 225 [: `optional<T` ['(not a ref)]`>::optional( bool condition, T const& v ) ;` ]
 226 [: `optional<T&>           ::optional( bool condition, T&       v ) ;` ]
 227
 228 * If condition is true, same as:
 229
 230 [: `optional<T` ['(not a ref)]`>::optional( T const& v )`]
 231 [: `optional<T&>           ::optional( T&       v )`]
 232
 233 * otherwise, same as:
 234
 235 [: `optional<T ['(not a ref)]>::optional()`]
 236 [: `optional<T&>           ::optional()`]
 237
 238 __SPACE__
 239
 240 [#reference_optional_constructor_optional]
 241
 242 [: `optional<T `['(not a ref)]`>::optional( optional const& rhs );`]
 243
 244 * [*Effect:] Copy-Constructs an `optional`.
 245 * [*Postconditions:] If rhs is initialized, `*this` is initialized and
 246 its value is a ['copy] of the value of `rhs`; else `*this` is uninitialized.
 247 * [*Throws:] Whatever `T::T( T const& )` throws.
 248 * [*Notes:] If rhs is initialized, `T::T(T const& )` is called.
 249 * [*Exception Safety:] Exceptions can only be thrown during
 250 `T::T( T const& );` in that case, this constructor has no effect.
 251 * [*Example:]
 252 ``
 253 optional<T> uninit ;
 254 assert (!uninit);
 255
 256 optional<T> uinit2 ( uninit ) ;
 257 assert ( uninit2 == uninit );
 258
 259 optional<T> init( T(2) );
 260 assert ( *init == T(2) ) ;
 261
 262 optional<T> init2 ( init ) ;
 263 assert ( init2 == init ) ;
 264 ``
 265
 266 __SPACE__
 267
 268 [: `optional<T&>::optional( optional const& rhs );`]
 269
 270 * [*Effect:] Copy-Constructs an `optional`.
 271 * [*Postconditions:] If `rhs` is initialized, `*this` is initialized and its
 272 value is another reference to the same object referenced by `*rhs`; else
 273 `*this` is uninitialized.
 274 * [*Throws:] Nothing.
 275 * [*Notes:] If `rhs` is initialized, both `*this` and `*rhs` will reefer to the
 276 same object (they alias).
 277 * [*Example:]
 278 ``
 279 optional<T&> uninit ;
 280 assert (!uninit);
 281
 282 optional<T&> uinit2 ( uninit ) ;
 283 assert ( uninit2 == uninit );
 284
 285 T v = 2 ; T& ref = v ;
 286 optional<T> init(ref);
 287 assert ( *init == v ) ;
 288
 289 optional<T> init2 ( init ) ;
 290 assert ( *init2 == v ) ;
 291
 292 v = 3 ;
 293
 294 assert ( *init  == 3 ) ;
 295 assert ( *init2 == 3 ) ;
 296 ``
 297
 298 __SPACE__
 299
 300 [#reference_optional_constructor_other_optional]
 301
 302 [: `template<U> explicit optional<T` ['(not a ref)]`>::optional( optional<U> const& rhs );`]
 303
 304 * [*Effect:] Copy-Constructs an `optional`.
 305 * [*Postconditions:] If `rhs` is initialized, `*this` is initialized and its
 306 value is a ['copy] of the value of rhs converted to type `T`; else `*this` is
 307 uninitialized.
 308 * [*Throws:] Whatever `T::T( U const& )` throws.
 309 * [*Notes: ] `T::T( U const& )` is called if `rhs` is initialized, which requires a
 310 valid conversion from `U` to `T`.
 311 * [*Exception Safety:] Exceptions can only be thrown during `T::T( U const& );`
 312 in that case, this constructor has no effect.
 313 * [*Example:]
 314 ``
 315 optional<double> x(123.4);
 316 assert ( *x == 123.4 ) ;
 317
 318 optional<int> y(x) ;
 319 assert( *y == 123 ) ;
 320 ``
 321
 322 __SPACE__
 323
 324 [#reference_optional_constructor_factory]
 325
 326 [: `template<InPlaceFactory> explicit optional<T` ['(not a ref)]`>::optional( InPlaceFactory const& f );`]
 327 [: `template<TypedInPlaceFactory> explicit optional<T` ['(not a ref)]`>::optional( TypedInPlaceFactory const& f );`]
 328
 329 * [*Effect:] Constructs an `optional` with a value of `T` obtained from the
 330 factory.
 331 * [*Postconditions: ] `*this` is [_initialized] and its value is ['directly given]
 332 from the factory `f` (i.e., the value [_is not copied]).
 333 * [*Throws:] Whatever the `T` constructor called by the factory throws.
 334 * [*Notes:] See [link boost_optional.in_place_factories In-Place Factories]
 335 * [*Exception Safety:] Exceptions can only be thrown during the call to
 336 the `T` constructor used by the factory; in that case, this constructor has
 337 no effect.
 338 * [*Example:]
 339 ``
 340 class C { C ( char, double, std::string ) ; } ;
 341
 342 C v('A',123.4,"hello");
 343
 344 optional<C> x( in_place   ('A', 123.4, "hello") ); // InPlaceFactory used
 345 optional<C> y( in_place<C>('A', 123.4, "hello") ); // TypedInPlaceFactory used
 346
 347 assert ( *x == v ) ;
 348 assert ( *y == v ) ;
 349 ``
 350
 351 __SPACE__
 352
 353 [#reference_optional_operator_equal_value]
 354
 355 [: `optional& optional<T` ['(not a ref)]`>::operator= ( T const& rhs ) ;`]
 356
 357 * [*Effect:] Assigns the value `rhs` to an `optional`.
 358 * [*Postconditions: ] `*this` is initialized and its value is a ['copy] of `rhs`.
 359 * [*Throws:] Whatever `T::operator=( T const& )` or `T::T(T const&)` throws.
 360 * [*Notes:] If `*this` was initialized, `T`'s assignment operator is used,
 361 otherwise, its copy-constructor is used.
 362 * [*Exception Safety:] In the event of an exception, the initialization
 363 state of `*this` is unchanged and its value unspecified as far as `optional`
 364 is concerned (it is up to `T`'s `operator=()`). If `*this` is initially
 365 uninitialized and `T`'s ['copy constructor] fails, `*this` is left properly
 366 uninitialized.
 367 * [*Example:]
 368 ``
 369 T x;
 370 optional<T> def ;
 371 optional<T> opt(x) ;
 372
 373 T y;
 374 def = y ;
 375 assert ( *def == y ) ;
 376 opt = y ;
 377 assert ( *opt == y ) ;
 378 ``
 379
 380 __SPACE__
 381
 382 [: `optional<T&>& optional<T&>::operator= ( T& const& rhs ) ;`]
 383
 384 * [*Effect:] (Re)binds thee wrapped reference.
 385 * [*Postconditions: ] `*this` is initialized and it references the same
 386 object referenced by `rhs`.
 387 * [*Notes:] If `*this` was initialized, is is ['rebound] to the new object.
 388 See [link boost_optional.rebinding_semantics_for_assignment_of_optional_references here] for details on this behavior.
 389 * [*Example:]
 390 ``
 391 int a = 1 ;
 392 int b = 2 ;
 393 T& ra = a ;
 394 T& rb = b ;
 395 optional<int&> def ;
 396 optional<int&> opt(ra) ;
 397
 398 def = rb ; // binds 'def' to 'b' through 'rb'
 399 assert ( *def == b ) ;
 400 *def = a ; // changes the value of 'b' to a copy of the value of 'a'
 401 assert ( b == a ) ;
 402 int c = 3;
 403 int& rc = c ;
 404 opt = rc ; // REBINDS to 'c' through 'rc'
 405 c = 4 ;
 406 assert ( *opt == 4 ) ;
 407 ``
 408
 409 __SPACE__
 410
 411 [#reference_optional_operator_equal_optional]
 412
 413 [: `optional& optional<T` ['(not a ref)]`>::operator= ( optional const& rhs ) ;`]
 414
 415 * [*Effect:] Assigns another `optional` to an `optional`.
 416 * [*Postconditions:] If `rhs` is initialized, `*this` is initialized and
 417 its value is a ['copy] of the value of `rhs`; else `*this` is uninitialized.
 418 * [*Throws:] Whatever `T::operator( T const&)` or  `T::T( T const& )` throws.
 419 * [*Notes:] If both `*this` and `rhs` are initially initialized, `T`'s
 420 ['assignment operator] is used. If `*this` is initially initialized but `rhs` is
 421 uninitialized, `T`'s [destructor] is called. If `*this` is initially uninitialized
 422 but `rhs` is initialized, `T`'s ['copy constructor] is called.
 423 * [*Exception Safety:] In the event of an exception, the initialization state of
 424 `*this` is unchanged and its value unspecified as far as optional is concerned
 425 (it is up to `T`'s `operator=()`). If `*this` is initially uninitialized and
 426 `T`'s ['copy constructor] fails, `*this` is left properly uninitialized.
 427 * [*Example:]
 428 ``
 429 T v;
 430 optional<T> opt(v);
 431 optional<T> def ;
 432
 433 opt = def ;
 434 assert ( !def ) ;
 435 // previous value (copy of 'v') destroyed from within 'opt'.
 436 ``
 437
 438 __SPACE__
 439
 440 [: `optional<T&> & optional<T&>::operator= ( optional<T&> const& rhs ) ;`]
 441
 442 * [*Effect:] (Re)binds thee wrapped reference.
 443 * [*Postconditions:] If `*rhs` is initialized, `*this` is initialized and it
 444 references the same object referenced by `*rhs`; otherwise, `*this` is
 445 uninitialized (and references no object).
 446 * [*Notes:] If `*this` was initialized and so is *rhs, this is is ['rebound] to
 447 the new object. See [link boost_optional.rebinding_semantics_for_assignment_of_optional_references here] for details on this behavior.
 448 * [*Example:]
 449 ``
 450 int a = 1 ;
 451 int b = 2 ;
 452 T& ra = a ;
 453 T& rb = b ;
 454 optional<int&> def ;
 455 optional<int&> ora(ra) ;
 456 optional<int&> orb(rb) ;
 457
 458 def = orb ; // binds 'def' to 'b' through 'rb' wrapped within 'orb'
 459 assert ( *def == b ) ;
 460 *def = ora ; // changes the value of 'b' to a copy of the value of 'a'
 461 assert ( b == a ) ;
 462 int c = 3;
 463 int& rc = c ;
 464 optional<int&> orc(rc) ;
 465 ora = orc ; // REBINDS ora to 'c' through 'rc'
 466 c = 4 ;
 467 assert ( *ora == 4 ) ;
 468 ``
 469
 470 __SPACE__
 471
 472 [#reference_optional_operator_equal_other_optional]
 473
 474 [: `template<U> optional& optional<T` ['(not a ref)]`>::operator= ( optional<U> const& rhs ) ;`]
 475
 476 * [*Effect:] Assigns another convertible optional to an optional.
 477 * [*Postconditions:] If `rhs` is initialized, `*this` is initialized and
 478 its value is a ['copy] of the value of `rhs` ['converted] to type `T`; else
 479 `*this` is uninitialized.
 480 * [*Throws:] Whatever `T::operator=( U const& )` or `T::T( U const& )` throws.
 481 * [*Notes:] If both `*this` and rhs are initially initialized, `T`'s
 482 ['assignment operator] (from `U`) is used. If `*this` is initially initialized
 483 but `rhs` is uninitialized, `T`'s ['destructor] is called. If `*this` is
 484 initially uninitialized but rhs is initialized, `T`'s ['converting constructor]
 485 (from `U`) is called.
 486 * [*Exception Safety:] In the event of an exception, the initialization state
 487 of `*this` is unchanged and its value unspecified as far as optional is
 488 concerned (it is up to `T`'s `operator=()`). If `*this` is initially
 489 uninitialized and `T`'s converting constructor fails, `*this` is left properly
 490 uninitialized.
 491 * [*Example:]
 492 ``
 493 T v;
 494 optional<T> opt0(v);
 495 optional<U> opt1;
 496
 497 opt1 = opt0 ;
 498 assert ( *opt1 == static_cast<U>(v) ) ;
 499 ``
 500
 501 __SPACE__
 502
 503 [#reference_optional_reset_value]
 504
 505 [: `void optional<T` ['(not a ref)]`>::reset( T const& v ) ;`]
 506 * [*Deprecated:] same as `operator= ( T const& v) ;`
 507
 508 __SPACE__
 509
 510 [#reference_optional_reset]
 511
 512 [: `void optional<T>::reset() ;`]
 513 * [*Deprecated:] Same as `operator=( detail::none_t );`
 514
 515 __SPACE__
 516
 517 [#reference_optional_get]
 518
 519 [: `T const& optional<T` ['(not a ref)]`>::operator*() const ;`]
 520 [: `T&       optional<T` ['(not a ref)]`>::operator*();`]
 521 [: `T const& optional<T` ['(not a ref)]`>::get() const ;`]
 522 [: `T&       optional<T` ['(not a ref)]`>::get() ;`]
 523
 524 [: `inline T const& get ( optional<T` ['(not a ref)]`> const& ) ;`]
 525 [: `inline T&       get ( optional<T` ['(not a ref)]`> &) ;`]
 526
 527 * [*Requirements:] `*this` is initialized
 528 * [*Returns:] A reference to the contained value
 529 * [*Throws:] Nothing.
 530 * [*Notes:] The requirement is asserted via `BOOST_ASSERT()`.
 531 * [*Example:]
 532 ``
 533 T v ;
 534 optional<T> opt ( v );
 535 T const& u = *opt;
 536 assert ( u == v ) ;
 537 T w ;
 538 *opt = w ;
 539 assert ( *opt == w ) ;
 540 ``
 541
 542 __SPACE__
 543
 544 [#reference_optional_get_value_or_value]
 545
 546 [: `T const& optional<T` ['(not a ref)]`>::get_value_or( T const& default) const ;`]
 547 [: `T&       optional<T` ['(not a ref)]`>::get_value_or( T&       default ) ;`]
 548
 549 [: `inline T const& get_optional_value_or ( optional<T` ['(not a ref)]`> const& o, T const& default ) ;`]
 550 [: `inline T&       get_optional_value_or ( optional<T` ['(not a ref)]`>&       o, T&       default ) ;`]
 551
 552 * [*Returns:] A reference to the contained value, if any, or `default`.
 553 * [*Throws:] Nothing.
 554 * [*Example:]
 555 ``
 556 T v, z ;
 557 optional<T> def;
 558 T const& y = def.get_value_or(z);
 559 assert ( y == z ) ;
 560
 561 optional<T> opt ( v );
 562 T const& u = get_optional_value_or(opt,z);
 563 assert ( u == v ) ;
 564 assert ( u != z ) ;
 565 ``
 566
 567 __SPACE__
 568
 569 [: `T const& optional<T&>::operator*() const ;`]
 570 [: `T      & optional<T&>::operator*();`]
 571 [: `T const& optional<T&>::get() const ;`]
 572 [: `T&       optional<T&>::get() ;`]
 573
 574 [: `inline T const& get ( optional<T&> const& ) ;`]
 575 [: `inline T&       get ( optional<T&> &) ;`]
 576
 577 * [*Requirements: ] `*this` is initialized
 578 * [*Returns:] [_The] reference contained.
 579 * [*Throws:] Nothing.
 580 * [*Notes:] The requirement is asserted via `BOOST_ASSERT()`.
 581 * [*Example:]
 582 ``
 583 T v ;
 584 T& vref = v ;
 585 optional<T&> opt ( vref );
 586 T const& vref2 = *opt;
 587 assert ( vref2 == v ) ;
 588 ++ v ;
 589 assert ( *opt == v ) ;
 590 ``
 591
 592 __SPACE__
 593
 594 [#reference_optional_get_ptr]
 595
 596 [: `T const* optional<T` ['(not a ref)]`>::get_ptr() const ;`]
 597 [: `T*       optional<T` ['(not a ref)]`>::get_ptr() ;`]
 598
 599 [: `inline T const* get_pointer ( optional<T` ['(not a ref)]`> const& ) ;`]
 600 [: `inline T*       get_pointer ( optional<T` ['(not a ref)]`> &) ;`]
 601
 602 * [*Returns:] If `*this` is initialized, a pointer to the contained value;
 603 else `0` (['null]).
 604 * [*Throws:] Nothing.
 605 * [*Notes:] The contained value is permanently stored within `*this`, so you
 606 should not hold nor delete this pointer
 607 * [*Example:]
 608 ``
 609 T v;
 610 optional<T> opt(v);
 611 optional<T> const copt(v);
 612 T* p = opt.get_ptr() ;
 613 T const* cp = copt.get_ptr();
 614 assert ( p == get_pointer(opt) );
 615 assert ( cp == get_pointer(copt) ) ;
 616 ``
 617
 618 __SPACE__
 619
 620 [#reference_optional_operator_arrow]
 621
 622 [: `T const* optional<T` ['(not a ref)]`>::operator ->() const ;`]
 623 [: `T*       optional<T` ['(not a ref)]`>::operator ->()       ;`]
 624
 625 * [*Requirements: ] `*this` is initialized.
 626 * [*Returns:] A pointer to the contained value.
 627 * [*Throws:] Nothing.
 628 * [*Notes:] The requirement is asserted via `BOOST_ASSERT()`.
 629 * [*Example:]
 630 ``
 631 struct X { int mdata ; } ;
 632 X x ;
 633 optional<X> opt (x);
 634 opt->mdata = 2 ;
 635 ``
 636
 637 __SPACE__
 638
 639 [#reference_optional_operator_bool]
 640
 641 [: `optional<T>::operator `['unspecified-bool-type]`() const ;`]
 642
 643 * [*Returns:] An unspecified value which if used on a boolean context
 644 is equivalent to (`get() != 0`)
 645 * [*Throws:] Nothing.
 646 * [*Example:]
 647 ``
 648 optional<T> def ;
 649 assert ( def == 0 );
 650 optional<T> opt ( v ) ;
 651 assert ( opt );
 652 assert ( opt != 0 );
 653 ``
 654
 655 __SPACE__
 656
 657 [#reference_optional_operator_not]
 658
 659 [: `bool optional<T>::operator!() ;`]
 660
 661 * [*Returns:] If `*this` is uninitialized, `true`; else `false`.
 662 * [*Throws:] Nothing.
 663 * [*Notes:] This operator is provided for those compilers which can't
 664 use the ['unspecified-bool-type operator] in certain boolean contexts.
 665 * [*Example:]
 666 ``
 667 optional<T> opt ;
 668 assert ( !opt );
 669 *opt = some_T ;
 670
 671 // Notice the "double-bang" idiom here.
 672 assert ( !!opt ) ;
 673 ``
 674
 675 __SPACE__
 676
 677 [#reference_optional_is_initialized]
 678
 679 [: `bool optional<T>::is_initialized() const ;`]
 680
 681 * [*Returns: ] `true` if the `optional` is initialized, `false` otherwise.
 682 * [*Throws:] Nothing.
 683 * [*Example:]
 684 ``
 685 optional<T> def ;
 686 assert ( !def.is_initialized() );
 687 optional<T> opt ( v ) ;
 688 assert ( opt.is_initialized() );
 689 ``
 690
 691 __SPACE__
 692
 693 [heading Free functions]
 694
 695 __SPACE__
 696
 697 [#reference_make_optional_value]
 698
 699 [: `optional<T` ['(not a ref)]`> make_optional( T const& v )`]
 700
 701 * [*Returns: ] `optional<T>(v)` for the ['deduced] type `T` of `v`.
 702 * [*Example:]
 703 ``
 704 template<class T> void foo ( optional<T> const& opt ) ;
 705
 706 foo ( make_optional(1+1) ) ; // Creates an optional<int>
 707 ``
 708
 709 __SPACE__
 710
 711 [#reference_make_optional_bool_value]
 712
 713 [: `optional<T` ['(not a ref)]`> make_optional( bool condition, T const& v )`]
 714
 715 * [*Returns: ] `optional<T>(condition,v)` for the ['deduced] type `T` of `v`.
 716 * [*Example:]
 717 ``
 718 optional<double> calculate_foo()
 719 {
 720   double val = compute_foo();
 721   return make_optional(is_not_nan_and_finite(val),val);
 722 }
 723
 724 optional<double> v = calculate_foo();
 725 if ( !v )
 726   error("foo wasn't computed");
 727 ``
 728
 729 __SPACE__
 730
 731 [#reference_operator_compare_equal_optional_optional]
 732
 733 [: `bool operator == ( optional<T> const& x, optional<T> const& y );`]
 734
 735 * [*Returns:] If both `x` and `y` are initialized, `(*x == *y)`. If only
 736 `x` or `y` is initialized, `false`. If both are uninitialized, `true`.
 737 * [*Throws:] Nothing.
 738 * [*Notes:] Pointers have shallow relational operators while `optional` has
 739 deep relational operators. Do not use `operator ==` directly in generic
 740 code which expect to be given either an `optional<T>` or a pointer; use
 741 __FUNCTION_EQUAL_POINTEES__ instead
 742 * [*Example:]
 743 ``
 744 T x(12);
 745 T y(12);
 746 T z(21);
 747 optional<T> def0 ;
 748 optional<T> def1 ;
 749 optional<T> optX(x);
 750 optional<T> optY(y);
 751 optional<T> optZ(z);
 752
 753 // Identity always hold
 754 assert ( def0 == def0 );
 755 assert ( optX == optX );
 756
 757 // Both uninitialized compare equal
 758 assert ( def0 == def1 );
 759
 760 // Only one initialized compare unequal.
 761 assert ( def0 != optX );
 762
 763 // Both initialized compare as (*lhs == *rhs)
 764 assert ( optX == optY ) ;
 765 assert ( optX != optZ ) ;
 766 ``
 767
 768 __SPACE__
 769
 770 [#reference_operator_compare_less_optional_optional]
 771
 772 [: `bool operator < ( optional<T> const& x, optional<T> const& y );`]
 773
 774 * [*Returns:] If `y` is not initialized, `false`. If `y` is initialized
 775 and `x` is not initialized, `true`. If both `x` and `y` are initialized,
 776 `(*x < *y)`.
 777 * [*Throws:] Nothing.
 778 * [*Notes:] Pointers have shallow relational operators while `optional` has
 779 deep relational operators. Do not use `operator <` directly in generic code
 780 which expect to be given either an `optional<T>` or a pointer; use __FUNCTION_LESS_POINTEES__ instead.
 781 * [*Example:]
 782 ``
 783 T x(12);
 784 T y(34);
 785 optional<T> def ;
 786 optional<T> optX(x);
 787 optional<T> optY(y);
 788
 789 // Identity always hold
 790 assert ( !(def < def) );
 791 assert ( optX == optX );
 792
 793 // Both uninitialized compare equal
 794 assert ( def0 == def1 );
 795
 796 // Only one initialized compare unequal.
 797 assert ( def0 != optX );
 798
 799 // Both initialized compare as (*lhs == *rhs)
 800 assert ( optX == optY ) ;
 801 assert ( optX != optZ ) ;
 802 ``
 803
 804 __SPACE__
 805
 806 [#reference_operator_compare_not_equal_optional_optional]
 807
 808 [: `bool operator != ( optional<T> const& x, optional<T> const& y );`]
 809
 810 * [*Returns: ] `!( x == y );`
 811 * [*Throws:] Nothing.
 812
 813 __SPACE__
 814
 815 [#reference_operator_compare_greater_optional_optional]
 816
 817 [: `bool operator > ( optional<T> const& x, optional<T> const& y );`]
 818
 819 * [*Returns: ] `( y < x );`
 820 * [*Throws:] Nothing.
 821
 822 __SPACE__
 823
 824 [#reference_operator_compare_less_or_equal_optional_optional]
 825
 826 [: `bool operator <= ( optional<T> const& x, optional<T> const& y );`]
 827
 828 * [*Returns: ] `!( y<x );`
 829 * [*Throws:] Nothing.
 830
 831 __SPACE__
 832
 833 [#reference_operator_compare_greater_or_equal_optional_optional]
 834
 835 [: `bool operator >= ( optional<T> const& x, optional<T> const& y );`]
 836
 837 * [*Returns: ] `!( x<y );`
 838 * [*Throws:] Nothing.
 839
 840 __SPACE__
 841
 842 [#reference_swap_optional_optional]
 843
 844 [: `void swap ( optional<T>& x, optional<T>& y );`]
 845
 846 * [*Effect:] If both `x` and `y` are initialized, calls `swap(*x,*y)`
 847 using `std::swap`. If only one is initialized, say `x`, calls:
 848 `y.reset(*x); x.reset();` If none is initialized, does nothing.
 849 * [*Postconditions:] The states of `x` and `y` interchanged.
 850 * [*Throws:] If both are initialized, whatever `swap(T&,T&)` throws. If only
 851 one is initialized, whatever `T::T ( T const& )` throws.
 852 * [*Notes:] If both are initialized, `swap(T&,T&)` is used unqualified but
 853 with `std::swap` introduced in scope.
 854 If only one is initialized, `T::~T()` and `T::T( T const& )` is called.
 855 * [*Exception Safety:] If both are initialized, this operation has the
 856 exception safety guarantees of `swap(T&,T&)`.
 857 If only one is initialized, it has the same basic guarantee as
 858 `optional<T>::reset( T const& )`.
 859 * [*Example:]
 860 ``
 861 T x(12);
 862 T y(21);
 863 optional<T> def0 ;
 864 optional<T> def1 ;
 865 optional<T> optX(x);
 866 optional<T> optY(y);
 867
 868 boost::swap(def0,def1); // no-op
 869
 870 boost::swap(def0,optX);
 871 assert ( *def0 == x );
 872 assert ( !optX );
 873
 874 boost::swap(def0,optX); // Get back to original values
 875
 876 boost::swap(optX,optY);
 877 assert ( *optX == y );
 878 assert ( *optY == x );
 879 ``
 880
 881 [endsect]