]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 Detailed Semantics - Optional Values] | |
13 | ||
14 | [note | |
15 | The following section contains various `assert()` which are used only to show | |
16 | the postconditions as sample code. It is not implied that the type `T` must | |
17 | support each particular expression but that if the expression is supported, | |
18 | the implied condition holds. | |
19 | ] | |
20 | ||
21 | ||
22 | __SPACE__ | |
23 | ||
24 | [#reference_optional_constructor] | |
25 | ||
26 | [: `optional<T>::optional() noexcept;`] | |
27 | ||
28 | * [*Effect:] Default-Constructs an `optional`. | |
29 | * [*Postconditions:] `*this` is [_uninitialized]. | |
30 | * [*Notes:] T's default constructor [_is not] called. | |
31 | * [*Example:] | |
32 | `` | |
33 | optional<T> def ; | |
34 | assert ( !def ) ; | |
35 | `` | |
36 | ||
37 | __SPACE__ | |
38 | ||
39 | [#reference_optional_constructor_none_t] | |
40 | ||
41 | [: `optional<T>::optional( none_t ) noexcept;`] | |
42 | ||
43 | * [*Effect:] Constructs an `optional` uninitialized. | |
44 | * [*Postconditions:] `*this` is [_uninitialized]. | |
45 | * [*Notes:] `T`'s default constructor [_is not] called. The expression | |
46 | `boost::none` denotes an instance of `boost::none_t` that can be used as | |
47 | the parameter. | |
48 | * [*Example:] | |
49 | `` | |
50 | #include <boost/none.hpp> | |
51 | optional<T> n(none) ; | |
52 | assert ( !n ) ; | |
53 | `` | |
54 | ||
55 | __SPACE__ | |
56 | ||
57 | [#reference_optional_constructor_value] | |
58 | ||
59 | [: `optional<T>::optional( T const& v )`] | |
60 | ||
61 | * [*Requires:] `is_copy_constructible<T>::value` is `true`. | |
62 | * [*Effect:] Directly-Constructs an `optional`. | |
63 | * [*Postconditions:] `*this` is [_initialized] and its value is a ['copy] | |
64 | of `v`. | |
65 | * [*Throws:] Whatever `T::T( T const& )` throws. | |
66 | * [*Notes: ] `T::T( T const& )` is called. | |
67 | * [*Exception Safety:] Exceptions can only be thrown during | |
68 | `T::T( T const& );` in that case, this constructor has no effect. | |
69 | * [*Example:] | |
70 | `` | |
71 | T v; | |
72 | optional<T> opt(v); | |
73 | assert ( *opt == v ) ; | |
74 | `` | |
75 | ||
76 | ||
77 | __SPACE__ | |
78 | ||
79 | [#reference_optional_constructor_move_value] | |
80 | ||
81 | [: `optional<T>::optional( T&& v )`] | |
82 | ||
83 | * [*Requires:] `is_move_constructible<T>::value` is `true`. | |
84 | * [*Effect:] Directly-Move-Constructs an `optional`. | |
85 | * [*Postconditions:] `*this` is [_initialized] and its value is move-constructed from `v`. | |
86 | * [*Throws:] Whatever `T::T( T&& )` throws. | |
87 | * [*Notes: ] `T::T( T&& )` is called. | |
88 | * [*Exception Safety:] Exceptions can only be thrown during | |
89 | `T::T( T&& );` in that case, the state of `v` is determined by exception safety guarantees for `T::T(T&&)`. | |
90 | * [*Example:] | |
91 | `` | |
92 | T v1, v2; | |
93 | optional<T> opt(std::move(v1)); | |
94 | assert ( *opt == v2 ) ; | |
95 | `` | |
96 | ||
97 | ||
98 | __SPACE__ | |
99 | ||
100 | [#reference_optional_constructor_bool_value] | |
101 | ||
102 | [: `optional<T>::optional( bool condition, T const& v ) ;` ] | |
103 | ||
104 | * If condition is true, same as: | |
105 | ||
106 | [: `optional<T>::optional( T const& v )`] | |
107 | ||
108 | * otherwise, same as: | |
109 | ||
110 | [: `optional<T>::optional()`] | |
111 | ||
112 | ||
113 | __SPACE__ | |
114 | ||
115 | [#reference_optional_constructor_optional] | |
116 | ||
117 | [: `optional<T>::optional( optional const& rhs );`] | |
118 | ||
119 | * [*Requires:] `is_copy_constructible<T>::value` is `true`. | |
120 | * [*Effect:] Copy-Constructs an `optional`. | |
121 | * [*Postconditions:] If rhs is initialized, `*this` is initialized and | |
122 | its value is a ['copy] of the value of `rhs`; else `*this` is uninitialized. | |
123 | * [*Throws:] Whatever `T::T( T const& )` throws. | |
124 | * [*Notes:] If rhs is initialized, `T::T(T const& )` is called. | |
125 | * [*Exception Safety:] Exceptions can only be thrown during | |
126 | `T::T( T const& );` in that case, this constructor has no effect. | |
127 | * [*Example:] | |
128 | `` | |
129 | optional<T> uninit ; | |
130 | assert (!uninit); | |
131 | ||
132 | optional<T> uinit2 ( uninit ) ; | |
133 | assert ( uninit2 == uninit ); | |
134 | ||
135 | optional<T> init( T(2) ); | |
136 | assert ( *init == T(2) ) ; | |
137 | ||
138 | optional<T> init2 ( init ) ; | |
139 | assert ( init2 == init ) ; | |
140 | `` | |
141 | ||
142 | ||
143 | __SPACE__ | |
144 | ||
145 | [#reference_optional_move_constructor_optional] | |
146 | ||
147 | [: `optional<T>::optional( optional&& rhs ) noexcept(`['see below]`);`] | |
148 | ||
149 | * [*Requires:] `is_move_constructible<T>::value` is `true`. | |
150 | * [*Effect:] Move-constructs an `optional`. | |
151 | * [*Postconditions:] If `rhs` is initialized, `*this` is initialized and | |
152 | its value is move constructed from `rhs`; else `*this` is uninitialized. | |
153 | * [*Throws:] Whatever `T::T( T&& )` throws. | |
154 | * [*Remarks:] The expression inside `noexcept` is equivalent to `is_nothrow_move_constructible<T>::value`. | |
155 | * [*Notes:] If `rhs` is initialized, `T::T( T && )` is called. | |
156 | * [*Exception Safety:] Exceptions can only be thrown during | |
157 | `T::T( T&& );` in that case, `rhs` remains initialized and the value of `*rhs` is determined by exception safety of `T::T(T&&)`. | |
158 | * [*Example:] | |
159 | `` | |
160 | optional<std::unique_ptr<T>> uninit ; | |
161 | assert (!uninit); | |
162 | ||
163 | optional<std::unique_ptr<T>> uinit2 ( std::move(uninit) ) ; | |
164 | assert ( uninit2 == uninit ); | |
165 | ||
166 | optional<std::unique_ptr<T>> init( std::uniqye_ptr<T>(new T(2)) ); | |
167 | assert ( **init == T(2) ) ; | |
168 | ||
169 | optional<std::unique_ptr<T>> init2 ( std::move(init) ) ; | |
170 | assert ( init ); | |
171 | assert ( *init == nullptr ); | |
172 | assert ( init2 ); | |
173 | assert ( **init2 == T(2) ) ; | |
174 | `` | |
175 | ||
176 | ||
177 | __SPACE__ | |
178 | ||
179 | [#reference_optional_constructor_other_optional] | |
180 | ||
181 | [: `template<U> explicit optional<T>::optional( optional<U> const& rhs );`] | |
182 | ||
183 | * [*Effect:] Copy-Constructs an `optional`. | |
184 | * [*Postconditions:] If `rhs` is initialized, `*this` is initialized and its | |
185 | value is a ['copy] of the value of rhs converted to type `T`; else `*this` is | |
186 | uninitialized. | |
187 | * [*Throws:] Whatever `T::T( U const& )` throws. | |
188 | * [*Notes: ] `T::T( U const& )` is called if `rhs` is initialized, which requires a | |
189 | valid conversion from `U` to `T`. | |
190 | * [*Exception Safety:] Exceptions can only be thrown during `T::T( U const& );` | |
191 | in that case, this constructor has no effect. | |
192 | * [*Example:] | |
193 | `` | |
194 | optional<double> x(123.4); | |
195 | assert ( *x == 123.4 ) ; | |
196 | ||
197 | optional<int> y(x) ; | |
198 | assert( *y == 123 ) ; | |
199 | `` | |
200 | ||
201 | __SPACE__ | |
202 | ||
203 | [#reference_optional_move_constructor_other_optional] | |
204 | ||
205 | [: `template<U> explicit optional<T>::optional( optional<U>&& rhs );`] | |
206 | ||
207 | * [*Effect:] Move-constructs an `optional`. | |
208 | * [*Postconditions:] If `rhs` is initialized, `*this` is initialized and its | |
209 | value is move-constructed from `*rhs`; else `*this` is | |
210 | uninitialized. | |
211 | * [*Throws:] Whatever `T::T( U&& )` throws. | |
212 | * [*Notes: ] `T::T( U&& )` is called if `rhs` is initialized, which requires a | |
213 | valid conversion from `U` to `T`. | |
214 | * [*Exception Safety:] Exceptions can only be thrown during `T::T( U&& );` | |
215 | in that case, `rhs` remains initialized and the value of `*rhs` is determined by exception safety guarantee of `T::T( U&& )`. | |
216 | * [*Example:] | |
217 | `` | |
218 | optional<double> x(123.4); | |
219 | assert ( *x == 123.4 ) ; | |
220 | ||
221 | optional<int> y(std::move(x)) ; | |
222 | assert( *y == 123 ) ; | |
223 | `` | |
224 | ||
225 | __SPACE__ | |
226 | ||
227 | [#reference_optional_in_place_init] | |
228 | ||
229 | [: `template<class... Args> explicit optional<T>::optional( in_place_init_t, Args&&... ars );`] | |
230 | ||
231 | * [*Requires:] `is_constructible_v<T, Args&&...>` is `true`. | |
232 | * [*Effect:] Initializes the contained value as if direct-non-list-initializing an object of type `T` with the | |
233 | arguments `std::forward<Args>(args)...`. | |
234 | * [*Postconditions:] `*this` is initialized. | |
235 | * [*Throws:] Any exception thrown by the selected constructor of `T`. | |
236 | * [*Notes: ] `T` need not be __MOVE_CONSTRUCTIBLE__. On compilers that do not suppor variadic templates or rvalue references, this constuctor is available in limited functionality. For details [link optional_emplace_workaround see here]. | |
237 | ||
238 | * [*Example:] | |
239 | `` | |
240 | // creates an std::mutex using its default constructor | |
241 | optional<std::mutex> om {in_place_init}; | |
242 | assert (om); | |
243 | ||
244 | // creates a unique_lock by calling unique_lock(*om, std::defer_lock) | |
245 | optional<std::unique_lock<std::mutex>> ol {in_place_init, *om, std::defer_lock}; | |
246 | assert (ol); | |
247 | assert (!ol->owns_lock()); | |
248 | `` | |
249 | ||
250 | __SPACE__ | |
251 | ||
252 | [#reference_optional_in_place_init_if] | |
253 | ||
254 | [: `template<class... Args> explicit optional<T>::optional( in_place_init_if_t, bool condition, Args&&... ars );`] | |
255 | ||
256 | * [*Requires:] `is_constructible_v<T, Args&&...>` is `true`. | |
257 | * [*Effect:] If `condition` is `true`, initializes the contained value as if direct-non-list-initializing an object of type `T` with the arguments `std::forward<Args>(args)...`. | |
258 | * [*Postconditions:] `bool(*this) == condition`. | |
259 | * [*Throws:] Any exception thrown by the selected constructor of `T`. | |
260 | * [*Notes: ] `T` need not be __MOVE_CONSTRUCTIBLE__. On compilers that do not suppor variadic templates or rvalue references, this constuctor is available in limited functionality. For details [link optional_emplace_workaround see here]. | |
261 | ||
262 | * [*Example:] | |
263 | `` | |
264 | optional<std::vector<std::string>> ov1 {in_place_init_if, false, 3, "A"}; | |
265 | assert (!ov1); | |
266 | ||
267 | optional<std::vector<std::string>> ov2 {in_place_init_if, true, 3, "A"}; | |
268 | assert (ov2); | |
269 | assert (ov2->size() == 3); | |
270 | `` | |
271 | ||
272 | __SPACE__ | |
273 | ||
274 | [#reference_optional_constructor_factory] | |
275 | ||
276 | [: `template<InPlaceFactory> explicit optional<T>::optional( InPlaceFactory const& f );`] | |
277 | [: `template<TypedInPlaceFactory> explicit optional<T>::optional( TypedInPlaceFactory const& f );`] | |
278 | ||
279 | * [*Effect:] Constructs an `optional` with a value of `T` obtained from the | |
280 | factory. | |
281 | * [*Postconditions: ] `*this` is [_initialized] and its value is ['directly given] | |
282 | from the factory `f` (i.e., the value [_is not copied]). | |
283 | * [*Throws:] Whatever the `T` constructor called by the factory throws. | |
284 | * [*Notes:] See [link boost_optional.tutorial.in_place_factories In-Place Factories] | |
285 | * [*Exception Safety:] Exceptions can only be thrown during the call to | |
286 | the `T` constructor used by the factory; in that case, this constructor has | |
287 | no effect. | |
288 | * [*Example:] | |
289 | `` | |
290 | class C { C ( char, double, std::string ) ; } ; | |
291 | ||
292 | C v('A',123.4,"hello"); | |
293 | ||
294 | optional<C> x( in_place ('A', 123.4, "hello") ); // InPlaceFactory used | |
295 | optional<C> y( in_place<C>('A', 123.4, "hello") ); // TypedInPlaceFactory used | |
296 | ||
297 | assert ( *x == v ) ; | |
298 | assert ( *y == v ) ; | |
299 | `` | |
300 | ||
301 | __SPACE__ | |
302 | ||
303 | [#reference_optional_operator_equal_none_t] | |
304 | ||
305 | [: `optional& optional<T>::operator= ( none_t ) noexcept;`] | |
306 | ||
307 | * [*Effect:] If `*this` is initialized destroys its contained value. | |
308 | * [*Postconditions: ] `*this` is uninitialized. | |
309 | ||
310 | __SPACE__ | |
311 | ||
312 | [#reference_optional_operator_equal_value] | |
313 | ||
314 | [: `optional& optional<T>::operator= ( T const& rhs ) ;`] | |
315 | ||
316 | * [*Effect:] Assigns the value `rhs` to an `optional`. | |
317 | * [*Postconditions: ] `*this` is initialized and its value is a ['copy] of `rhs`. | |
318 | * [*Throws:] Whatever `T::operator=( T const& )` or `T::T(T const&)` throws. | |
319 | * [*Notes:] If `*this` was initialized, `T`'s assignment operator is used, | |
320 | otherwise, its copy-constructor is used. | |
321 | * [*Exception Safety:] In the event of an exception, the initialization | |
322 | state of `*this` is unchanged and its value unspecified as far as `optional` | |
323 | is concerned (it is up to `T`'s `operator=()`). If `*this` is initially | |
324 | uninitialized and `T`'s ['copy constructor] fails, `*this` is left properly | |
325 | uninitialized. | |
326 | * [*Example:] | |
327 | `` | |
328 | T x; | |
329 | optional<T> def ; | |
330 | optional<T> opt(x) ; | |
331 | ||
332 | T y; | |
333 | def = y ; | |
334 | assert ( *def == y ) ; | |
335 | opt = y ; | |
336 | assert ( *opt == y ) ; | |
337 | `` | |
338 | ||
339 | ||
340 | __SPACE__ | |
341 | ||
342 | [#reference_optional_operator_move_equal_value] | |
343 | ||
344 | [: `optional& optional<T>::operator= ( T&& rhs ) ;`] | |
345 | ||
346 | * [*Effect:] Moves the value `rhs` to an `optional`. | |
347 | * [*Postconditions: ] `*this` is initialized and its value is moved from `rhs`. | |
348 | * [*Throws:] Whatever `T::operator=( T&& )` or `T::T(T &&)` throws. | |
349 | * [*Notes:] If `*this` was initialized, `T`'s move-assignment operator is used, | |
350 | otherwise, its move-constructor is used. | |
351 | * [*Exception Safety:] In the event of an exception, the initialization | |
352 | state of `*this` is unchanged and its value unspecified as far as `optional` | |
353 | is concerned (it is up to `T`'s `operator=()`). If `*this` is initially | |
354 | uninitialized and `T`'s ['move constructor] fails, `*this` is left properly | |
355 | uninitialized. | |
356 | * [*Example:] | |
357 | `` | |
358 | T x; | |
359 | optional<T> def ; | |
360 | optional<T> opt(x) ; | |
361 | ||
362 | T y1, y2, yR; | |
363 | def = std::move(y1) ; | |
364 | assert ( *def == yR ) ; | |
365 | opt = std::move(y2) ; | |
366 | assert ( *opt == yR ) ; | |
367 | `` | |
368 | ||
369 | ||
370 | __SPACE__ | |
371 | ||
372 | [#reference_optional_operator_equal_optional] | |
373 | ||
374 | [: `optional& optional<T>::operator= ( optional const& rhs ) ;`] | |
375 | ||
376 | * [*Requires:] `T` is __COPY_CONSTRUCTIBLE__ and `CopyAssignable`. | |
377 | * [*Effects:] | |
378 | [table | |
379 | [] | |
380 | [[][[*`*this` contains a value]][[*`*this` does not contain a value]]] | |
381 | [[[*`rhs` contains a value]][assigns `*rhs` to the contained value][initializes the contained value as if direct-initializing an object of type `T` with `*rhs`]] | |
382 | [[[*`rhs` does not contain a value]][destroys the contained value by calling `val->T::~T()`][no effect]] | |
383 | ] | |
384 | * [*Returns:] `*this`; | |
385 | * [*Postconditions:] `bool(rhs) == bool(*this)`. | |
386 | * [*Exception Safety:] If any exception is thrown, the initialization state of `*this` and `rhs` remains unchanged. | |
387 | If an exception is thrown during the call to `T`'s copy constructor, no effect. | |
388 | If an exception is thrown during the call to `T`'s copy assignment, the state of its contained value is as defined by the exception safety guarantee of `T`'s copy assignment. | |
389 | * [*Example:] | |
390 | `` | |
391 | T v; | |
392 | optional<T> opt(v); | |
393 | optional<T> def ; | |
394 | ||
395 | opt = def ; | |
396 | assert ( !def ) ; | |
397 | // previous value (copy of 'v') destroyed from within 'opt'. | |
398 | `` | |
399 | ||
400 | ||
401 | __SPACE__ | |
402 | ||
403 | [#reference_optional_operator_move_equal_optional] | |
404 | ||
405 | [: `optional& optional<T>::operator= ( optional&& rhs ) noexcept(`['see below]`);`] | |
406 | ||
407 | * [*Requires:] `T` is __MOVE_CONSTRUCTIBLE__ and `MoveAssignable`. | |
408 | * [*Effects:] | |
409 | [table | |
410 | [] | |
411 | [[][[*`*this` contains a value]][[*`*this` does not contain a value]]] | |
412 | [[[*`rhs` contains a value]][assigns `std::move(*rhs)` to the contained value][initializes the contained value as if direct-initializing an object of type `T` with `std::move(*rhs)`]] | |
413 | [[[*`rhs` does not contain a value]][destroys the contained value by calling `val->T::~T()`][no effect]] | |
414 | ] | |
415 | * [*Returns:] `*this`; | |
416 | * [*Postconditions:] `bool(rhs) == bool(*this)`. | |
417 | * [*Remarks:] The expression inside `noexcept` is equivalent to `is_nothrow_move_constructible<T>::value && is_nothrow_move_assignable<T>::value`. | |
418 | * [*Exception Safety:] If any exception is thrown, the initialization state of `*this` and `rhs` remains unchanged. If an exception is | |
419 | thrown during the call to `T`'s move constructor, the state of `*rhs` is determined by the exception safety guarantee | |
420 | of `T`'s move constructor. If an exception is thrown during the call to T's move-assignment, the state of `**this` and `*rhs` is determined by the exception safety guarantee of T's move assignment. | |
421 | * [*Example:] | |
422 | `` | |
423 | optional<T> opt(T(2)) ; | |
424 | optional<T> def ; | |
425 | ||
426 | opt = def ; | |
427 | assert ( def ) ; | |
428 | assert ( opt ) ; | |
429 | assert ( *opt == T(2) ) ; | |
430 | `` | |
431 | ||
432 | ||
433 | __SPACE__ | |
434 | ||
435 | ||
436 | [#reference_optional_operator_equal_other_optional] | |
437 | ||
438 | [: `template<U> optional& optional<T>::operator= ( optional<U> const& rhs ) ;`] | |
439 | ||
440 | * [*Effect:] | |
441 | [table | |
442 | [] | |
443 | [[][[*`*this` contains a value]][[*`*this` does not contain a value]]] | |
444 | [[[*`rhs` contains a value]][assigns `*rhs` to the contained value][initializes the contained value as if direct-initializing an object of type `T` with `*rhs`]] | |
445 | [[[*`rhs` does not contain a value]][destroys the contained value by calling `val->T::~T()`][no effect]] | |
446 | ] | |
447 | * [*Returns:] `*this`. | |
448 | * [*Postconditions:] `bool(rhs) == bool(*this)`. | |
449 | * [*Exception Safety:] If any exception is thrown, the result of the expression `bool(*this)` remains unchanged. | |
450 | If an exception is thrown during the call to `T`'s constructor, no effect. | |
451 | If an exception is thrown during the call to `T`'s assignment, the state of its contained value is as defined by the exception safety guarantee of `T`'s copy assignment. | |
452 | * [*Example:] | |
453 | `` | |
454 | T v; | |
455 | optional<T> opt0(v); | |
456 | optional<U> opt1; | |
457 | ||
458 | opt1 = opt0 ; | |
459 | assert ( *opt1 == static_cast<U>(v) ) ; | |
460 | `` | |
461 | ||
462 | __SPACE__ | |
463 | ||
464 | [#reference_optional_operator_move_equal_other_optional] | |
465 | ||
466 | [: `template<U> optional& optional<T>::operator= ( optional<U>&& rhs ) ;`] | |
467 | ||
468 | * [*Effect:] | |
469 | [table | |
470 | [] | |
471 | [[][[*`*this` contains a value]][[*`*this` does not contain a value]]] | |
472 | [[[*`rhs` contains a value]][assigns `std::move(*rhs)` to the contained value][initializes the contained value as if direct-initializing an object of type `T` with `std::move(*rhs)`]] | |
473 | [[[*`rhs` does not contain a value]][destroys the contained value by calling `val->T::~T()`][no effect]] | |
474 | ] | |
475 | * [*Returns:] `*this`. | |
476 | * [*Postconditions:] `bool(rhs) == bool(*this)`. | |
477 | * [*Exception Safety:] If any exception is thrown, the result of the expression `bool(*this)` remains unchanged. | |
478 | If an exception is thrown during the call to `T`'s constructor, no effect. | |
479 | If an exception is thrown during the call to `T`'s assignment, the state of its contained value is as defined by the exception safety guarantee of `T`'s copy assignment. | |
480 | * [*Example:] | |
481 | `` | |
482 | T v; | |
483 | optional<T> opt0(v); | |
484 | optional<U> opt1; | |
485 | ||
486 | opt1 = std::move(opt0) ; | |
487 | assert ( opt0 ); | |
488 | assert ( opt1 ) | |
489 | assert ( *opt1 == static_cast<U>(v) ) ; | |
490 | `` | |
491 | ||
492 | __SPACE__ | |
493 | ||
494 | [#reference_optional_emplace] | |
495 | ||
496 | [: `template<class... Args> void optional<T>::emplace( Args&&... args );`] | |
497 | ||
498 | * [*Requires:] The compiler supports rvalue references and variadic templates. | |
499 | * [*Effect:] If `*this` is initialized calls `*this = none`. | |
500 | Then initializes in-place the contained value as if direct-initializing an object | |
501 | of type `T` with `std::forward<Args>(args)...`. | |
502 | * [*Postconditions: ] `*this` is [_initialized]. | |
503 | * [*Throws:] Whatever the selected `T`'s constructor throws. | |
504 | * [*Exception Safety:] If an exception is thrown during the initialization of `T`, `*this` is ['uninitialized]. | |
505 | * [*Notes:] `T` need not be __MOVE_CONSTRUCTIBLE__ or `MoveAssignable`. On compilers that do not suppor variadic templates or rvalue references, this function is available in limited functionality. For details [link optional_emplace_workaround see here]. | |
506 | * [*Example:] | |
507 | `` | |
508 | T v; | |
509 | optional<const T> opt; | |
510 | opt.emplace(0); // create in-place using ctor T(int) | |
511 | opt.emplace(); // destroy previous and default-construct another T | |
512 | opt.emplace(v); // destroy and copy-construct in-place (no assignment called) | |
513 | `` | |
514 | ||
515 | __SPACE__ | |
516 | ||
517 | [#reference_optional_operator_equal_factory] | |
518 | ||
519 | [: `template<InPlaceFactory> optional<T>& optional<T>::operator=( InPlaceFactory const& f );`] | |
520 | [: `template<TypedInPlaceFactory> optional<T>& optional<T>::operator=( TypedInPlaceFactory const& f );`] | |
521 | ||
522 | * [*Effect:] Assigns an `optional` with a value of `T` obtained from the | |
523 | factory. | |
524 | * [*Postconditions: ] `*this` is [_initialized] and its value is ['directly given] | |
525 | from the factory `f` (i.e., the value [_is not copied]). | |
526 | * [*Throws:] Whatever the `T` constructor called by the factory throws. | |
527 | * [*Notes:] See [link boost_optional.tutorial.in_place_factories In-Place Factories] | |
528 | * [*Exception Safety:] Exceptions can only be thrown during the call to | |
529 | the `T` constructor used by the factory; in that case, the `optional` object | |
530 | will be reset to be ['uninitialized]. | |
531 | ||
532 | __SPACE__ | |
533 | ||
534 | [#reference_optional_reset_value] | |
535 | ||
536 | [: `void optional<T>::reset( T const& v ) ;`] | |
537 | * [*Deprecated:] same as `operator= ( T const& v) ;` | |
538 | ||
539 | __SPACE__ | |
540 | ||
541 | [#reference_optional_reset] | |
542 | ||
543 | [: `void optional<T>::reset() noexcept ;`] | |
544 | * [*Deprecated:] Same as `operator=( none_t );` | |
545 | ||
546 | __SPACE__ | |
547 | ||
548 | [#reference_optional_get] | |
549 | ||
550 | [: `T const& optional<T>::get() const ;`] | |
551 | [: `T& optional<T>::get() ;`] | |
552 | ||
553 | [: `inline T const& get ( optional<T> const& ) ;`] | |
554 | [: `inline T& get ( optional<T> &) ;`] | |
555 | ||
556 | * [*Requires:] `*this` is initialized | |
557 | * [*Returns:] A reference to the contained value | |
558 | * [*Throws:] Nothing. | |
559 | * [*Notes:] The requirement is asserted via `BOOST_ASSERT()`. | |
560 | ||
561 | ||
562 | __SPACE__ | |
563 | ||
564 | [#reference_optional_operator_asterisk] | |
565 | ||
566 | [: `T const& optional<T>::operator*() const& ;`] | |
567 | [: `T& optional<T>::operator*() &;`] | |
568 | ||
569 | * [*Requires:] `*this` is initialized | |
570 | * [*Returns:] A reference to the contained value | |
571 | * [*Throws:] Nothing. | |
572 | * [*Notes:] The requirement is asserted via `BOOST_ASSERT()`. On compilers that do not support ref-qualifiers on member functions these two overloads are replaced with the classical two: a `const` and non-`const` member functions. | |
573 | * [*Example:] | |
574 | `` | |
575 | T v ; | |
576 | optional<T> opt ( v ); | |
577 | T const& u = *opt; | |
578 | assert ( u == v ) ; | |
579 | T w ; | |
580 | *opt = w ; | |
581 | assert ( *opt == w ) ; | |
582 | `` | |
583 | ||
584 | __SPACE__ | |
585 | ||
586 | [#reference_optional_operator_asterisk_move] | |
587 | ||
588 | [: `T&& optional<T>::operator*() &&;`] | |
589 | ||
590 | * [*Requires:] `*this` contains a value. | |
591 | * [*Effects:] Equivalent to `return std::move(*val);`. | |
592 | * [*Notes:] The requirement is asserted via `BOOST_ASSERT()`. On compilers that do not support ref-qualifiers on member functions this overload is not present. | |
593 | ||
594 | ||
595 | __SPACE__ | |
596 | ||
597 | [#reference_optional_value] | |
598 | ||
599 | [: `T const& optional<T>::value() const& ;`] | |
600 | [: `T& optional<T>::value() & ;`] | |
601 | ||
602 | * [*Effects:] Equivalent to `return bool(*this) ? *val : throw bad_optional_access();`. | |
603 | * [*Notes:] On compilers that do not support ref-qualifiers on member functions these two overloads are replaced with the classical two: a `const` and non-`const` member functions. | |
604 | * [*Example:] | |
605 | `` | |
606 | T v ; | |
607 | optional<T> o0, o1 ( v ); | |
608 | assert ( o1.value() == v ); | |
609 | ||
610 | try { | |
611 | o0.value(); // throws | |
612 | assert ( false ); | |
613 | } | |
614 | catch(bad_optional_access&) { | |
615 | assert ( true ); | |
616 | } | |
617 | `` | |
618 | ||
619 | __SPACE__ | |
620 | ||
621 | [#reference_optional_value_move] | |
622 | ||
623 | [: `T&& optional<T>::value() && ;`] | |
624 | ||
625 | * [*Effects:] Equivalent to `return bool(*this) ? std::move(*val) : throw bad_optional_access();`. | |
626 | * [*Notes:] On compilers that do not support ref-qualifiers on member functions this overload is not present. | |
627 | ||
628 | __SPACE__ | |
629 | ||
630 | ||
631 | [#reference_optional_value_or] | |
632 | ||
633 | [: `template<class U> T optional<T>::value_or(U && v) const& ;`] | |
634 | ||
635 | * [*Effects:] Equivalent to `if (*this) return **this; else return std::forward<U>(v);`. | |
636 | * [*Remarks:] If `T` is not __COPY_CONSTRUCTIBLE__ or `U &&` is not convertible to `T`, the program is ill-formed. | |
637 | * [*Notes:] On compilers that do not support ref-qualifiers on member functions this overload is replaced with the `const`-qualified member function. On compilers without rvalue reference support the type of `v` becomes `U const&`. | |
638 | ||
639 | __SPACE__ | |
640 | ||
641 | [#reference_optional_value_or_move] | |
642 | ||
643 | [: `template<class U> T optional<T>::value_or(U && v) && ;`] | |
644 | ||
645 | * [*Effects:] Equivalent to `if (*this) return std::move(**this); else return std::forward<U>(v);`. | |
646 | * [*Remarks:] If `T` is not __MOVE_CONSTRUCTIBLE__ or `U &&` is not convertible to `T`, the program is ill-formed. | |
647 | * [*Notes:] On compilers that do not support ref-qualifiers on member functions this overload is not present. | |
648 | ||
649 | __SPACE__ | |
650 | ||
651 | [#reference_optional_value_or_call] | |
652 | ||
653 | [: `template<class F> T optional<T>::value_or_eval(F f) const& ;`] | |
654 | ||
655 | * [*Requires:] `T` is __COPY_CONSTRUCTIBLE__ and `F` models a __SGI_GENERATOR__ whose result type is convertible to `T`. | |
656 | * [*Effects:] `if (*this) return **this; else return f();`. | |
657 | * [*Notes:] On compilers that do not support ref-qualifiers on member functions this overload is replaced with the `const`-qualified member function. | |
658 | * [*Example:] | |
659 | `` | |
660 | int complain_and_0() | |
661 | { | |
662 | clog << "no value returned, using default" << endl; | |
663 | return 0; | |
664 | } | |
665 | ||
666 | optional<int> o1 = 1; | |
667 | optional<int> oN = none; | |
668 | ||
669 | int i = o1.value_or_eval(complain_and_0); // fun not called | |
670 | assert (i == 1); | |
671 | ||
672 | int j = oN.value_or_eval(complain_and_0); // fun called | |
673 | assert (i == 0); | |
674 | `` | |
675 | ||
676 | __SPACE__ | |
677 | ||
678 | [#reference_optional_value_or_call_move] | |
679 | ||
680 | [: `template<class F> T optional<T>::value_or_eval(F f) && ;`] | |
681 | ||
682 | * [*Requires:] `T` is __MOVE_CONSTRUCTIBLE__ and `F` models a __SGI_GENERATOR__ whose result type is convertible to `T`. | |
683 | * [*Effects:] `if (*this) return std::move(**this); else return f();`. | |
684 | * [*Notes:] On compilers that do not support ref-qualifiers on member functions this overload is not present. | |
685 | ||
686 | __SPACE__ | |
687 | ||
688 | [#reference_optional_get_value_or_value] | |
689 | ||
690 | [: `T const& optional<T>::get_value_or( T const& default) const ;`] | |
691 | [: `T& optional<T>::get_value_or( T& default ) ;`] | |
692 | ||
693 | * [*Deprecated:] Use `value_or()` instead. | |
694 | * [*Returns:] A reference to the contained value, if any, or `default`. | |
695 | * [*Throws:] Nothing. | |
696 | * [*Example:] | |
697 | `` | |
698 | T v, z ; | |
699 | optional<T> def; | |
700 | T const& y = def.get_value_or(z); | |
701 | assert ( y == z ) ; | |
702 | ||
703 | optional<T> opt ( v ); | |
704 | T const& u = opt.get_value_or(z); | |
705 | assert ( u == v ) ; | |
706 | assert ( u != z ) ; | |
707 | `` | |
708 | ||
709 | ||
710 | __SPACE__ | |
711 | ||
712 | [#reference_optional_get_ptr] | |
713 | ||
714 | [: `T const* optional<T>::get_ptr() const ;`] | |
715 | [: `T* optional<T>::get_ptr() ;`] | |
716 | ||
717 | * [*Returns:] If `*this` is initialized, a pointer to the contained value; | |
718 | else `0` (['null]). | |
719 | * [*Throws:] Nothing. | |
720 | * [*Notes:] The contained value is permanently stored within `*this`, so you | |
721 | should not hold nor delete this pointer | |
722 | * [*Example:] | |
723 | `` | |
724 | T v; | |
725 | optional<T> opt(v); | |
726 | optional<T> const copt(v); | |
727 | T* p = opt.get_ptr() ; | |
728 | T const* cp = copt.get_ptr(); | |
729 | assert ( p == get_pointer(opt) ); | |
730 | assert ( cp == get_pointer(copt) ) ; | |
731 | `` | |
732 | ||
733 | __SPACE__ | |
734 | ||
735 | [#reference_optional_operator_arrow] | |
736 | ||
737 | [: `T const* optional<T>::operator ->() const ;`] | |
738 | [: `T* optional<T>::operator ->() ;`] | |
739 | ||
740 | * [*Requires: ] `*this` is initialized. | |
741 | * [*Returns:] A pointer to the contained value. | |
742 | * [*Throws:] Nothing. | |
743 | * [*Notes:] The requirement is asserted via `BOOST_ASSERT()`. | |
744 | * [*Example:] | |
745 | `` | |
746 | struct X { int mdata ; } ; | |
747 | X x ; | |
748 | optional<X> opt (x); | |
749 | opt->mdata = 2 ; | |
750 | `` | |
751 | ||
752 | __SPACE__ | |
753 | ||
754 | [#reference_optional_operator_bool] | |
755 | ||
756 | [: `explicit optional<T>::operator bool() const noexcept ;`] | |
757 | ||
758 | * [*Returns:] `get_ptr() != 0`. | |
759 | * [*Notes:] On compilers that do not support explicit conversion operators this falls back to safe-bool idiom. | |
760 | * [*Example:] | |
761 | `` | |
762 | optional<T> def ; | |
763 | assert ( def == 0 ); | |
764 | optional<T> opt ( v ) ; | |
765 | assert ( opt ); | |
766 | assert ( opt != 0 ); | |
767 | `` | |
768 | ||
769 | __SPACE__ | |
770 | ||
771 | [#reference_optional_operator_not] | |
772 | ||
773 | [: `bool optional<T>::operator!() noexcept ;`] | |
774 | ||
775 | * [*Returns:] If `*this` is uninitialized, `true`; else `false`. | |
776 | * [*Notes:] This operator is provided for those compilers which can't | |
777 | use the ['unspecified-bool-type operator] in certain boolean contexts. | |
778 | * [*Example:] | |
779 | `` | |
780 | optional<T> opt ; | |
781 | assert ( !opt ); | |
782 | *opt = some_T ; | |
783 | ||
784 | // Notice the "double-bang" idiom here. | |
785 | assert ( !!opt ) ; | |
786 | `` | |
787 | ||
788 | __SPACE__ | |
789 | ||
790 | [#reference_optional_is_initialized] | |
791 | ||
792 | [: `bool optional<T>::is_initialized() const ;`] | |
793 | ||
794 | * [*Deprecated:] Same as `explicit operator bool () ;` | |
795 | ||
796 | ||
797 | [endsect] | |
798 | ||
799 | [section Detailed Semantics - Optional References] | |
800 | ||
801 | __SPACE__ | |
802 | ||
803 | [#reference_optional_ref_default_ctor] | |
804 | ||
805 | [: `optional<T&>::optional() noexcept;`] | |
806 | [: `optional<T&>::optional(none_t) noexcept;`] | |
807 | ||
808 | * [*Postconditions:] `bool(*this) == false`; `*this` refers to nothing. | |
809 | ||
810 | ||
811 | __SPACE__ | |
812 | ||
813 | [#reference_optional_ref_value_ctor] | |
814 | ||
815 | [: `template<class R> optional<T&>::optional(R&& r) noexcept;`] | |
816 | * [*Postconditions:] `bool(*this) == true`; `addressof(**this) == addressof(r)`. | |
817 | * [*Remarks:] Unless `R` is an lvalue reference, the program is ill-formed. This constructor does not participate in overload resolution if `decay<R>` is an instance of `boost::optional`. | |
818 | * [*Notes:] This constructor is declared `explicit` on compilers that do not correctly suport binding to const lvalues of integral types. For more details [link optional_reference_binding see here]. | |
819 | * [*Example:] | |
820 | `` | |
821 | T v; | |
822 | T& vref = v ; | |
823 | optional<T&> opt(vref); | |
824 | assert ( *opt == v ) ; | |
825 | ++ v ; // mutate referee | |
826 | assert (*opt == v); | |
827 | `` | |
828 | ||
829 | __SPACE__ | |
830 | ||
831 | [#reference_optional_ref_cond_value_ctor] | |
832 | ||
833 | [: `template<class R> optional<T&>::optional(bool cond, R&& r) noexcept;`] | |
834 | * [*Effects: ] Initializes `ref` with expression `cond ? addressof(r) : nullptr`. | |
835 | * [*Postconditions:] `bool(*this) == cond`; If `bool(*this)`, `addressof(**this) == addressof(r)`. | |
836 | * [*Remarks:] Unless `R` is an lvalue reference, the program is ill-formed. This constructor does not participate in overload resolution if `decay<R>` is an instance of `boost::optional`. | |
837 | ||
838 | __SPACE__ | |
839 | ||
840 | [#reference_optional_ref_copy_ctor] | |
841 | ||
842 | [: `optional<T&>::optional ( optional const& rhs ) noexcept ;`] | |
843 | ||
844 | * [*Effects: ] Initializes `ref` with expression `rhs.ref`. | |
845 | ||
846 | * [*Postconditions:] `bool(*this) == bool(rhs)`. | |
847 | ||
848 | * [*Example:] | |
849 | `` | |
850 | optional<T&> uninit ; | |
851 | assert (!uninit); | |
852 | ||
853 | optional<T&> uinit2 ( uninit ) ; | |
854 | assert ( uninit2 == uninit ); | |
855 | ||
856 | T v = 2 ; T& ref = v ; | |
857 | optional<T> init(ref); | |
858 | assert ( *init == v ) ; | |
859 | ||
860 | optional<T> init2 ( init ) ; | |
861 | assert ( *init2 == v ) ; | |
862 | ||
863 | v = 3 ; | |
864 | ||
865 | assert ( *init == 3 ) ; | |
866 | assert ( *init2 == 3 ) ; | |
867 | `` | |
868 | ||
869 | __SPACE__ | |
870 | ||
871 | [#reference_optional_ref_ctor_from_opt_U] | |
872 | ||
873 | [: `template<class U> explicit optional<T&>::optional ( optional<U&> const& rhs ) noexcept ;`] | |
874 | ||
875 | * [*Requires:] `is_convertible<U&, T&>::value` is `true`. | |
876 | ||
877 | * [*Effects: ] Initializes `ref` with expression `rhs.ref`. | |
878 | ||
879 | * [*Postconditions:] `bool(*this) == bool(rhs)`. | |
880 | ||
881 | ||
882 | __SPACE__ | |
883 | ||
884 | [#reference_optional_ref_assign_none_t] | |
885 | ||
886 | [: `optional<T&>::operator= ( none_t ) noexcept ;`] | |
887 | ||
888 | * [*Effects: ] Assigns `ref` with expression `nullptr`. | |
889 | ||
890 | * [*returns:] `*this`. | |
891 | ||
892 | * [*Postconditions:] `bool(*this) == false`. | |
893 | ||
894 | ||
895 | ||
896 | [#reference_optional_ref_copy_assign] | |
897 | ||
898 | [: `optional& optional<T&>::operator= ( optional const& rhs ) noexcept ;`] | |
899 | ||
900 | * [*Effects: ] Assigns `ref` with expression `rhs.ref`. | |
901 | ||
902 | * [*returns:] `*this`. | |
903 | ||
904 | * [*Postconditions:] `bool(*this) == bool(rhs)`. | |
905 | ||
906 | * [*Notes:] This behaviour is called ['rebinding semantics]. See [link boost_optional.tutorial.optional_references.rebinding_semantics_for_assignment_of_optional_references here] for details. | |
907 | ||
908 | * [*Example:] | |
909 | `` | |
910 | int a = 1 ; | |
911 | int b = 2 ; | |
912 | T& ra = a ; | |
913 | T& rb = b ; | |
914 | optional<int&> def ; | |
915 | optional<int&> ora(ra) ; | |
916 | optional<int&> orb(rb) ; | |
917 | ||
918 | def = orb ; // binds 'def' to 'b' through 'rb' wrapped within 'orb' | |
919 | assert ( *def == b ) ; | |
920 | *def = ora ; // changes the value of 'b' to a copy of the value of 'a' | |
921 | assert ( b == a ) ; | |
922 | int c = 3; | |
923 | int& rc = c ; | |
924 | optional<int&> orc(rc) ; | |
925 | ora = orc ; // REBINDS ora to 'c' through 'rc' | |
926 | c = 4 ; | |
927 | assert ( *ora == 4 ) ; | |
928 | `` | |
929 | ||
930 | ||
931 | [#reference_optional_ref_assign_optional_U] | |
932 | ||
933 | [: `template<class U> optional& optional<T&>::operator= ( optional<U&> const& rhs ) noexcept ;`] | |
934 | ||
935 | * [*Requires:] `is_convertible<U&, T&>::value` is `true`. | |
936 | ||
937 | * [*Effects: ] Assigns `ref` with expression `rhs.ref`. | |
938 | ||
939 | * [*returns:] `*this`. | |
940 | ||
941 | * [*Postconditions:] `bool(*this) == bool(rhs)`. | |
942 | ||
943 | ||
944 | __SPACE__ | |
945 | ||
946 | [#reference_optional_ref_assign_R] | |
947 | ||
948 | [: `template<class R> optional& optional<T&>::operator= ( R&& r ) noexcept ;`] | |
949 | ||
950 | * [*Effects: ] Assigns `ref` with expression `r`. | |
951 | ||
952 | * [*returns:] `*this`. | |
953 | ||
954 | * [*Postconditions:] `bool(*this) == true`. | |
955 | ||
956 | * [*Remarks:] Unless `R` is an lvalue reference, the program is ill-formed. This function does not participate in overload resolution if `decay<R>` is an instance of `boost::optional`. | |
957 | ||
958 | * [*Example:] | |
959 | `` | |
960 | int a = 1 ; | |
961 | int b = 2 ; | |
962 | T& ra = a ; | |
963 | T& rb = b ; | |
964 | optional<int&> def ; | |
965 | optional<int&> opt(ra) ; | |
966 | ||
967 | def = rb ; // binds 'def' to 'b' through 'rb' | |
968 | assert ( *def == b ) ; | |
969 | *def = a ; // changes the value of 'b' to a copy of the value of 'a' | |
970 | assert ( b == a ) ; | |
971 | int c = 3; | |
972 | int& rc = c ; | |
973 | opt = rc ; // REBINDS to 'c' through 'rc' | |
974 | c = 4 ; | |
975 | assert ( *opt == 4 ) ; | |
976 | `` | |
977 | ||
978 | __SPACE__ | |
979 | ||
980 | [#reference_optional_ref_emplace_R] | |
981 | ||
982 | [: `void optional<T&>::emplace( R&& r ) noexcept ;`] | |
983 | * [*Effects: ] Assigns `ref` with expression `r`. | |
984 | * [*Postconditions:] `bool(*this) == true`. | |
985 | * [*Remarks:] Unless `R` is an lvalue reference, the program is ill-formed. This function does not participate in overload resolution if `decay<R>` is an instance of `boost::optional`. | |
986 | ||
987 | __SPACE__ | |
988 | ||
989 | [#reference_optional_ref_get] | |
990 | [: `T& optional<T&>::get() const ;`] | |
991 | [: `T& optional<T&>::operator *() const ;`] | |
992 | * [*Requires:] `bool(*this) == true`. | |
993 | * [*Effects: ] Returns `*ref`. | |
994 | * [*Throws: ] Nothing. | |
995 | * [*Example:] | |
996 | `` | |
997 | T v ; | |
998 | T& vref = v ; | |
999 | optional<T&> opt ( vref ); | |
1000 | T const& vref2 = *opt; | |
1001 | assert ( vref2 == v ) ; | |
1002 | ++ v ; | |
1003 | assert ( *opt == v ) ; | |
1004 | `` | |
1005 | ||
1006 | __SPACE__ | |
1007 | ||
1008 | [#reference_optional_ref_arrow] | |
1009 | [: `T* optional<T&>::operator -> () const ;`] | |
1010 | * [*Requires:] `bool(*this) == true`. | |
1011 | * [*Effects: ] Returns `ref`. | |
1012 | * [*Throws: ] Nothing. | |
1013 | ||
1014 | __SPACE__ | |
1015 | ||
1016 | [#reference_optional_ref_value] | |
1017 | [: `T& optional<T&>::value() const ;`] | |
1018 | * [*Effects:] Equivalent to `return bool(*this) ? *val : throw bad_optional_access();`. | |
1019 | ||
1020 | __SPACE__ | |
1021 | ||
1022 | [#reference_optional_ref_value_or] | |
1023 | [: `template<class R> T& optional<T&>::value_or( R&& r ) const noexcept;`] | |
1024 | * [*Effects:] Equivalent to `if (*this) return **this; else return r;`. | |
1025 | * [*Remarks:] Unless `R` is an lvalue reference, the program is ill-formed. | |
1026 | ||
1027 | __SPACE__ | |
1028 | ||
1029 | [#reference_optional_ref_value_or_eval] | |
1030 | [: `template<class F> T& optional<T&>::value_or( F f ) const ;`] | |
1031 | * [*Effects:] Equivalent to `if (*this) return **this; else return f();`. | |
1032 | * [*Remarks:] Unless `decltype(f())` is an lvalue reference, the program is ill-formed. | |
1033 | ||
1034 | __SPACE__ | |
1035 | ||
1036 | [#reference_optional_ref_get_ptr] | |
1037 | [: `T* optional<T&>::get_ptr () const noexcept;`] | |
1038 | * [*Returns:] `ref`. | |
1039 | ||
1040 | __SPACE__ | |
1041 | ||
1042 | [#reference_optional_ref_operator_bool] | |
1043 | [: `optional<T&>::operator bool () const noexcept;`] | |
1044 | * [*Returns:] `bool(ref)`. | |
1045 | ||
1046 | __SPACE__ | |
1047 | ||
1048 | [#reference_optional_ref_operator_not] | |
1049 | [: `optional<T&>::operator ! () const noexcept;`] | |
1050 | * [*Returns:] `!bool(ref)`. | |
1051 | ||
1052 | __SPACE__ | |
1053 | ||
1054 | [#reference_optional_ref_reset] | |
1055 | [: `void optional<T&>::reset() noexcept;`] | |
1056 | * [*Effects:] Use `*this = none` instead. | |
1057 | * [*Remarks:] This function is depprecated. | |
1058 | ||
1059 | __SPACE__ | |
1060 | ||
1061 | [#reference_optional_ref_reset_value] | |
1062 | [: `template<class R> void optional<T&>::reset ( R&& r) noexcept;`] | |
1063 | * [*Effects:] Equivalent to `*this = std::forward<R>(r)`. | |
1064 | * [*Remarks:] This function is depprecated. | |
1065 | ||
1066 | __SPACE__ | |
1067 | ||
1068 | [#reference_optional_ref_is_initialized] | |
1069 | [: `bool optional<T&>::is_initialized() const noexcept;`] | |
1070 | * [*Effects:] Equivalent to `return bool(*this)`. | |
1071 | * [*Remarks:] This function is depprecated. | |
1072 | ||
1073 | __SPACE__ | |
1074 | ||
1075 | [#reference_optional_ref_get_value_or_value] | |
1076 | [: `template<class R> T& optional<T&>::get_value_or( R&& r ) const noexcept;`] | |
1077 | * [*Effects:] Equivalent to `return value_or(std::forward<R>(r);`. | |
1078 | * [*Remarks:] This function is depprecated. | |
1079 | ||
1080 | [endsect] | |
1081 | ||
1082 | ||
1083 | [section Detailed Semantics - Free Functions] | |
1084 | ||
1085 | ||
1086 | __SPACE__ | |
1087 | ||
1088 | [#reference_make_optional_value] | |
1089 | ||
1090 | [: `optional<T> make_optional( T const& v )`] | |
1091 | ||
1092 | * [*Returns: ] `optional<T>(v)` for the ['deduced] type `T` of `v`. | |
1093 | * [*Example:] | |
1094 | `` | |
1095 | template<class T> void foo ( optional<T> const& opt ) ; | |
1096 | ||
1097 | foo ( make_optional(1+1) ) ; // Creates an optional<int> | |
1098 | `` | |
1099 | ||
1100 | __SPACE__ | |
1101 | ||
1102 | [#reference_make_optional_bool_value] | |
1103 | ||
1104 | [: `optional<T> make_optional( bool condition, T const& v )`] | |
1105 | ||
1106 | * [*Returns: ] `optional<T>(condition, v)` for the ['deduced] type `T` of `v`. | |
1107 | * [*Example:] | |
1108 | `` | |
1109 | optional<double> calculate_foo() | |
1110 | { | |
1111 | double val = compute_foo(); | |
1112 | return make_optional(is_not_nan_and_finite(val),val); | |
1113 | } | |
1114 | ||
1115 | optional<double> v = calculate_foo(); | |
1116 | if ( !v ) | |
1117 | error("foo wasn't computed"); | |
1118 | `` | |
1119 | ||
1120 | __SPACE__ | |
1121 | ||
1122 | [#reference_operator_compare_equal_optional_optional] | |
1123 | ||
1124 | [: `bool operator == ( optional<T> const& x, optional<T> const& y );`] | |
1125 | ||
1126 | * [*Requires:] `T` shall meet requirements of __SGI_EQUALITY_COMPARABLE__. | |
1127 | * [*Returns:] If both `x` and `y` are initialized, `(*x == *y)`. If only | |
1128 | `x` or `y` is initialized, `false`. If both are uninitialized, `true`. | |
1129 | * [*Notes:] This definition guarantees that `optional<T>` not containing a value is compared unequal to any `optional<T>` containing any value, and equal to any other `optional<T>` not containing a value. | |
1130 | 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 | |
1131 | __FUNCTION_EQUAL_POINTEES__ instead | |
1132 | * [*Example:] | |
1133 | `` | |
1134 | optional<T> oN, oN_; | |
1135 | optional<T> o1(T(1)), o1_(T(1)); | |
1136 | optional<T> o2(T(2)); | |
1137 | ||
1138 | assert ( oN == oN ); // Identity implies equality | |
1139 | assert ( o1 == o1 ); // | |
1140 | ||
1141 | assert ( oN == oN_ ); // Both uninitialized compare equal | |
1142 | ||
1143 | assert ( oN != o1 ); // Initialized unequal to initialized. | |
1144 | ||
1145 | assert ( o1 == o1_ ); // Both initialized compare as (*lhs == *rhs) | |
1146 | assert ( o1 != o2 ); // | |
1147 | `` | |
1148 | ||
1149 | __SPACE__ | |
1150 | ||
1151 | [#reference_operator_compare_less_optional_optional] | |
1152 | ||
1153 | [: `bool operator < ( optional<T> const& x, optional<T> const& y );`] | |
1154 | ||
1155 | * [*Requires:] Expression `*x < *y` shall be well-formed and its result shall be convertible to `bool`. | |
1156 | * [*Returns:] `(!y) ? false : (!x) ? true : *x < *y`. | |
1157 | * [*Notes:] This definition guarantees that `optional<T>` not containing a value is ordered as less than any `optional<T>` containing any value, and equivalent to any other `optional<T>` not containing a value. | |
1158 | Pointers have shallow relational operators while `optional` has deep relational operators. Do not use `operator<` directly in generic code | |
1159 | which expect to be given either an `optional<T>` or a pointer; use __FUNCTION_LESS_POINTEES__ instead. `T` need not be __SGI_LESS_THAN_COMPARABLE__. Only single `operator<` is required. Other relational operations are defined in terms of this one. If `T`'s `operator<` satisfies the axioms of __SGI_LESS_THAN_COMPARABLE__ (transitivity, antisymmetry and irreflexivity), `optinal<T>` is __SGI_LESS_THAN_COMPARABLE__. | |
1160 | * [*Example:] | |
1161 | `` | |
1162 | optional<T> oN, oN_; | |
1163 | optional<T> o0(T(0)); | |
1164 | optional<T> o1(T(1)); | |
1165 | ||
1166 | assert ( !(oN < oN) ); // Identity implies equivalence | |
1167 | assert ( !(o1 < o1) ); | |
1168 | ||
1169 | assert ( !(oN < oN_) ); // Two uninitialized are equivalent | |
1170 | assert ( !(oN_ < oN) ); | |
1171 | ||
1172 | assert ( oN < o0 ); // Uninitialized is less than initialized | |
1173 | assert ( !(o0 < oN) ); | |
1174 | ||
1175 | assert ( o1 < o2 ) ; // Two initialized compare as (*lhs < *rhs) | |
1176 | assert ( !(o2 < o1) ) ; | |
1177 | assert ( !(o2 < o2) ) ; | |
1178 | `` | |
1179 | ||
1180 | __SPACE__ | |
1181 | ||
1182 | [#reference_operator_compare_not_equal_optional_optional] | |
1183 | ||
1184 | [: `bool operator != ( optional<T> const& x, optional<T> const& y );`] | |
1185 | ||
1186 | * [*Returns: ] `!( x == y );` | |
1187 | ||
1188 | __SPACE__ | |
1189 | ||
1190 | [#reference_operator_compare_greater_optional_optional] | |
1191 | ||
1192 | [: `bool operator > ( optional<T> const& x, optional<T> const& y );`] | |
1193 | ||
1194 | * [*Returns: ] `( y < x );` | |
1195 | ||
1196 | __SPACE__ | |
1197 | ||
1198 | [#reference_operator_compare_less_or_equal_optional_optional] | |
1199 | ||
1200 | [: `bool operator <= ( optional<T> const& x, optional<T> const& y );`] | |
1201 | ||
1202 | * [*Returns: ] `!( y < x );` | |
1203 | ||
1204 | __SPACE__ | |
1205 | ||
1206 | [#reference_operator_compare_greater_or_equal_optional_optional] | |
1207 | ||
1208 | [: `bool operator >= ( optional<T> const& x, optional<T> const& y );`] | |
1209 | ||
1210 | * [*Returns: ] `!( x < y );` | |
1211 | ||
1212 | __SPACE__ | |
1213 | ||
1214 | [#reference_operator_compare_equal_optional_none] | |
1215 | ||
1216 | [: `bool operator == ( optional<T> const& x, none_t ) noexcept;`] | |
1217 | [: `bool operator == ( none_t, optional<T> const& x ) noexcept;`] | |
1218 | ||
1219 | * [*Returns:] `!x`. | |
1220 | * [*Notes:] `T` need not meet requirements of __SGI_EQUALITY_COMPARABLE__. | |
1221 | ||
1222 | ||
1223 | __SPACE__ | |
1224 | ||
1225 | [#reference_operator_compare_not_equal_optional_none] | |
1226 | ||
1227 | [: `bool operator != ( optional<T> const& x, none_t ) noexcept;`] | |
1228 | [: `bool operator != ( none_t, optional<T> const& x ) noexcept;`] | |
1229 | ||
1230 | * [*Returns: ] `bool(x);` | |
1231 | ||
1232 | ||
1233 | __SPACE__ | |
1234 | ||
1235 | ||
1236 | [#reference_free_get_pointer] | |
1237 | [: `auto get_pointer ( optional<T>& o ) -> typename optional<T>::pointer_type ;`] | |
1238 | [: `auto get_pointer ( optional<T> const& o ) -> typename optional<T>::pointer_const_type ;`] | |
1239 | * [*Returns:] `o.get_ptr()`. | |
1240 | * [*Throws:] Nothing. | |
1241 | ||
1242 | __SPACE__ | |
1243 | ||
1244 | ||
1245 | [#reference_free_get_value_or] | |
1246 | [: `auto get_optional_value_or ( optional<T>& o, typename optional<T>::reference_type def ) -> typename optional<T>::reference_type ;`] | |
1247 | [: `auto get_optional_value_or ( optional<T> const& o, typename optional<T>::reference_const_type def ) -> typename optional<T>::reference_const_type ;`] | |
1248 | * [*Returns:] `o.get_value_or(def)`. | |
1249 | * [*Throws:] Nothing. | |
1250 | * [*Remarks:] This function is deprecated. | |
1251 | ||
1252 | __SPACE__ | |
1253 | ||
1254 | [#reference_swap_optional_optional] | |
1255 | ||
1256 | [: `void swap ( optional<T>& x, optional<T>& y ) ;`] | |
1257 | ||
1258 | * [*Requires:] Lvalues of type `T` shall be swappable and `T` shall be __MOVE_CONSTRUCTIBLE__. | |
1259 | * [*Effects:] | |
1260 | [table | |
1261 | [] | |
1262 | [[][[*`*this` contains a value]][[*`*this` does not contain a value]]] | |
1263 | [[[*`rhs` contains a value]][calls `swap(*(*this), *rhs)`][initializes the contained value of `*this` as if direct-initializing an object of type `T` with the expression `std::move(*rhs)`, followed by `rhs.val->T::~T()`, `*this` contains a value and `rhs` does not contain a value]] | |
1264 | [[[*`rhs` does not contain a value]][initializes the contained value of `rhs` as if direct-initializing an object of type `T` with the expression `std::move(*(*this))`, followed by `val->T::~T()`, `*this` does not contain a value and `rhs` contains a value][no effect]] | |
1265 | ] | |
1266 | * [*Postconditions:] The states of `x` and `y` interchanged. | |
1267 | * [*Throws:] If both are initialized, whatever `swap(T&,T&)` throws. If only | |
1268 | one is initialized, whatever `T::T ( T&& )` throws. | |
1269 | * [*Example:] | |
1270 | `` | |
1271 | T x(12); | |
1272 | T y(21); | |
1273 | optional<T> def0 ; | |
1274 | optional<T> def1 ; | |
1275 | optional<T> optX(x); | |
1276 | optional<T> optY(y); | |
1277 | ||
1278 | boost::swap(def0,def1); // no-op | |
1279 | ||
1280 | boost::swap(def0,optX); | |
1281 | assert ( *def0 == x ); | |
1282 | assert ( !optX ); | |
1283 | ||
1284 | boost::swap(def0,optX); // Get back to original values | |
1285 | ||
1286 | boost::swap(optX,optY); | |
1287 | assert ( *optX == y ); | |
1288 | assert ( *optY == x ); | |
1289 | `` | |
1290 | ||
1291 | __SPACE__ | |
1292 | ||
1293 | [#reference_swap_optional_reference] | |
1294 | [: `void swap ( optional<T&>& x, optional<T&>& y ) noexcept ;`] | |
1295 | ||
1296 | * [*Postconditions:] `x` refers to what `y` refererred to before the swap (if anything). `y` refers to whatever `x` referred to before the swap. | |
1297 | ||
1298 | * [*Example:] | |
1299 | `` | |
1300 | T x(12); | |
1301 | T y(21); | |
1302 | ||
1303 | optional<T&> opt0; | |
1304 | optional<T&> optX (x); | |
1305 | optional<T&> optY (y); | |
1306 | ||
1307 | boost::swap(optX, optY); | |
1308 | assert (addressof(*optX) == addressof(y)); | |
1309 | assert (addressof(*optY) == addressof(x)); | |
1310 | ||
1311 | boost::swap(opt0, optX); | |
1312 | assert ( opt0 ); | |
1313 | assert ( !optX ); | |
1314 | assert (addressof(*opt0) == addressof(y)); | |
1315 | `` | |
1316 | ||
1317 | [endsect] |