mirror of
https://github.com/boostorg/optional.git
synced 2025-06-26 04:21:34 +02:00
Compare commits
18 Commits
svn-branch
...
svn-branch
| Author | SHA1 | Date | |
|---|---|---|---|
| 041aa12848 | |||
| 3ff4258fbb | |||
| 35040aab6a | |||
| bfd5cc0a87 | |||
| 0fd45d73b1 | |||
| 3bf8d0f1b4 | |||
| 789cb2b24f | |||
| 7287f2bf11 | |||
| b6a1946a60 | |||
| 9bbde2be14 | |||
| f258713788 | |||
| 3dc3f46d66 | |||
| c23c21d9c2 | |||
| 5182283649 | |||
| 4599ae0bfd | |||
| 9ccefc8349 | |||
| 0961a6598a | |||
| 03248b5fd8 |
@ -1,28 +0,0 @@
|
||||
# Boost.Optional
|
||||
#
|
||||
# Copyright (c) 2003-2007 Fernando Luis Cacciola Carballal
|
||||
#
|
||||
# Distributed under the Boost Software License, Version 1.0.
|
||||
# (See accompanying file LICENSE_1_0.txt or copy at
|
||||
# http://www.boost.org/LICENSE_1_0.txt)
|
||||
|
||||
|
||||
# Quickbook
|
||||
# -----------------------------------------------------------------------------
|
||||
|
||||
import quickbook ;
|
||||
|
||||
xml optional
|
||||
:
|
||||
optional.qbk
|
||||
;
|
||||
|
||||
boostbook standalone
|
||||
:
|
||||
optional
|
||||
:
|
||||
<xsl:param>toc.max.depth=1
|
||||
<xsl:param>toc.section.depth=1
|
||||
<xsl:param>chunk.section.depth=1
|
||||
;
|
||||
|
||||
@ -1,60 +0,0 @@
|
||||
[/
|
||||
Boost.Optional
|
||||
|
||||
Copyright (c) 2003-2007 Fernando Luis Cacciola Carballal
|
||||
|
||||
Distributed under the Boost Software License, Version 1.0.
|
||||
(See accompanying file LICENSE_1_0.txt or copy at
|
||||
http://www.boost.org/LICENSE_1_0.txt)
|
||||
]
|
||||
|
||||
|
||||
[section Acknowledgments]
|
||||
|
||||
[heading Pre-formal review]
|
||||
|
||||
* Peter Dimov suggested the name 'optional', and was the first to point out
|
||||
the need for aligned storage.
|
||||
* Douglas Gregor developed 'type_with_alignment', and later Eric Friedman
|
||||
coded 'aligned_storage', which are the core of the optional class
|
||||
implementation.
|
||||
* Andrei Alexandrescu and Brian Parker also worked with aligned storage
|
||||
techniques and their work influenced the current implementation.
|
||||
* Gennadiy Rozental made extensive and important comments which shaped the
|
||||
design.
|
||||
* Vesa Karvonen and Douglas Gregor made quite useful comparisons between
|
||||
optional, variant and any; and made other relevant comments.
|
||||
* Douglas Gregor and Peter Dimov commented on comparisons and evaluation
|
||||
in boolean contexts.
|
||||
* Eric Friedman helped understand the issues involved with aligned storage,
|
||||
move/copy operations and exception safety.
|
||||
* Many others have participated with useful comments: Aleksey Gurotov,
|
||||
Kevlin Henney, David Abrahams, and others I can't recall.
|
||||
|
||||
[heading Post-formal review]
|
||||
|
||||
* William Kempf carefully considered the originally proposed interface
|
||||
and suggested the new interface which is currently used. He also started and
|
||||
fueled the discussion about the analogy optional<>/smart pointer and about
|
||||
relational operators.
|
||||
* Peter Dimov, Joel de Guzman, David Abrahams, Tanton Gibbs and Ian Hanson
|
||||
focused on the relational semantics of optional (originally undefined);
|
||||
concluding with the fact that the pointer-like interface doesn't make it a
|
||||
pointer so it shall have deep relational operators.
|
||||
* Augustus Saunders also explored the different relational semantics between
|
||||
optional<> and a pointer and developed the OptionalPointee concept as an aid
|
||||
against potential conflicts on generic code.
|
||||
* Joel de Guzman noticed that optional<> can be seen as an API on top of
|
||||
variant<T,nil_t>.
|
||||
* Dave Gomboc explained the meaning and usage of the Haskell analog to
|
||||
optional<>: the Maybe type constructor (analogy originally pointed out by
|
||||
David Sankel).
|
||||
* Other comments were posted by Vincent Finn, Anthony Williams, Ed Brey,
|
||||
Rob Stewart, and others.
|
||||
* Joel de Guzman made the case for the support of references and helped
|
||||
with the proper semantics.
|
||||
* Mat Marcus shown the virtues of a value-oriented interface, influencing
|
||||
the current design, and contributed the idea of "none".
|
||||
|
||||
[endsect]
|
||||
|
||||
@ -1,17 +0,0 @@
|
||||
[/
|
||||
Boost.Optional
|
||||
|
||||
Copyright (c) 2003-2007 Fernando Luis Cacciola Carballal
|
||||
|
||||
Distributed under the Boost Software License, Version 1.0.
|
||||
(See accompanying file LICENSE_1_0.txt or copy at
|
||||
http://www.boost.org/LICENSE_1_0.txt)
|
||||
]
|
||||
|
||||
|
||||
[section Dependencies and Portability]
|
||||
|
||||
The implementation uses `type_traits/alignment_of.hpp` and
|
||||
`type_traits/type_with_alignment.hpp`
|
||||
|
||||
[endsect]
|
||||
@ -1,251 +0,0 @@
|
||||
[/
|
||||
Boost.Optional
|
||||
|
||||
Copyright (c) 2003-2007 Fernando Luis Cacciola Carballal
|
||||
|
||||
Distributed under the Boost Software License, Version 1.0.
|
||||
(See accompanying file LICENSE_1_0.txt or copy at
|
||||
http://www.boost.org/LICENSE_1_0.txt)
|
||||
]
|
||||
|
||||
[section Development]
|
||||
|
||||
[section The models]
|
||||
|
||||
In C++, we can ['declare] an object (a variable) of type `T`, and we can give this
|
||||
variable an ['initial value] (through an ['initializer]. (c.f. 8.5)).
|
||||
When a declaration includes a non-empty initializer (an initial value is given),
|
||||
it is said that the object has been initialized.
|
||||
If the declaration uses an empty initializer (no initial value is given), and
|
||||
neither default nor value initialization applies, it is said that the object is
|
||||
[*uninitialized]. Its actual value exist but has an ['indeterminate initial value]
|
||||
(c.f. 8.5.9).
|
||||
`optional<T>` intends to formalize the notion of initialization (or lack of it)
|
||||
allowing a program to test whether an object has been initialized and stating
|
||||
that access to the value of an uninitialized object is undefined behavior. That
|
||||
is, when a variable is declared as `optional<T>` and no initial value is given,
|
||||
the variable is ['formally] uninitialized. A formally uninitialized optional object
|
||||
has conceptually no value at all and this situation can be tested at runtime. It
|
||||
is formally ['undefined behavior] to try to access the value of an uninitialized
|
||||
optional. An uninitialized optional can be assigned a value, in which case its initialization state changes to initialized. Furthermore, given the formal
|
||||
treatment of initialization states in optional objects, it is even possible to
|
||||
reset an optional to ['uninitialized].
|
||||
|
||||
In C++ there is no formal notion of uninitialized objects, which means that
|
||||
objects always have an initial value even if indeterminate.
|
||||
As discussed on the previous section, this has a drawback because you need
|
||||
additional information to tell if an object has been effectively initialized.
|
||||
One of the typical ways in which this has been historically dealt with is via
|
||||
a special value: `EOF`, `npos`, -1, etc... This is equivalent to adding the
|
||||
special value to the set of possible values of a given type. This super set of
|
||||
`T` plus some ['nil_t]—were `nil_t` is some stateless POD-can be modeled in modern
|
||||
languages as a [*discriminated union] of T and nil_t. Discriminated unions are
|
||||
often called ['variants]. A variant has a ['current type], which in our case is either
|
||||
`T` or `nil_t`.
|
||||
Using the __BOOST_VARIANT__ library, this model can be implemented in terms of `boost::variant<T,nil_t>`.
|
||||
There is precedent for a discriminated union as a model for an optional value:
|
||||
the __HASKELL__ [*Maybe] built-in type constructor. Thus, a discriminated union
|
||||
`T+nil_t` serves as a conceptual foundation.
|
||||
|
||||
A `variant<T,nil_t>` follows naturally from the traditional idiom of extending
|
||||
the range of possible values adding an additional sentinel value with the
|
||||
special meaning of ['Nothing]. However, this additional ['Nothing] value is largely
|
||||
irrelevant for our purpose since our goal is to formalize the notion of
|
||||
uninitialized objects and, while a special extended value can be used to convey
|
||||
that meaning, it is not strictly necessary in order to do so.
|
||||
|
||||
The observation made in the last paragraph about the irrelevant nature of the
|
||||
additional `nil_t` with respect to [_purpose] of `optional<T>` suggests an
|
||||
alternative model: a ['container] that either has a value of `T` or nothing.
|
||||
|
||||
As of this writing I don't know of any precedence for a variable-size
|
||||
fixed-capacity (of 1) stack-based container model for optional values, yet I
|
||||
believe this is the consequence of the lack of practical implementations of
|
||||
such a container rather than an inherent shortcoming of the container model.
|
||||
|
||||
In any event, both the discriminated-union or the single-element container
|
||||
models serve as a conceptual ground for a class representing optional—i.e.
|
||||
possibly uninitialized—objects.
|
||||
For instance, these models show the ['exact] semantics required for a wrapper
|
||||
of optional values:
|
||||
|
||||
Discriminated-union:
|
||||
|
||||
* [*deep-copy] semantics: copies of the variant implies copies of the value.
|
||||
* [*deep-relational] semantics: comparisons between variants matches both
|
||||
current types and values
|
||||
* If the variant's current type is `T`, it is modeling an ['initialized] optional.
|
||||
* If the variant's current type is not `T`, it is modeling an ['uninitialized]
|
||||
optional.
|
||||
* Testing if the variant's current type is `T` models testing if the optional
|
||||
is initialized
|
||||
* Trying to extract a `T` from a variant when its current type is not `T`, models
|
||||
the undefined behavior of trying to access the value of an uninitialized optional
|
||||
|
||||
Single-element container:
|
||||
|
||||
* [*deep-copy] semantics: copies of the container implies copies of the value.
|
||||
* [*deep-relational] semantics: comparisons between containers compare container
|
||||
size and if match, contained value
|
||||
* If the container is not empty (contains an object of type `T`), it is modeling
|
||||
an ['initialized] optional.
|
||||
* If the container is empty, it is modeling an ['uninitialized] optional.
|
||||
* Testing if the container is empty models testing if the optional is
|
||||
initialized
|
||||
* Trying to extract a `T` from an empty container models the undefined behavior
|
||||
of trying to access the value of an uninitialized optional
|
||||
|
||||
[endsect]
|
||||
|
||||
[section The semantics]
|
||||
|
||||
Objects of type `optional<T>` are intended to be used in places where objects of
|
||||
type `T` would but which might be uninitialized. Hence, `optional<T>`'s purpose is
|
||||
to formalize the additional possibly uninitialized state.
|
||||
From the perspective of this role, `optional<T>` can have the same operational
|
||||
semantics of `T` plus the additional semantics corresponding to this special
|
||||
state.
|
||||
As such, `optional<T>` could be thought of as a ['supertype] of `T`. Of course, we
|
||||
can't do that in C++, so we need to compose the desired semantics using a
|
||||
different mechanism.
|
||||
Doing it the other way around, that is, making `optional<T>` a ['subtype] of `T`
|
||||
is not only conceptually wrong but also impractical: it is not allowed to
|
||||
derive from a non-class type, such as a built-in type.
|
||||
|
||||
We can draw from the purpose of `optional<T>` the required basic semantics:
|
||||
|
||||
* [*Default Construction:] To introduce a formally uninitialized wrapped
|
||||
object.
|
||||
* [*Direct Value Construction via copy:] To introduce a formally initialized
|
||||
wrapped object whose value is obtained as a copy of some object.
|
||||
* [*Deep Copy Construction:] To obtain a new yet equivalent wrapped object.
|
||||
* [*Direct Value Assignment (upon initialized):] To assign a value to the
|
||||
wrapped object.
|
||||
* [*Direct Value Assignment (upon uninitialized):] To initialize the wrapped
|
||||
object with a value obtained as a copy of some object.
|
||||
* [*Assignment (upon initialized):] To assign to the wrapped object the value
|
||||
of another wrapped object.
|
||||
* [*Assignment (upon uninitialized):] To initialize the wrapped object with
|
||||
value of another wrapped object.
|
||||
* [*Deep Relational Operations (when supported by the type T):] To compare
|
||||
wrapped object values taking into account the presence of uninitialized states.
|
||||
* [*Value access:] To unwrap the wrapped object.
|
||||
* [*Initialization state query:] To determine if the object is formally
|
||||
initialized or not.
|
||||
* [*Swap:] To exchange wrapped objects. (with whatever exception safety
|
||||
guarantees are provided by `T`'s swap).
|
||||
* [*De-initialization:] To release the wrapped object (if any) and leave the
|
||||
wrapper in the uninitialized state.
|
||||
|
||||
Additional operations are useful, such as converting constructors and
|
||||
converting assignments, in-place construction and assignment, and safe
|
||||
value access via a pointer to the wrapped object or null.
|
||||
|
||||
[endsect]
|
||||
|
||||
[section The Interface]
|
||||
|
||||
Since the purpose of optional is to allow us to use objects with a formal
|
||||
uninitialized additional state, the interface could try to follow the
|
||||
interface of the underlying `T` type as much as possible. In order to choose
|
||||
the proper degree of adoption of the native `T` interface, the following must
|
||||
be noted: Even if all the operations supported by an instance of type `T` are
|
||||
defined for the entire range of values for such a type, an `optional<T>`
|
||||
extends such a set of values with a new value for which most
|
||||
(otherwise valid) operations are not defined in terms of `T`.
|
||||
|
||||
Furthermore, since `optional<T>` itself is merely a `T` wrapper (modeling a `T`
|
||||
supertype), any attempt to define such operations upon uninitialized optionals
|
||||
will be totally artificial w.r.t. `T`.
|
||||
|
||||
This library chooses an interface which follows from `T`'s interface only for
|
||||
those operations which are well defined (w.r.t the type `T`) even if any of the
|
||||
operands are uninitialized. These operations include: construction,
|
||||
copy-construction, assignment, swap and relational operations.
|
||||
|
||||
For the value access operations, which are undefined (w.r.t the type `T`) when
|
||||
the operand is uninitialized, a different interface is chosen (which will be
|
||||
explained next).
|
||||
|
||||
Also, the presence of the possibly uninitialized state requires additional
|
||||
operations not provided by `T` itself which are supported by a special interface.
|
||||
|
||||
[heading Lexically-hinted Value Access in the presence of possibly
|
||||
untitialized optional objects: The operators * and ->]
|
||||
|
||||
A relevant feature of a pointer is that it can have a [*null pointer value].
|
||||
This is a ['special] value which is used to indicate that the pointer is not
|
||||
referring to any object at all. In other words, null pointer values convey
|
||||
the notion of inexistent objects.
|
||||
|
||||
This meaning of the null pointer value allowed pointers to became a ['de
|
||||
facto] standard for handling optional objects because all you have to do
|
||||
to refer to a value which you don't really have is to use a null pointer
|
||||
value of the appropriate type. Pointers have been used for decades—from
|
||||
the days of C APIs to modern C++ libraries—to ['refer] to optional (that is,
|
||||
possibly inexistent) objects; particularly as optional arguments to a
|
||||
function, but also quite often as optional data members.
|
||||
|
||||
The possible presence of a null pointer value makes the operations that
|
||||
access the pointee's value possibly undefined, therefore, expressions which
|
||||
use dereference and access operators, such as: `( *p = 2 )` and `( p->foo() )`,
|
||||
implicitly convey the notion of optionality, and this information is tied to
|
||||
the ['syntax] of the expressions. That is, the presence of operators `*` and `->`
|
||||
tell by themselves —without any additional context— that the expression will
|
||||
be undefined unless the implied pointee actually exist.
|
||||
|
||||
Such a ['de facto] idiom for referring to optional objects can be formalized
|
||||
in the form of a concept: the __OPTIONAL_POINTEE__ concept.
|
||||
This concept captures the syntactic usage of operators `*`, `->` and
|
||||
conversion to `bool` to convey the notion of optionality.
|
||||
|
||||
However, pointers are good to [_refer] to optional objects, but not particularly
|
||||
good to handle the optional objects in all other respects, such as initializing
|
||||
or moving/copying them. The problem resides in the shallow-copy of pointer
|
||||
semantics: if you need to effectively move or copy the object, pointers alone
|
||||
are not enough. The problem is that copies of pointers do not imply copies of
|
||||
pointees. For example, as was discussed in the motivation, pointers alone
|
||||
cannot be used to return optional objects from a function because the object
|
||||
must move outside from the function and into the caller's context.
|
||||
|
||||
A solution to the shallow-copy problem that is often used is to resort to
|
||||
dynamic allocation and use a smart pointer to automatically handle the details
|
||||
of this. For example, if a function is to optionally return an object `X`, it can
|
||||
use `shared_ptr<X>` as the return value. However, this requires dynamic allocation
|
||||
of `X`. If `X` is a built-in or small POD, this technique is very poor in terms of
|
||||
required resources. Optional objects are essentially values so it is very
|
||||
convenient to be able to use automatic storage and deep-copy semantics to
|
||||
manipulate optional values just as we do with ordinary values. Pointers do
|
||||
not have this semantics, so are inappropriate for the initialization and
|
||||
transport of optional values, yet are quite convenient for handling the access
|
||||
to the possible undefined value because of the idiomatic aid present in the
|
||||
__OPTIONAL_POINTEE__ concept incarnated by pointers.
|
||||
|
||||
|
||||
[heading Optional<T> as a model of OptionalPointee]
|
||||
|
||||
For value access operations `optional<>` uses operators `*` and `->` to
|
||||
lexically warn about the possibly uninitialized state appealing to the
|
||||
familiar pointer semantics w.r.t. to null pointers.
|
||||
|
||||
[warning
|
||||
However, it is particularly important to note that `optional<>` objects
|
||||
are not pointers. [_`optional<>` is not, and does not model, a pointer].
|
||||
]
|
||||
|
||||
For instance, `optional<>` does not have shallow-copy so does not alias:
|
||||
two different optionals never refer to the ['same] value unless `T` itself is
|
||||
a reference (but may have ['equivalent] values).
|
||||
The difference between an `optional<T>` and a pointer must be kept in mind,
|
||||
particularly because the semantics of relational operators are different:
|
||||
since `optional<T>` is a value-wrapper, relational operators are deep: they
|
||||
compare optional values; but relational operators for pointers are shallow:
|
||||
they do not compare pointee values.
|
||||
As a result, you might be able to replace `optional<T>` by `T*` on some
|
||||
situations but not always. Specifically, on generic code written for both,
|
||||
you cannot use relational operators directly, and must use the template
|
||||
functions __FUNCTION_EQUAL_POINTEES__ and __FUNCTION_LESS_POINTEES__ instead.
|
||||
|
||||
[endsect]
|
||||
|
||||
[endsect]
|
||||
102
doc/examples.qbk
102
doc/examples.qbk
@ -1,102 +0,0 @@
|
||||
[/
|
||||
Boost.Optional
|
||||
|
||||
Copyright (c) 2003-2007 Fernando Luis Cacciola Carballal
|
||||
|
||||
Distributed under the Boost Software License, Version 1.0.
|
||||
(See accompanying file LICENSE_1_0.txt or copy at
|
||||
http://www.boost.org/LICENSE_1_0.txt)
|
||||
]
|
||||
|
||||
|
||||
[section Examples]
|
||||
|
||||
[section Optional return values]
|
||||
|
||||
optional<char> get_async_input()
|
||||
{
|
||||
if ( !queue.empty() )
|
||||
return optional<char>(queue.top());
|
||||
else return optional<char>(); // uninitialized
|
||||
}
|
||||
|
||||
void receive_async_message()
|
||||
{
|
||||
optional<char> rcv ;
|
||||
// The safe boolean conversion from 'rcv' is used here.
|
||||
while ( (rcv = get_async_input()) && !timeout() )
|
||||
output(*rcv);
|
||||
}
|
||||
|
||||
[endsect]
|
||||
|
||||
[section Optional local variables]
|
||||
|
||||
optional<string> name ;
|
||||
if ( database.open() )
|
||||
{
|
||||
name.reset ( database.lookup(employer_name) ) ;
|
||||
}
|
||||
else
|
||||
{
|
||||
if ( can_ask_user )
|
||||
name.reset ( user.ask(employer_name) ) ;
|
||||
}
|
||||
|
||||
if ( name )
|
||||
print(*name);
|
||||
else print("employer's name not found!");
|
||||
|
||||
[endsect]
|
||||
|
||||
[section Optional data members]
|
||||
|
||||
class figure
|
||||
{
|
||||
public:
|
||||
|
||||
figure()
|
||||
{
|
||||
// data member 'm_clipping_rect' is uninitialized at this point.
|
||||
}
|
||||
|
||||
void clip_in_rect ( rect const& rect )
|
||||
{
|
||||
....
|
||||
m_clipping_rect.reset ( rect ) ; // initialized here.
|
||||
}
|
||||
|
||||
void draw ( canvas& cvs )
|
||||
{
|
||||
if ( m_clipping_rect )
|
||||
do_clipping(*m_clipping_rect);
|
||||
|
||||
cvs.drawXXX(..);
|
||||
}
|
||||
|
||||
// this can return NULL.
|
||||
rect const* get_clipping_rect() { return get_pointer(m_clipping_rect); }
|
||||
|
||||
private :
|
||||
|
||||
optional<rect> m_clipping_rect ;
|
||||
|
||||
};
|
||||
|
||||
[endsect]
|
||||
|
||||
[section Bypassing expensive unnecessary default construction]
|
||||
|
||||
class ExpensiveCtor { ... } ;
|
||||
class Fred
|
||||
{
|
||||
Fred() : mLargeVector(10000) {}
|
||||
|
||||
std::vector< optional<ExpensiveCtor> > mLargeVector ;
|
||||
} ;
|
||||
|
||||
[endsect]
|
||||
|
||||
[endsect]
|
||||
|
||||
|
||||
@ -1,14 +0,0 @@
|
||||
index.html
|
||||
boost_optional/development.html
|
||||
boost_optional/synopsis.html
|
||||
boost_optional/detailed_semantics.html
|
||||
boost_optional/examples.html
|
||||
boost_optional/optional_references.html
|
||||
boost_optional/rebinding_semantics_for_assignment_of_optional_references.html
|
||||
boost_optional/in_place_factories.html
|
||||
boost_optional/a_note_about_optional_bool_.html
|
||||
boost_optional/exception_safety_guarantees.html
|
||||
boost_optional/type_requirements.html
|
||||
boost_optional/implementation_notes.html
|
||||
boost_optional/dependencies_and_portability.html
|
||||
boost_optional/acknowledgments.html
|
||||
@ -1,84 +0,0 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||||
<title>A note about
|
||||
optional<bool></title>
|
||||
<link rel="stylesheet" href="../boostbook.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
|
||||
<link rel="start" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
|
||||
<link rel="up" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
|
||||
<link rel="prev" href="in_place_factories.html" title="In-Place Factories">
|
||||
<link rel="next" href="exception_safety_guarantees.html" title="Exception Safety
|
||||
Guarantees">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%">
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../index.htm">Home</a></td>
|
||||
<td align="center"><a href="../libraries.html">Libraries</a></td>
|
||||
<td align="center"><a href="../../../people/people.htm">People</a></td>
|
||||
<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
|
||||
<td align="center"><a href="../../../more/index.htm">More</a></td>
|
||||
</table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="in_place_factories.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="exception_safety_guarantees.html"><img src="../images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="boost_optional.a_note_about_optional_bool_"></a><a href="a_note_about_optional_bool_.html" title="A note about
|
||||
optional<bool>">A note about
|
||||
optional<bool></a>
|
||||
</h2></div></div></div>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="keyword">bool</span><span class="special">></span></code> should
|
||||
be used with special caution and consideration.
|
||||
</p>
|
||||
<p>
|
||||
First, it is functionally similar to a tristate boolean (false,maybe,true)
|
||||
—such as <a href="../../../../tribool/index.html" target="_top">boost::tribool</a>—
|
||||
except that in a tristate boolean, the maybe state <span class="underline">represents
|
||||
a valid value</span>, unlike the corresponding state of an uninitialized
|
||||
<code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="keyword">bool</span><span class="special">></span></code>. It
|
||||
should be carefully considered if an <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="keyword">bool</span><span class="special">></span></code>
|
||||
instead of a <code class="computeroutput"><span class="identifier">tribool</span></code> is really
|
||||
needed.
|
||||
</p>
|
||||
<p>
|
||||
Second, <code class="computeroutput"><span class="identifier">optional</span><span class="special"><></span></code>
|
||||
provides an implicit conversion to <code class="computeroutput"><span class="keyword">bool</span></code>.
|
||||
This conversion refers to the initialization state and not to the contained
|
||||
value. Using <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="keyword">bool</span><span class="special">></span></code> can
|
||||
lead to subtle errors due to the implicit <code class="computeroutput"><span class="keyword">bool</span></code>
|
||||
conversion:
|
||||
</p>
|
||||
<pre class="programlisting">
|
||||
<span class="keyword">void</span> <span class="identifier">foo</span> <span class="special">(</span> <span class="keyword">bool</span> <span class="identifier">v</span> <span class="special">)</span> <span class="special">;</span>
|
||||
<span class="keyword">void</span> <span class="identifier">bar</span><span class="special">()</span>
|
||||
<span class="special">{</span>
|
||||
<span class="identifier">optional</span><span class="special"><</span><span class="keyword">bool</span><span class="special">></span> <span class="identifier">v</span> <span class="special">=</span> <span class="keyword">try</span><span class="special">();</span>
|
||||
|
||||
<span class="comment">// The following intended to pass the value of 'v' to foo():
|
||||
</span> <span class="identifier">foo</span><span class="special">(</span><span class="identifier">v</span><span class="special">);</span>
|
||||
<span class="comment">// But instead, the initialization state is passed
|
||||
</span> <span class="comment">// due to a typo: it should have been foo(*v).
|
||||
</span><span class="special">}</span>
|
||||
</pre>
|
||||
<p>
|
||||
The only implicit conversion is to <code class="computeroutput"><span class="keyword">bool</span></code>,
|
||||
and it is safe in the sense that typical integral promotions don't apply (i.e.
|
||||
if <code class="computeroutput"><span class="identifier">foo</span><span class="special">()</span></code>
|
||||
takes an <code class="computeroutput"><span class="keyword">int</span></code> instead, it won't
|
||||
compile).
|
||||
</p>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
<td align="right"><small>Copyright <20> 2003 -2007 Fernando Luis Cacciola Carballal</small></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="in_place_factories.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="exception_safety_guarantees.html"><img src="../images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@ -1,122 +0,0 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||||
<title>Acknowledgments</title>
|
||||
<link rel="stylesheet" href="../boostbook.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
|
||||
<link rel="start" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
|
||||
<link rel="up" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
|
||||
<link rel="prev" href="dependencies_and_portability.html" title="Dependencies
|
||||
and Portability">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%">
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../index.htm">Home</a></td>
|
||||
<td align="center"><a href="../libraries.html">Libraries</a></td>
|
||||
<td align="center"><a href="../../../people/people.htm">People</a></td>
|
||||
<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
|
||||
<td align="center"><a href="../../../more/index.htm">More</a></td>
|
||||
</table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="dependencies_and_portability.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a>
|
||||
</div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="boost_optional.acknowledgments"></a><a href="acknowledgments.html" title="Acknowledgments">Acknowledgments</a>
|
||||
</h2></div></div></div>
|
||||
<a name="boost_optional.acknowledgments.pre_formal_review"></a><h4>
|
||||
<a name="id2644860"></a>
|
||||
<a href="acknowledgments.html#boost_optional.acknowledgments.pre_formal_review">Pre-formal
|
||||
review</a>
|
||||
</h4>
|
||||
<div class="itemizedlist"><ul type="disc">
|
||||
<li>
|
||||
Peter Dimov suggested the name 'optional', and was the first to point out
|
||||
the need for aligned storage.
|
||||
</li>
|
||||
<li>
|
||||
Douglas Gregor developed 'type_with_alignment', and later Eric Friedman coded
|
||||
'aligned_storage', which are the core of the optional class implementation.
|
||||
</li>
|
||||
<li>
|
||||
Andrei Alexandrescu and Brian Parker also worked with aligned storage techniques
|
||||
and their work influenced the current implementation.
|
||||
</li>
|
||||
<li>
|
||||
Gennadiy Rozental made extensive and important comments which shaped the
|
||||
design.
|
||||
</li>
|
||||
<li>
|
||||
Vesa Karvonen and Douglas Gregor made quite useful comparisons between optional,
|
||||
variant and any; and made other relevant comments.
|
||||
</li>
|
||||
<li>
|
||||
Douglas Gregor and Peter Dimov commented on comparisons and evaluation in
|
||||
boolean contexts.
|
||||
</li>
|
||||
<li>
|
||||
Eric Friedman helped understand the issues involved with aligned storage,
|
||||
move/copy operations and exception safety.
|
||||
</li>
|
||||
<li>
|
||||
Many others have participated with useful comments: Aleksey Gurotov, Kevlin
|
||||
Henney, David Abrahams, and others I can't recall.
|
||||
</li>
|
||||
</ul></div>
|
||||
<a name="boost_optional.acknowledgments.post_formal_review"></a><h4>
|
||||
<a name="id2644931"></a>
|
||||
<a href="acknowledgments.html#boost_optional.acknowledgments.post_formal_review">Post-formal
|
||||
review</a>
|
||||
</h4>
|
||||
<div class="itemizedlist"><ul type="disc">
|
||||
<li>
|
||||
William Kempf carefully considered the originally proposed interface and
|
||||
suggested the new interface which is currently used. He also started and
|
||||
fueled the discussion about the analogy optional<>/smart pointer and
|
||||
about relational operators.
|
||||
</li>
|
||||
<li>
|
||||
Peter Dimov, Joel de Guzman, David Abrahams, Tanton Gibbs and Ian Hanson
|
||||
focused on the relational semantics of optional (originally undefined); concluding
|
||||
with the fact that the pointer-like interface doesn't make it a pointer so
|
||||
it shall have deep relational operators.
|
||||
</li>
|
||||
<li>
|
||||
Augustus Saunders also explored the different relational semantics between
|
||||
optional<> and a pointer and developed the OptionalPointee concept
|
||||
as an aid against potential conflicts on generic code.
|
||||
</li>
|
||||
<li>
|
||||
Joel de Guzman noticed that optional<> can be seen as an API on top
|
||||
of variant<T,nil_t>.
|
||||
</li>
|
||||
<li>
|
||||
Dave Gomboc explained the meaning and usage of the Haskell analog to optional<>:
|
||||
the Maybe type constructor (analogy originally pointed out by David Sankel).
|
||||
</li>
|
||||
<li>
|
||||
Other comments were posted by Vincent Finn, Anthony Williams, Ed Brey, Rob
|
||||
Stewart, and others.
|
||||
</li>
|
||||
<li>
|
||||
Joel de Guzman made the case for the support of references and helped with
|
||||
the proper semantics.
|
||||
</li>
|
||||
<li>
|
||||
Mat Marcus shown the virtues of a value-oriented interface, influencing the
|
||||
current design, and contributed the idea of "none".
|
||||
</li>
|
||||
</ul></div>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
<td align="right"><small>Copyright <20> 2003 -2007 Fernando Luis Cacciola Carballal</small></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="dependencies_and_portability.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@ -1,46 +0,0 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||||
<title>Dependencies
|
||||
and Portability</title>
|
||||
<link rel="stylesheet" href="../boostbook.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
|
||||
<link rel="start" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
|
||||
<link rel="up" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
|
||||
<link rel="prev" href="implementation_notes.html" title="Implementation Notes">
|
||||
<link rel="next" href="acknowledgments.html" title="Acknowledgments">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%">
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../index.htm">Home</a></td>
|
||||
<td align="center"><a href="../libraries.html">Libraries</a></td>
|
||||
<td align="center"><a href="../../../people/people.htm">People</a></td>
|
||||
<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
|
||||
<td align="center"><a href="../../../more/index.htm">More</a></td>
|
||||
</table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="implementation_notes.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="acknowledgments.html"><img src="../images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="boost_optional.dependencies_and_portability"></a><a href="dependencies_and_portability.html" title="Dependencies
|
||||
and Portability">Dependencies
|
||||
and Portability</a>
|
||||
</h2></div></div></div>
|
||||
<p>
|
||||
The implementation uses <code class="computeroutput"><span class="identifier">type_traits</span><span class="special">/</span><span class="identifier">alignment_of</span><span class="special">.</span><span class="identifier">hpp</span></code> and
|
||||
<code class="computeroutput"><span class="identifier">type_traits</span><span class="special">/</span><span class="identifier">type_with_alignment</span><span class="special">.</span><span class="identifier">hpp</span></code>
|
||||
</p>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
<td align="right"><small>Copyright <20> 2003 -2007 Fernando Luis Cacciola Carballal</small></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="implementation_notes.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="acknowledgments.html"><img src="../images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,415 +0,0 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||||
<title>Development</title>
|
||||
<link rel="stylesheet" href="../boostbook.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
|
||||
<link rel="start" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
|
||||
<link rel="up" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
|
||||
<link rel="prev" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
|
||||
<link rel="next" href="synopsis.html" title="Synopsis">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%">
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../index.htm">Home</a></td>
|
||||
<td align="center"><a href="../libraries.html">Libraries</a></td>
|
||||
<td align="center"><a href="../../../people/people.htm">People</a></td>
|
||||
<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
|
||||
<td align="center"><a href="../../../more/index.htm">More</a></td>
|
||||
</table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="../index.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="synopsis.html"><img src="../images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="boost_optional.development"></a><a href="development.html" title="Development">Development</a>
|
||||
</h2></div></div></div>
|
||||
<div class="toc"><dl>
|
||||
<dt><span class="section"><a href="development.html#boost_optional.development.the_models">The models</a></span></dt>
|
||||
<dt><span class="section"><a href="development.html#boost_optional.development.the_semantics">The semantics</a></span></dt>
|
||||
<dt><span class="section"><a href="development.html#boost_optional.development.the_interface">The Interface</a></span></dt>
|
||||
</dl></div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_optional.development.the_models"></a><a href="development.html#boost_optional.development.the_models" title="The models">The models</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
In C++, we can <span class="emphasis"><em>declare</em></span> an object (a variable) of type
|
||||
<code class="computeroutput"><span class="identifier">T</span></code>, and we can give this variable
|
||||
an <span class="emphasis"><em>initial value</em></span> (through an <span class="emphasis"><em>initializer</em></span>.
|
||||
(c.f. 8.5)). When a declaration includes a non-empty initializer (an initial
|
||||
value is given), it is said that the object has been initialized. If the
|
||||
declaration uses an empty initializer (no initial value is given), and neither
|
||||
default nor value initialization applies, it is said that the object is
|
||||
<span class="bold"><strong>uninitialized</strong></span>. Its actual value exist but
|
||||
has an <span class="emphasis"><em>indeterminate initial value</em></span> (c.f. 8.5.9). <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code> intends
|
||||
to formalize the notion of initialization (or lack of it) allowing a program
|
||||
to test whether an object has been initialized and stating that access to
|
||||
the value of an uninitialized object is undefined behavior. That is, when
|
||||
a variable is declared as <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code>
|
||||
and no initial value is given, the variable is <span class="emphasis"><em>formally</em></span>
|
||||
uninitialized. A formally uninitialized optional object has conceptually
|
||||
no value at all and this situation can be tested at runtime. It is formally
|
||||
<span class="emphasis"><em>undefined behavior</em></span> to try to access the value of an
|
||||
uninitialized optional. An uninitialized optional can be assigned a value,
|
||||
in which case its initialization state changes to initialized. Furthermore,
|
||||
given the formal treatment of initialization states in optional objects,
|
||||
it is even possible to reset an optional to <span class="emphasis"><em>uninitialized</em></span>.
|
||||
</p>
|
||||
<p>
|
||||
In C++ there is no formal notion of uninitialized objects, which means that
|
||||
objects always have an initial value even if indeterminate. As discussed
|
||||
on the previous section, this has a drawback because you need additional
|
||||
information to tell if an object has been effectively initialized. One of
|
||||
the typical ways in which this has been historically dealt with is via a
|
||||
special value: <code class="computeroutput"><span class="identifier">EOF</span></code>, <code class="computeroutput"><span class="identifier">npos</span></code>, -1, etc... This is equivalent to
|
||||
adding the special value to the set of possible values of a given type. This
|
||||
super set of <code class="computeroutput"><span class="identifier">T</span></code> plus some
|
||||
<span class="emphasis"><em>nil_t</em></span>—were <code class="computeroutput"><span class="identifier">nil_t</span></code>
|
||||
is some stateless POD-can be modeled in modern languages as a <span class="bold"><strong>discriminated
|
||||
union</strong></span> of T and nil_t. Discriminated unions are often called <span class="emphasis"><em>variants</em></span>.
|
||||
A variant has a <span class="emphasis"><em>current type</em></span>, which in our case is either
|
||||
<code class="computeroutput"><span class="identifier">T</span></code> or <code class="computeroutput"><span class="identifier">nil_t</span></code>.
|
||||
Using the <a href="../../../../variant/index.html" target="_top">Boost.Variant</a>
|
||||
library, this model can be implemented in terms of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">variant</span><span class="special"><</span><span class="identifier">T</span><span class="special">,</span><span class="identifier">nil_t</span><span class="special">></span></code>.
|
||||
There is precedent for a discriminated union as a model for an optional value:
|
||||
the <a href="http://www.haskell.org/" target="_top">Haskell</a> <span class="bold"><strong>Maybe</strong></span>
|
||||
built-in type constructor. Thus, a discriminated union <code class="computeroutput"><span class="identifier">T</span><span class="special">+</span><span class="identifier">nil_t</span></code>
|
||||
serves as a conceptual foundation.
|
||||
</p>
|
||||
<p>
|
||||
A <code class="computeroutput"><span class="identifier">variant</span><span class="special"><</span><span class="identifier">T</span><span class="special">,</span><span class="identifier">nil_t</span><span class="special">></span></code> follows naturally from the traditional
|
||||
idiom of extending the range of possible values adding an additional sentinel
|
||||
value with the special meaning of <span class="emphasis"><em>Nothing</em></span>. However,
|
||||
this additional <span class="emphasis"><em>Nothing</em></span> value is largely irrelevant
|
||||
for our purpose since our goal is to formalize the notion of uninitialized
|
||||
objects and, while a special extended value can be used to convey that meaning,
|
||||
it is not strictly necessary in order to do so.
|
||||
</p>
|
||||
<p>
|
||||
The observation made in the last paragraph about the irrelevant nature of
|
||||
the additional <code class="computeroutput"><span class="identifier">nil_t</span></code> with
|
||||
respect to <span class="underline">purpose</span> of <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code> suggests
|
||||
an alternative model: a <span class="emphasis"><em>container</em></span> that either has a
|
||||
value of <code class="computeroutput"><span class="identifier">T</span></code> or nothing.
|
||||
</p>
|
||||
<p>
|
||||
As of this writing I don't know of any precedence for a variable-size fixed-capacity
|
||||
(of 1) stack-based container model for optional values, yet I believe this
|
||||
is the consequence of the lack of practical implementations of such a container
|
||||
rather than an inherent shortcoming of the container model.
|
||||
</p>
|
||||
<p>
|
||||
In any event, both the discriminated-union or the single-element container
|
||||
models serve as a conceptual ground for a class representing optional—i.e.
|
||||
possibly uninitialized—objects. For instance, these models show the <span class="emphasis"><em>exact</em></span>
|
||||
semantics required for a wrapper of optional values:
|
||||
</p>
|
||||
<p>
|
||||
Discriminated-union:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul type="disc">
|
||||
<li>
|
||||
<span class="bold"><strong>deep-copy</strong></span> semantics: copies of the variant
|
||||
implies copies of the value.
|
||||
</li>
|
||||
<li>
|
||||
<span class="bold"><strong>deep-relational</strong></span> semantics: comparisons
|
||||
between variants matches both current types and values
|
||||
</li>
|
||||
<li>
|
||||
If the variant's current type is <code class="computeroutput"><span class="identifier">T</span></code>,
|
||||
it is modeling an <span class="emphasis"><em>initialized</em></span> optional.
|
||||
</li>
|
||||
<li>
|
||||
If the variant's current type is not <code class="computeroutput"><span class="identifier">T</span></code>,
|
||||
it is modeling an <span class="emphasis"><em>uninitialized</em></span> optional.
|
||||
</li>
|
||||
<li>
|
||||
Testing if the variant's current type is <code class="computeroutput"><span class="identifier">T</span></code>
|
||||
models testing if the optional is initialized
|
||||
</li>
|
||||
<li>
|
||||
Trying to extract a <code class="computeroutput"><span class="identifier">T</span></code> from
|
||||
a variant when its current type is not <code class="computeroutput"><span class="identifier">T</span></code>,
|
||||
models the undefined behavior of trying to access the value of an uninitialized
|
||||
optional
|
||||
</li>
|
||||
</ul></div>
|
||||
<p>
|
||||
Single-element container:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul type="disc">
|
||||
<li>
|
||||
<span class="bold"><strong>deep-copy</strong></span> semantics: copies of the container
|
||||
implies copies of the value.
|
||||
</li>
|
||||
<li>
|
||||
<span class="bold"><strong>deep-relational</strong></span> semantics: comparisons
|
||||
between containers compare container size and if match, contained value
|
||||
</li>
|
||||
<li>
|
||||
If the container is not empty (contains an object of type <code class="computeroutput"><span class="identifier">T</span></code>), it is modeling an <span class="emphasis"><em>initialized</em></span>
|
||||
optional.
|
||||
</li>
|
||||
<li>
|
||||
If the container is empty, it is modeling an <span class="emphasis"><em>uninitialized</em></span>
|
||||
optional.
|
||||
</li>
|
||||
<li>
|
||||
Testing if the container is empty models testing if the optional is initialized
|
||||
</li>
|
||||
<li>
|
||||
Trying to extract a <code class="computeroutput"><span class="identifier">T</span></code> from
|
||||
an empty container models the undefined behavior of trying to access the
|
||||
value of an uninitialized optional
|
||||
</li>
|
||||
</ul></div>
|
||||
</div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_optional.development.the_semantics"></a><a href="development.html#boost_optional.development.the_semantics" title="The semantics">The semantics</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
Objects of type <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code>
|
||||
are intended to be used in places where objects of type <code class="computeroutput"><span class="identifier">T</span></code>
|
||||
would but which might be uninitialized. Hence, <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code>'s
|
||||
purpose is to formalize the additional possibly uninitialized state. From
|
||||
the perspective of this role, <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code>
|
||||
can have the same operational semantics of <code class="computeroutput"><span class="identifier">T</span></code>
|
||||
plus the additional semantics corresponding to this special state. As such,
|
||||
<code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code> could
|
||||
be thought of as a <span class="emphasis"><em>supertype</em></span> of <code class="computeroutput"><span class="identifier">T</span></code>.
|
||||
Of course, we can't do that in C++, so we need to compose the desired semantics
|
||||
using a different mechanism. Doing it the other way around, that is, making
|
||||
<code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code> a
|
||||
<span class="emphasis"><em>subtype</em></span> of <code class="computeroutput"><span class="identifier">T</span></code>
|
||||
is not only conceptually wrong but also impractical: it is not allowed to
|
||||
derive from a non-class type, such as a built-in type.
|
||||
</p>
|
||||
<p>
|
||||
We can draw from the purpose of <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code>
|
||||
the required basic semantics:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul type="disc">
|
||||
<li>
|
||||
<span class="bold"><strong>Default Construction:</strong></span> To introduce a formally
|
||||
uninitialized wrapped object.
|
||||
</li>
|
||||
<li>
|
||||
<span class="bold"><strong>Direct Value Construction via copy:</strong></span> To
|
||||
introduce a formally initialized wrapped object whose value is obtained
|
||||
as a copy of some object.
|
||||
</li>
|
||||
<li>
|
||||
<span class="bold"><strong>Deep Copy Construction:</strong></span> To obtain a new
|
||||
yet equivalent wrapped object.
|
||||
</li>
|
||||
<li>
|
||||
<span class="bold"><strong>Direct Value Assignment (upon initialized):</strong></span>
|
||||
To assign a value to the wrapped object.
|
||||
</li>
|
||||
<li>
|
||||
<span class="bold"><strong>Direct Value Assignment (upon uninitialized):</strong></span>
|
||||
To initialize the wrapped object with a value obtained as a copy of some
|
||||
object.
|
||||
</li>
|
||||
<li>
|
||||
<span class="bold"><strong>Assignment (upon initialized):</strong></span> To assign
|
||||
to the wrapped object the value of another wrapped object.
|
||||
</li>
|
||||
<li>
|
||||
<span class="bold"><strong>Assignment (upon uninitialized):</strong></span> To initialize
|
||||
the wrapped object with value of another wrapped object.
|
||||
</li>
|
||||
<li>
|
||||
<span class="bold"><strong>Deep Relational Operations (when supported by the
|
||||
type T):</strong></span> To compare wrapped object values taking into account
|
||||
the presence of uninitialized states.
|
||||
</li>
|
||||
<li>
|
||||
<span class="bold"><strong>Value access:</strong></span> To unwrap the wrapped object.
|
||||
</li>
|
||||
<li>
|
||||
<span class="bold"><strong>Initialization state query:</strong></span> To determine
|
||||
if the object is formally initialized or not.
|
||||
</li>
|
||||
<li>
|
||||
<span class="bold"><strong>Swap:</strong></span> To exchange wrapped objects. (with
|
||||
whatever exception safety guarantees are provided by <code class="computeroutput"><span class="identifier">T</span></code>'s
|
||||
swap).
|
||||
</li>
|
||||
<li>
|
||||
<span class="bold"><strong>De-initialization:</strong></span> To release the wrapped
|
||||
object (if any) and leave the wrapper in the uninitialized state.
|
||||
</li>
|
||||
</ul></div>
|
||||
<p>
|
||||
Additional operations are useful, such as converting constructors and converting
|
||||
assignments, in-place construction and assignment, and safe value access
|
||||
via a pointer to the wrapped object or null.
|
||||
</p>
|
||||
</div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_optional.development.the_interface"></a><a href="development.html#boost_optional.development.the_interface" title="The Interface">The Interface</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
Since the purpose of optional is to allow us to use objects with a formal
|
||||
uninitialized additional state, the interface could try to follow the interface
|
||||
of the underlying <code class="computeroutput"><span class="identifier">T</span></code> type
|
||||
as much as possible. In order to choose the proper degree of adoption of
|
||||
the native <code class="computeroutput"><span class="identifier">T</span></code> interface, the
|
||||
following must be noted: Even if all the operations supported by an instance
|
||||
of type <code class="computeroutput"><span class="identifier">T</span></code> are defined for
|
||||
the entire range of values for such a type, an <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code>
|
||||
extends such a set of values with a new value for which most (otherwise valid)
|
||||
operations are not defined in terms of <code class="computeroutput"><span class="identifier">T</span></code>.
|
||||
</p>
|
||||
<p>
|
||||
Furthermore, since <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code>
|
||||
itself is merely a <code class="computeroutput"><span class="identifier">T</span></code> wrapper
|
||||
(modeling a <code class="computeroutput"><span class="identifier">T</span></code> supertype),
|
||||
any attempt to define such operations upon uninitialized optionals will be
|
||||
totally artificial w.r.t. <code class="computeroutput"><span class="identifier">T</span></code>.
|
||||
</p>
|
||||
<p>
|
||||
This library chooses an interface which follows from <code class="computeroutput"><span class="identifier">T</span></code>'s
|
||||
interface only for those operations which are well defined (w.r.t the type
|
||||
<code class="computeroutput"><span class="identifier">T</span></code>) even if any of the operands
|
||||
are uninitialized. These operations include: construction, copy-construction,
|
||||
assignment, swap and relational operations.
|
||||
</p>
|
||||
<p>
|
||||
For the value access operations, which are undefined (w.r.t the type <code class="computeroutput"><span class="identifier">T</span></code>) when the operand is uninitialized, a
|
||||
different interface is chosen (which will be explained next).
|
||||
</p>
|
||||
<p>
|
||||
Also, the presence of the possibly uninitialized state requires additional
|
||||
operations not provided by <code class="computeroutput"><span class="identifier">T</span></code>
|
||||
itself which are supported by a special interface.
|
||||
</p>
|
||||
<a name="boost_optional.development.the_interface.lexically_hinted_value_access_in_the_presence_of_possibly_untitialized_optional_objects__the_operators___and___gt_"></a><h5>
|
||||
<a name="id2615242"></a>
|
||||
<a href="development.html#boost_optional.development.the_interface.lexically_hinted_value_access_in_the_presence_of_possibly_untitialized_optional_objects__the_operators___and___gt_">Lexically-hinted
|
||||
Value Access in the presence of possibly untitialized optional objects: The
|
||||
operators * and -></a>
|
||||
</h5>
|
||||
<p>
|
||||
A relevant feature of a pointer is that it can have a <span class="bold"><strong>null
|
||||
pointer value</strong></span>. This is a <span class="emphasis"><em>special</em></span> value which
|
||||
is used to indicate that the pointer is not referring to any object at all.
|
||||
In other words, null pointer values convey the notion of inexistent objects.
|
||||
</p>
|
||||
<p>
|
||||
This meaning of the null pointer value allowed pointers to became a <span class="emphasis"><em>de
|
||||
facto</em></span> standard for handling optional objects because all you have
|
||||
to do to refer to a value which you don't really have is to use a null pointer
|
||||
value of the appropriate type. Pointers have been used for decades—from
|
||||
the days of C APIs to modern C++ libraries—to <span class="emphasis"><em>refer</em></span>
|
||||
to optional (that is, possibly inexistent) objects; particularly as optional
|
||||
arguments to a function, but also quite often as optional data members.
|
||||
</p>
|
||||
<p>
|
||||
The possible presence of a null pointer value makes the operations that access
|
||||
the pointee's value possibly undefined, therefore, expressions which use
|
||||
dereference and access operators, such as: <code class="computeroutput"><span class="special">(</span>
|
||||
<span class="special">*</span><span class="identifier">p</span> <span class="special">=</span> <span class="number">2</span> <span class="special">)</span></code>
|
||||
and <code class="computeroutput"><span class="special">(</span> <span class="identifier">p</span><span class="special">-></span><span class="identifier">foo</span><span class="special">()</span> <span class="special">)</span></code>, implicitly
|
||||
convey the notion of optionality, and this information is tied to the <span class="emphasis"><em>syntax</em></span>
|
||||
of the expressions. That is, the presence of operators <code class="computeroutput"><span class="special">*</span></code>
|
||||
and <code class="computeroutput"><span class="special">-></span></code> tell by themselves
|
||||
—without any additional context— that the expression will be undefined
|
||||
unless the implied pointee actually exist.
|
||||
</p>
|
||||
<p>
|
||||
Such a <span class="emphasis"><em>de facto</em></span> idiom for referring to optional objects
|
||||
can be formalized in the form of a concept: the <a href="../../../../utility/OptionalPointee.html" target="_top">OptionalPointee</a>
|
||||
concept. This concept captures the syntactic usage of operators <code class="computeroutput"><span class="special">*</span></code>, <code class="computeroutput"><span class="special">-></span></code>
|
||||
and conversion to <code class="computeroutput"><span class="keyword">bool</span></code> to convey
|
||||
the notion of optionality.
|
||||
</p>
|
||||
<p>
|
||||
However, pointers are good to <span class="underline">refer</span>
|
||||
to optional objects, but not particularly good to handle the optional objects
|
||||
in all other respects, such as initializing or moving/copying them. The problem
|
||||
resides in the shallow-copy of pointer semantics: if you need to effectively
|
||||
move or copy the object, pointers alone are not enough. The problem is that
|
||||
copies of pointers do not imply copies of pointees. For example, as was discussed
|
||||
in the motivation, pointers alone cannot be used to return optional objects
|
||||
from a function because the object must move outside from the function and
|
||||
into the caller's context.
|
||||
</p>
|
||||
<p>
|
||||
A solution to the shallow-copy problem that is often used is to resort to
|
||||
dynamic allocation and use a smart pointer to automatically handle the details
|
||||
of this. For example, if a function is to optionally return an object <code class="computeroutput"><span class="identifier">X</span></code>, it can use <code class="computeroutput"><span class="identifier">shared_ptr</span><span class="special"><</span><span class="identifier">X</span><span class="special">></span></code>
|
||||
as the return value. However, this requires dynamic allocation of <code class="computeroutput"><span class="identifier">X</span></code>. If <code class="computeroutput"><span class="identifier">X</span></code>
|
||||
is a built-in or small POD, this technique is very poor in terms of required
|
||||
resources. Optional objects are essentially values so it is very convenient
|
||||
to be able to use automatic storage and deep-copy semantics to manipulate
|
||||
optional values just as we do with ordinary values. Pointers do not have
|
||||
this semantics, so are inappropriate for the initialization and transport
|
||||
of optional values, yet are quite convenient for handling the access to the
|
||||
possible undefined value because of the idiomatic aid present in the <a href="../../../../utility/OptionalPointee.html" target="_top">OptionalPointee</a> concept
|
||||
incarnated by pointers.
|
||||
</p>
|
||||
<a name="boost_optional.development.the_interface.optional_lt_t_gt__as_a_model_of_optionalpointee"></a><h5>
|
||||
<a name="id2615580"></a>
|
||||
<a href="development.html#boost_optional.development.the_interface.optional_lt_t_gt__as_a_model_of_optionalpointee">Optional<T>
|
||||
as a model of OptionalPointee</a>
|
||||
</h5>
|
||||
<p>
|
||||
For value access operations <code class="computeroutput"><span class="identifier">optional</span><span class="special"><></span></code> uses operators <code class="computeroutput"><span class="special">*</span></code>
|
||||
and <code class="computeroutput"><span class="special">-></span></code> to lexically warn
|
||||
about the possibly uninitialized state appealing to the familiar pointer
|
||||
semantics w.r.t. to null pointers.
|
||||
</p>
|
||||
<div class="warning"><table border="0" summary="Warning">
|
||||
<tr>
|
||||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../images/warning.png"></td>
|
||||
<th align="left">Warning</th>
|
||||
</tr>
|
||||
<tr><td align="left" valign="top">
|
||||
<p>
|
||||
</p>
|
||||
<p>
|
||||
However, it is particularly important to note that <code class="computeroutput"><span class="identifier">optional</span><span class="special"><></span></code> objects are not pointers. <span class="underline"><code class="computeroutput"><span class="identifier">optional</span><span class="special"><></span></code> is not, and does not model, a
|
||||
pointer</span>.
|
||||
</p>
|
||||
<p>
|
||||
</p>
|
||||
</td></tr>
|
||||
</table></div>
|
||||
<p>
|
||||
For instance, <code class="computeroutput"><span class="identifier">optional</span><span class="special"><></span></code>
|
||||
does not have shallow-copy so does not alias: two different optionals never
|
||||
refer to the <span class="emphasis"><em>same</em></span> value unless <code class="computeroutput"><span class="identifier">T</span></code>
|
||||
itself is a reference (but may have <span class="emphasis"><em>equivalent</em></span> values).
|
||||
The difference between an <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code>
|
||||
and a pointer must be kept in mind, particularly because the semantics of
|
||||
relational operators are different: since <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code>
|
||||
is a value-wrapper, relational operators are deep: they compare optional
|
||||
values; but relational operators for pointers are shallow: they do not compare
|
||||
pointee values. As a result, you might be able to replace <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code>
|
||||
by <code class="computeroutput"><span class="identifier">T</span><span class="special">*</span></code>
|
||||
on some situations but not always. Specifically, on generic code written
|
||||
for both, you cannot use relational operators directly, and must use the
|
||||
template functions <a href="../../../../utility/OptionalPointee.html#equal" target="_top"><code class="computeroutput"><span class="identifier">equal_pointees</span><span class="special">()</span></code></a>
|
||||
and <a href="../../../../utility/OptionalPointee.html#less" target="_top"><code class="computeroutput"><span class="identifier">less_pointees</span><span class="special">()</span></code></a>
|
||||
instead.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
<td align="right"><small>Copyright <20> 2003 -2007 Fernando Luis Cacciola Carballal</small></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="../index.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="synopsis.html"><img src="../images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@ -1,151 +0,0 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||||
<title>Examples</title>
|
||||
<link rel="stylesheet" href="../boostbook.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
|
||||
<link rel="start" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
|
||||
<link rel="up" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
|
||||
<link rel="prev" href="detailed_semantics.html" title="Detailed Semantics">
|
||||
<link rel="next" href="optional_references.html" title="Optional references">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%">
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../index.htm">Home</a></td>
|
||||
<td align="center"><a href="../libraries.html">Libraries</a></td>
|
||||
<td align="center"><a href="../../../people/people.htm">People</a></td>
|
||||
<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
|
||||
<td align="center"><a href="../../../more/index.htm">More</a></td>
|
||||
</table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="detailed_semantics.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="optional_references.html"><img src="../images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="boost_optional.examples"></a><a href="examples.html" title="Examples">Examples</a>
|
||||
</h2></div></div></div>
|
||||
<div class="toc"><dl>
|
||||
<dt><span class="section"><a href="examples.html#boost_optional.examples.optional_return_values">Optional
|
||||
return values</a></span></dt>
|
||||
<dt><span class="section"><a href="examples.html#boost_optional.examples.optional_local_variables">Optional
|
||||
local variables</a></span></dt>
|
||||
<dt><span class="section"><a href="examples.html#boost_optional.examples.optional_data_members">Optional
|
||||
data members</a></span></dt>
|
||||
<dt><span class="section"><a href="examples.html#boost_optional.examples.bypassing_expensive_unnecessary_default_construction">Bypassing
|
||||
expensive unnecessary default construction</a></span></dt>
|
||||
</dl></div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_optional.examples.optional_return_values"></a><a href="examples.html#boost_optional.examples.optional_return_values" title="Optional
|
||||
return values">Optional
|
||||
return values</a>
|
||||
</h3></div></div></div>
|
||||
<pre class="programlisting">
|
||||
<span class="identifier">optional</span><span class="special"><</span><span class="keyword">char</span><span class="special">></span> <span class="identifier">get_async_input</span><span class="special">()</span>
|
||||
<span class="special">{</span>
|
||||
<span class="keyword">if</span> <span class="special">(</span> <span class="special">!</span><span class="identifier">queue</span><span class="special">.</span><span class="identifier">empty</span><span class="special">()</span> <span class="special">)</span>
|
||||
<span class="keyword">return</span> <span class="identifier">optional</span><span class="special"><</span><span class="keyword">char</span><span class="special">>(</span><span class="identifier">queue</span><span class="special">.</span><span class="identifier">top</span><span class="special">());</span>
|
||||
<span class="keyword">else</span> <span class="keyword">return</span> <span class="identifier">optional</span><span class="special"><</span><span class="keyword">char</span><span class="special">>();</span> <span class="comment">// uninitialized
|
||||
</span><span class="special">}</span>
|
||||
|
||||
<span class="keyword">void</span> <span class="identifier">receive_async_message</span><span class="special">()</span>
|
||||
<span class="special">{</span>
|
||||
<span class="identifier">optional</span><span class="special"><</span><span class="keyword">char</span><span class="special">></span> <span class="identifier">rcv</span> <span class="special">;</span>
|
||||
<span class="comment">// The safe boolean conversion from 'rcv' is used here.
|
||||
</span> <span class="keyword">while</span> <span class="special">(</span> <span class="special">(</span><span class="identifier">rcv</span> <span class="special">=</span> <span class="identifier">get_async_input</span><span class="special">())</span> <span class="special">&&</span> <span class="special">!</span><span class="identifier">timeout</span><span class="special">()</span> <span class="special">)</span>
|
||||
<span class="identifier">output</span><span class="special">(*</span><span class="identifier">rcv</span><span class="special">);</span>
|
||||
<span class="special">}</span>
|
||||
</pre>
|
||||
</div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_optional.examples.optional_local_variables"></a><a href="examples.html#boost_optional.examples.optional_local_variables" title="Optional
|
||||
local variables">Optional
|
||||
local variables</a>
|
||||
</h3></div></div></div>
|
||||
<pre class="programlisting">
|
||||
<span class="identifier">optional</span><span class="special"><</span><span class="identifier">string</span><span class="special">></span> <span class="identifier">name</span> <span class="special">;</span>
|
||||
<span class="keyword">if</span> <span class="special">(</span> <span class="identifier">database</span><span class="special">.</span><span class="identifier">open</span><span class="special">()</span> <span class="special">)</span>
|
||||
<span class="special">{</span>
|
||||
<span class="identifier">name</span><span class="special">.</span><span class="identifier">reset</span> <span class="special">(</span> <span class="identifier">database</span><span class="special">.</span><span class="identifier">lookup</span><span class="special">(</span><span class="identifier">employer_name</span><span class="special">)</span> <span class="special">)</span> <span class="special">;</span>
|
||||
<span class="special">}</span>
|
||||
<span class="keyword">else</span>
|
||||
<span class="special">{</span>
|
||||
<span class="keyword">if</span> <span class="special">(</span> <span class="identifier">can_ask_user</span> <span class="special">)</span>
|
||||
<span class="identifier">name</span><span class="special">.</span><span class="identifier">reset</span> <span class="special">(</span> <span class="identifier">user</span><span class="special">.</span><span class="identifier">ask</span><span class="special">(</span><span class="identifier">employer_name</span><span class="special">)</span> <span class="special">)</span> <span class="special">;</span>
|
||||
<span class="special">}</span>
|
||||
|
||||
<span class="keyword">if</span> <span class="special">(</span> <span class="identifier">name</span> <span class="special">)</span>
|
||||
<span class="identifier">print</span><span class="special">(*</span><span class="identifier">name</span><span class="special">);</span>
|
||||
<span class="keyword">else</span> <span class="identifier">print</span><span class="special">(</span><span class="string">"employer's name not found!"</span><span class="special">);</span>
|
||||
</pre>
|
||||
</div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_optional.examples.optional_data_members"></a><a href="examples.html#boost_optional.examples.optional_data_members" title="Optional
|
||||
data members">Optional
|
||||
data members</a>
|
||||
</h3></div></div></div>
|
||||
<pre class="programlisting">
|
||||
<span class="keyword">class</span> <span class="identifier">figure</span>
|
||||
<span class="special">{</span>
|
||||
<span class="keyword">public</span><span class="special">:</span>
|
||||
|
||||
<span class="identifier">figure</span><span class="special">()</span>
|
||||
<span class="special">{</span>
|
||||
<span class="comment">// data member 'm_clipping_rect' is uninitialized at this point.
|
||||
</span> <span class="special">}</span>
|
||||
|
||||
<span class="keyword">void</span> <span class="identifier">clip_in_rect</span> <span class="special">(</span> <span class="identifier">rect</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rect</span> <span class="special">)</span>
|
||||
<span class="special">{</span>
|
||||
<span class="special">....</span>
|
||||
<span class="identifier">m_clipping_rect</span><span class="special">.</span><span class="identifier">reset</span> <span class="special">(</span> <span class="identifier">rect</span> <span class="special">)</span> <span class="special">;</span> <span class="comment">// initialized here.
|
||||
</span> <span class="special">}</span>
|
||||
|
||||
<span class="keyword">void</span> <span class="identifier">draw</span> <span class="special">(</span> <span class="identifier">canvas</span><span class="special">&</span> <span class="identifier">cvs</span> <span class="special">)</span>
|
||||
<span class="special">{</span>
|
||||
<span class="keyword">if</span> <span class="special">(</span> <span class="identifier">m_clipping_rect</span> <span class="special">)</span>
|
||||
<span class="identifier">do_clipping</span><span class="special">(*</span><span class="identifier">m_clipping_rect</span><span class="special">);</span>
|
||||
|
||||
<span class="identifier">cvs</span><span class="special">.</span><span class="identifier">drawXXX</span><span class="special">(..);</span>
|
||||
<span class="special">}</span>
|
||||
|
||||
<span class="comment">// this can return NULL.
|
||||
</span> <span class="identifier">rect</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">get_clipping_rect</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">get_pointer</span><span class="special">(</span><span class="identifier">m_clipping_rect</span><span class="special">);</span> <span class="special">}</span>
|
||||
|
||||
<span class="keyword">private</span> <span class="special">:</span>
|
||||
|
||||
<span class="identifier">optional</span><span class="special"><</span><span class="identifier">rect</span><span class="special">></span> <span class="identifier">m_clipping_rect</span> <span class="special">;</span>
|
||||
|
||||
<span class="special">};</span>
|
||||
</pre>
|
||||
</div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="boost_optional.examples.bypassing_expensive_unnecessary_default_construction"></a><a href="examples.html#boost_optional.examples.bypassing_expensive_unnecessary_default_construction" title="Bypassing
|
||||
expensive unnecessary default construction">Bypassing
|
||||
expensive unnecessary default construction</a>
|
||||
</h3></div></div></div>
|
||||
<pre class="programlisting">
|
||||
<span class="keyword">class</span> <span class="identifier">ExpensiveCtor</span> <span class="special">{</span> <span class="special">...</span> <span class="special">}</span> <span class="special">;</span>
|
||||
<span class="keyword">class</span> <span class="identifier">Fred</span>
|
||||
<span class="special">{</span>
|
||||
<span class="identifier">Fred</span><span class="special">()</span> <span class="special">:</span> <span class="identifier">mLargeVector</span><span class="special">(</span><span class="number">10000</span><span class="special">)</span> <span class="special">{}</span>
|
||||
|
||||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">ExpensiveCtor</span><span class="special">></span> <span class="special">></span> <span class="identifier">mLargeVector</span> <span class="special">;</span>
|
||||
<span class="special">}</span> <span class="special">;</span>
|
||||
</pre>
|
||||
</div>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
<td align="right"><small>Copyright <20> 2003 -2007 Fernando Luis Cacciola Carballal</small></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="detailed_semantics.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="optional_references.html"><img src="../images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@ -1,140 +0,0 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||||
<title>Exception Safety
|
||||
Guarantees</title>
|
||||
<link rel="stylesheet" href="../boostbook.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
|
||||
<link rel="start" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
|
||||
<link rel="up" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
|
||||
<link rel="prev" href="a_note_about_optional_bool_.html" title="A note about
|
||||
optional<bool>">
|
||||
<link rel="next" href="type_requirements.html" title="Type requirements">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%">
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../index.htm">Home</a></td>
|
||||
<td align="center"><a href="../libraries.html">Libraries</a></td>
|
||||
<td align="center"><a href="../../../people/people.htm">People</a></td>
|
||||
<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
|
||||
<td align="center"><a href="../../../more/index.htm">More</a></td>
|
||||
</table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="a_note_about_optional_bool_.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="type_requirements.html"><img src="../images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="boost_optional.exception_safety_guarantees"></a><a href="exception_safety_guarantees.html" title="Exception Safety
|
||||
Guarantees">Exception Safety
|
||||
Guarantees</a>
|
||||
</h2></div></div></div>
|
||||
<p>
|
||||
Because of the current implementation (see <a href="../index.html#optional_implementation_notes">Implementation
|
||||
Notes</a>), all of the assignment methods:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul type="disc">
|
||||
<li><code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="keyword">operator</span><span class="special">=</span> <span class="special">(</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span>
|
||||
<span class="keyword">const</span><span class="special">&</span>
|
||||
<span class="special">)</span></code></li>
|
||||
<li><code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="keyword">operator</span><span class="special">=</span> <span class="special">(</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="special">)</span></code></li>
|
||||
<li><code class="computeroutput"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">U</span><span class="special">></span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="keyword">operator</span><span class="special">=</span> <span class="special">(</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">U</span><span class="special">></span>
|
||||
<span class="keyword">const</span><span class="special">&</span>
|
||||
<span class="special">)</span></code></li>
|
||||
<li><code class="computeroutput"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">InPlaceFactory</span><span class="special">></span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="keyword">operator</span><span class="special">=</span> <span class="special">(</span> <span class="identifier">InPlaceFactory</span>
|
||||
<span class="keyword">const</span><span class="special">&</span>
|
||||
<span class="special">)</span></code></li>
|
||||
<li><code class="computeroutput"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">TypedInPlaceFactory</span><span class="special">></span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="keyword">operator</span><span class="special">=</span> <span class="special">(</span> <span class="identifier">TypedInPlaceFactory</span>
|
||||
<span class="keyword">const</span><span class="special">&</span>
|
||||
<span class="special">)</span> </code></li>
|
||||
<li><code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">>:::</span><span class="identifier">reset</span> <span class="special">(</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&)</span></code></li>
|
||||
</ul></div>
|
||||
<p>
|
||||
Can only <span class="emphasis"><em>guarantee</em></span> the <span class="underline">basic
|
||||
exception safety</span>: The lvalue optional is left <span class="underline">uninitialized</span>
|
||||
if an exception is thrown (any previous value is <span class="emphasis"><em>first</em></span>
|
||||
destroyed using <code class="computeroutput"><span class="identifier">T</span><span class="special">::~</span><span class="identifier">T</span><span class="special">()</span></code>)
|
||||
</p>
|
||||
<p>
|
||||
On the other hand, the <span class="emphasis"><em>uninitializing</em></span> methods:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul type="disc">
|
||||
<li><code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="keyword">operator</span><span class="special">=</span> <span class="special">(</span> <span class="identifier">detail</span><span class="special">::</span><span class="identifier">none_t</span> <span class="special">)</span></code></li>
|
||||
<li><code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">reset</span><span class="special">()</span></code></li>
|
||||
</ul></div>
|
||||
<p>
|
||||
Provide the no-throw guarantee (assuming a no-throw <code class="computeroutput"><span class="identifier">T</span><span class="special">::~</span><span class="identifier">T</span><span class="special">()</span></code>)
|
||||
</p>
|
||||
<p>
|
||||
However, since <code class="computeroutput"><span class="identifier">optional</span><span class="special"><></span></code>
|
||||
itself doesn't throw any exceptions, the only source for exceptions here are
|
||||
<code class="computeroutput"><span class="identifier">T</span></code>'s constructor, so if you
|
||||
know the exception guarantees for <code class="computeroutput"><span class="identifier">T</span><span class="special">::</span><span class="identifier">T</span> <span class="special">(</span>
|
||||
<span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="special">)</span></code>, you
|
||||
know that <code class="computeroutput"><span class="identifier">optional</span></code>'s assignment
|
||||
and reset has the same guarantees.
|
||||
</p>
|
||||
<pre class="programlisting">
|
||||
<span class="comment">//
|
||||
</span><span class="comment">// Case 1: Exception thrown during assignment.
|
||||
</span><span class="comment">//
|
||||
</span><span class="identifier">T</span> <span class="identifier">v0</span><span class="special">(</span><span class="number">123</span><span class="special">);</span>
|
||||
<span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="identifier">opt0</span><span class="special">(</span><span class="identifier">v0</span><span class="special">);</span>
|
||||
<span class="keyword">try</span>
|
||||
<span class="special">{</span>
|
||||
<span class="identifier">T</span> <span class="identifier">v1</span><span class="special">(</span><span class="number">456</span><span class="special">);</span>
|
||||
<span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="identifier">opt1</span><span class="special">(</span><span class="identifier">v1</span><span class="special">);</span>
|
||||
<span class="identifier">opt0</span> <span class="special">=</span> <span class="identifier">opt1</span> <span class="special">;</span>
|
||||
|
||||
<span class="comment">// If no exception was thrown, assignment succeeded.
|
||||
</span> <span class="identifier">assert</span><span class="special">(</span> <span class="special">*</span><span class="identifier">opt0</span> <span class="special">==</span> <span class="identifier">v1</span> <span class="special">)</span> <span class="special">;</span>
|
||||
<span class="special">}</span>
|
||||
<span class="keyword">catch</span><span class="special">(...)</span>
|
||||
<span class="special">{</span>
|
||||
<span class="comment">// If any exception was thrown, 'opt0' is reset to uninitialized.
|
||||
</span> <span class="identifier">assert</span><span class="special">(</span> <span class="special">!</span><span class="identifier">opt0</span> <span class="special">)</span> <span class="special">;</span>
|
||||
<span class="special">}</span>
|
||||
|
||||
<span class="comment">//
|
||||
</span><span class="comment">// Case 2: Exception thrown during reset(v)
|
||||
</span><span class="comment">//
|
||||
</span><span class="identifier">T</span> <span class="identifier">v0</span><span class="special">(</span><span class="number">123</span><span class="special">);</span>
|
||||
<span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="identifier">opt</span><span class="special">(</span><span class="identifier">v0</span><span class="special">);</span>
|
||||
<span class="keyword">try</span>
|
||||
<span class="special">{</span>
|
||||
<span class="identifier">T</span> <span class="identifier">v1</span><span class="special">(</span><span class="number">456</span><span class="special">);</span>
|
||||
<span class="identifier">opt</span><span class="special">.</span><span class="identifier">reset</span> <span class="special">(</span> <span class="identifier">v1</span> <span class="special">)</span> <span class="special">;</span>
|
||||
|
||||
<span class="comment">// If no exception was thrown, reset succeeded.
|
||||
</span> <span class="identifier">assert</span><span class="special">(</span> <span class="special">*</span><span class="identifier">opt</span> <span class="special">==</span> <span class="identifier">v1</span> <span class="special">)</span> <span class="special">;</span>
|
||||
<span class="special">}</span>
|
||||
<span class="keyword">catch</span><span class="special">(...)</span>
|
||||
<span class="special">{</span>
|
||||
<span class="comment">// If any exception was thrown, 'opt' is reset to uninitialized.
|
||||
</span> <span class="identifier">assert</span><span class="special">(</span> <span class="special">!</span><span class="identifier">opt</span> <span class="special">)</span> <span class="special">;</span>
|
||||
<span class="special">}</span>
|
||||
</pre>
|
||||
<a name="boost_optional.exception_safety_guarantees.swap"></a><h4>
|
||||
<a name="id2644335"></a>
|
||||
<a href="exception_safety_guarantees.html#boost_optional.exception_safety_guarantees.swap">Swap</a>
|
||||
</h4>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="keyword">void</span> <span class="identifier">swap</span><span class="special">(</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">>&,</span>
|
||||
<span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">>&</span> <span class="special">)</span></code> has the same exception guarantee as <code class="computeroutput"><span class="identifier">swap</span><span class="special">(</span><span class="identifier">T</span><span class="special">&,</span><span class="identifier">T</span><span class="special">&)</span></code>
|
||||
when both optionals are initialized. If only one of the optionals is initialized,
|
||||
it gives the same <span class="emphasis"><em>basic</em></span> exception guarantee as <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">reset</span><span class="special">(</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="special">)</span></code> (since
|
||||
<code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">reset</span><span class="special">()</span></code> doesn't throw). If none of the optionals
|
||||
is initialized, it has no-throw guarantee since it is a no-op.
|
||||
</p>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
<td align="right"><small>Copyright <20> 2003 -2007 Fernando Luis Cacciola Carballal</small></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="a_note_about_optional_bool_.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="type_requirements.html"><img src="../images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@ -1,52 +0,0 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||||
<title>Implementation Notes</title>
|
||||
<link rel="stylesheet" href="../boostbook.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
|
||||
<link rel="start" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
|
||||
<link rel="up" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
|
||||
<link rel="prev" href="type_requirements.html" title="Type requirements">
|
||||
<link rel="next" href="dependencies_and_portability.html" title="Dependencies
|
||||
and Portability">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%">
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../index.htm">Home</a></td>
|
||||
<td align="center"><a href="../libraries.html">Libraries</a></td>
|
||||
<td align="center"><a href="../../../people/people.htm">People</a></td>
|
||||
<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
|
||||
<td align="center"><a href="../../../more/index.htm">More</a></td>
|
||||
</table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="type_requirements.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="dependencies_and_portability.html"><img src="../images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="boost_optional.implementation_notes"></a><a href="implementation_notes.html" title="Implementation Notes">Implementation Notes</a>
|
||||
</h2></div></div></div>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code> is
|
||||
currently implemented using a custom aligned storage facility built from <code class="computeroutput"><span class="identifier">alignment_of</span></code> and <code class="computeroutput"><span class="identifier">type_with_alignment</span></code>
|
||||
(both from Type Traits). It uses a separate boolean flag to indicate the initialization
|
||||
state. Placement new with <code class="computeroutput"><span class="identifier">T</span></code>'s
|
||||
copy constructor and <code class="computeroutput"><span class="identifier">T</span></code>'s destructor
|
||||
are explicitly used to initialize,copy and destroy optional values. As a result,
|
||||
<code class="computeroutput"><span class="identifier">T</span></code>'s default constructor is
|
||||
effectively by-passed, but the exception guarantees are basic. It is planned
|
||||
to replace the current implementation with another with stronger exception
|
||||
safety, such as a future <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">variant</span></code>.
|
||||
</p>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
<td align="right"><small>Copyright <20> 2003 -2007 Fernando Luis Cacciola Carballal</small></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="type_requirements.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="dependencies_and_portability.html"><img src="../images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@ -1,200 +0,0 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||||
<title>In-Place Factories</title>
|
||||
<link rel="stylesheet" href="../boostbook.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
|
||||
<link rel="start" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
|
||||
<link rel="up" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
|
||||
<link rel="prev" href="rebinding_semantics_for_assignment_of_optional_references.html" title="Rebinding
|
||||
semantics for assignment of optional references">
|
||||
<link rel="next" href="a_note_about_optional_bool_.html" title="A note about
|
||||
optional<bool>">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%">
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../index.htm">Home</a></td>
|
||||
<td align="center"><a href="../libraries.html">Libraries</a></td>
|
||||
<td align="center"><a href="../../../people/people.htm">People</a></td>
|
||||
<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
|
||||
<td align="center"><a href="../../../more/index.htm">More</a></td>
|
||||
</table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="rebinding_semantics_for_assignment_of_optional_references.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="a_note_about_optional_bool_.html"><img src="../images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="boost_optional.in_place_factories"></a><a href="in_place_factories.html" title="In-Place Factories">In-Place Factories</a>
|
||||
</h2></div></div></div>
|
||||
<p>
|
||||
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 <a href="../../../../utility/CopyConstructible.html" target="_top">Copy Constructible</a>,
|
||||
but also requires the existence of a fully constructed object, often temporary,
|
||||
just to follow the copy from:
|
||||
</p>
|
||||
<pre class="programlisting">
|
||||
<span class="keyword">struct</span> <span class="identifier">X</span>
|
||||
<span class="special">{</span>
|
||||
<span class="identifier">X</span> <span class="special">(</span> <span class="keyword">int</span><span class="special">,</span> <span class="identifier">std</span><span class="special">:::</span><span class="identifier">string</span> <span class="special">)</span> <span class="special">;</span>
|
||||
<span class="special">}</span> <span class="special">;</span>
|
||||
|
||||
<span class="keyword">class</span> <span class="identifier">W</span>
|
||||
<span class="special">{</span>
|
||||
<span class="identifier">X</span> <span class="identifier">wrapped_</span> <span class="special">;</span>
|
||||
|
||||
<span class="keyword">public</span><span class="special">:</span>
|
||||
|
||||
<span class="identifier">W</span> <span class="special">(</span> <span class="identifier">X</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x</span> <span class="special">)</span> <span class="special">:</span> <span class="identifier">wrapped_</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">{}</span>
|
||||
<span class="special">}</span> <span class="special">;</span>
|
||||
|
||||
<span class="keyword">void</span> <span class="identifier">foo</span><span class="special">()</span>
|
||||
<span class="special">{</span>
|
||||
<span class="comment">// Temporary object created.
|
||||
</span> <span class="identifier">W</span> <span class="special">(</span> <span class="identifier">X</span><span class="special">(</span><span class="number">123</span><span class="special">,</span><span class="string">"hello"</span><span class="special">)</span> <span class="special">)</span> <span class="special">;</span>
|
||||
<span class="special">}</span>
|
||||
</pre>
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
<pre class="programlisting">
|
||||
<span class="keyword">class</span> <span class="identifier">W</span>
|
||||
<span class="special">{</span>
|
||||
<span class="identifier">X</span> <span class="identifier">wrapped_</span> <span class="special">;</span>
|
||||
|
||||
<span class="keyword">public</span><span class="special">:</span>
|
||||
|
||||
<span class="identifier">W</span> <span class="special">(</span> <span class="identifier">X</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x</span> <span class="special">)</span> <span class="special">:</span> <span class="identifier">wrapped_</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">{}</span>
|
||||
<span class="identifier">W</span> <span class="special">(</span> <span class="keyword">int</span> <span class="identifier">a0</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">a1</span><span class="special">)</span> <span class="special">:</span> <span class="identifier">wrapped_</span><span class="special">(</span><span class="identifier">a0</span><span class="special">,</span><span class="identifier">a1</span><span class="special">)</span> <span class="special">{}</span>
|
||||
<span class="special">}</span> <span class="special">;</span>
|
||||
|
||||
<span class="keyword">void</span> <span class="identifier">foo</span><span class="special">()</span>
|
||||
<span class="special">{</span>
|
||||
<span class="comment">// Wrapped object constructed in-place
|
||||
</span> <span class="comment">// No temporary created.
|
||||
</span> <span class="identifier">W</span> <span class="special">(</span><span class="number">123</span><span class="special">,</span><span class="string">"hello"</span><span class="special">)</span> <span class="special">;</span>
|
||||
<span class="special">}</span>
|
||||
</pre>
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
<p>
|
||||
The solution presented in this library is the family of <span class="bold"><strong>InPlaceFactories</strong></span>
|
||||
and <span class="bold"><strong>TypedInPlaceFactories</strong></span>. 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.
|
||||
</p>
|
||||
<p>
|
||||
For example, one member of this family looks like:
|
||||
</p>
|
||||
<pre class="programlisting">
|
||||
<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">A1</span><span class="special">></span>
|
||||
<span class="keyword">class</span> <span class="identifier">TypedInPlaceFactory2</span>
|
||||
<span class="special">{</span>
|
||||
<span class="identifier">A0</span> <span class="identifier">m_a0</span> <span class="special">;</span> <span class="identifier">A1</span> <span class="identifier">m_a1</span> <span class="special">;</span>
|
||||
|
||||
<span class="keyword">public</span><span class="special">:</span>
|
||||
|
||||
<span class="identifier">TypedInPlaceFactory2</span><span class="special">(</span> <span class="identifier">A0</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">a0</span><span class="special">,</span> <span class="identifier">A1</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">a1</span> <span class="special">)</span> <span class="special">:</span> <span class="identifier">m_a0</span><span class="special">(</span><span class="identifier">a0</span><span class="special">),</span> <span class="identifier">m_a1</span><span class="special">(</span><span class="identifier">a1</span><span class="special">)</span> <span class="special">{}</span>
|
||||
|
||||
<span class="keyword">void</span> <span class="identifier">construct</span> <span class="special">(</span> <span class="keyword">void</span><span class="special">*</span> <span class="identifier">p</span> <span class="special">)</span> <span class="special">{</span> <span class="keyword">new</span> <span class="special">(</span><span class="identifier">p</span><span class="special">)</span> <span class="identifier">T</span><span class="special">(</span><span class="identifier">m_a0</span><span class="special">,</span><span class="identifier">m_a1</span><span class="special">)</span> <span class="special">;</span> <span class="special">}</span>
|
||||
<span class="special">}</span> <span class="special">;</span>
|
||||
</pre>
|
||||
<p>
|
||||
A wrapper class aware of this can use it as:
|
||||
</p>
|
||||
<pre class="programlisting">
|
||||
<span class="keyword">class</span> <span class="identifier">W</span>
|
||||
<span class="special">{</span>
|
||||
<span class="identifier">X</span> <span class="identifier">wrapped_</span> <span class="special">;</span>
|
||||
|
||||
<span class="keyword">public</span><span class="special">:</span>
|
||||
|
||||
<span class="identifier">W</span> <span class="special">(</span> <span class="identifier">X</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x</span> <span class="special">)</span> <span class="special">:</span> <span class="identifier">wrapped_</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">{}</span>
|
||||
<span class="identifier">W</span> <span class="special">(</span> <span class="identifier">TypedInPlaceFactory2</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">fac</span> <span class="special">)</span> <span class="special">{</span> <span class="identifier">fac</span><span class="special">.</span><span class="identifier">construct</span><span class="special">(&</span><span class="identifier">wrapped_</span><span class="special">)</span> <span class="special">;</span> <span class="special">}</span>
|
||||
<span class="special">}</span> <span class="special">;</span>
|
||||
|
||||
<span class="keyword">void</span> <span class="identifier">foo</span><span class="special">()</span>
|
||||
<span class="special">{</span>
|
||||
<span class="comment">// Wrapped object constructed in-place via a TypedInPlaceFactory.
|
||||
</span> <span class="comment">// No temporary created.
|
||||
</span> <span class="identifier">W</span> <span class="special">(</span> <span class="identifier">TypedInPlaceFactory2</span><span class="special"><</span><span class="identifier">X</span><span class="special">,</span><span class="keyword">int</span><span class="special">,</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&</span><span class="identifier">rt</span><span class="special">(</span><span class="number">123</span><span class="special">,</span><span class="string">"hello"</span><span class="special">))</span> <span class="special">;</span>
|
||||
<span class="special">}</span>
|
||||
</pre>
|
||||
<p>
|
||||
The factories are divided in two groups:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul type="disc">
|
||||
<li>
|
||||
<span class="underline">TypedInPlaceFactories</span>: those which
|
||||
take the target type as a primary template parameter.
|
||||
</li>
|
||||
<li>
|
||||
<span class="underline">InPlaceFactories</span>: those with a template
|
||||
<code class="computeroutput"><span class="identifier">construct</span><span class="special">(</span><span class="keyword">void</span><span class="special">*)</span></code> member
|
||||
function taking the target type.
|
||||
</li>
|
||||
</ul></div>
|
||||
<p>
|
||||
Within each group, all the family members differ only in the number of parameters
|
||||
allowed.
|
||||
</p>
|
||||
<p>
|
||||
This library provides an overloaded set of helper template functions to construct
|
||||
these factories without requiring unnecessary template parameters:
|
||||
</p>
|
||||
<pre class="programlisting">
|
||||
<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">,...,</span><span class="keyword">class</span> <span class="identifier">AN</span><span class="special">></span>
|
||||
<span class="identifier">InPlaceFactoryN</span> <span class="special"><</span><span class="identifier">A0</span><span class="special">,...,</span><span class="identifier">AN</span><span class="special">></span> <span class="identifier">in_place</span> <span class="special">(</span> <span class="identifier">A0</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">a0</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">AN</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">aN</span><span class="special">)</span> <span class="special">;</span>
|
||||
|
||||
<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span><span class="keyword">class</span> <span class="identifier">A0</span><span class="special">,...,</span><span class="keyword">class</span> <span class="identifier">AN</span><span class="special">></span>
|
||||
<span class="identifier">TypedInPlaceFactoryN</span> <span class="special"><</span><span class="identifier">T</span><span class="special">,</span><span class="identifier">A0</span><span class="special">,...,</span><span class="identifier">AN</span><span class="special">></span> <span class="identifier">in_place</span> <span class="special">(</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">a0</span><span class="special">,</span> <span class="identifier">A0</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">a0</span><span class="special">,</span> <span class="special">...,</span> <span class="identifier">AN</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">aN</span><span class="special">)</span> <span class="special">;</span>
|
||||
</pre>
|
||||
<p>
|
||||
In-place factories can be used generically by the wrapper and user as follows:
|
||||
</p>
|
||||
<pre class="programlisting">
|
||||
<span class="keyword">class</span> <span class="identifier">W</span>
|
||||
<span class="special">{</span>
|
||||
<span class="identifier">X</span> <span class="identifier">wrapped_</span> <span class="special">;</span>
|
||||
|
||||
<span class="keyword">public</span><span class="special">:</span>
|
||||
|
||||
<span class="identifier">W</span> <span class="special">(</span> <span class="identifier">X</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x</span> <span class="special">)</span> <span class="special">:</span> <span class="identifier">wrapped_</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">{}</span>
|
||||
|
||||
<span class="keyword">template</span><span class="special"><</span> <span class="keyword">class</span> <span class="identifier">InPlaceFactory</span> <span class="special">></span>
|
||||
<span class="identifier">W</span> <span class="special">(</span> <span class="identifier">InPlaceFactory</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">fac</span> <span class="special">)</span> <span class="special">{</span> <span class="identifier">fac</span><span class="special">.</span><span class="keyword">template</span> <span class="special"><</span><span class="identifier">X</span><span class="special">></span><span class="identifier">construct</span><span class="special">(&</span><span class="identifier">wrapped_</span><span class="special">)</span> <span class="special">;</span> <span class="special">}</span>
|
||||
|
||||
<span class="special">}</span> <span class="special">;</span>
|
||||
|
||||
<span class="keyword">void</span> <span class="identifier">foo</span><span class="special">()</span>
|
||||
<span class="special">{</span>
|
||||
<span class="comment">// Wrapped object constructed in-place via a InPlaceFactory.
|
||||
</span> <span class="comment">// No temporary created.
|
||||
</span> <span class="identifier">W</span> <span class="special">(</span> <span class="identifier">in_place</span><span class="special">(</span><span class="number">123</span><span class="special">,</span><span class="string">"hello"</span><span class="special">)</span> <span class="special">)</span> <span class="special">;</span>
|
||||
<span class="special">}</span>
|
||||
</pre>
|
||||
<p>
|
||||
The factories are implemented in the headers: <a href="../../../../../boost/utility/in_place_factory.hpp" target="_top">in_place_factory.hpp</a>
|
||||
and <a href="../../../../../boost/utility/typed_in_place_factory.hpp" target="_top">typed_in_place_factory.hpp</a>
|
||||
</p>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
<td align="right"><small>Copyright <20> 2003 -2007 Fernando Luis Cacciola Carballal</small></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="rebinding_semantics_for_assignment_of_optional_references.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="a_note_about_optional_bool_.html"><img src="../images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@ -1,82 +0,0 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||||
<title>Optional references</title>
|
||||
<link rel="stylesheet" href="../boostbook.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
|
||||
<link rel="start" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
|
||||
<link rel="up" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
|
||||
<link rel="prev" href="examples.html" title="Examples">
|
||||
<link rel="next" href="rebinding_semantics_for_assignment_of_optional_references.html" title="Rebinding
|
||||
semantics for assignment of optional references">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%">
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../index.htm">Home</a></td>
|
||||
<td align="center"><a href="../libraries.html">Libraries</a></td>
|
||||
<td align="center"><a href="../../../people/people.htm">People</a></td>
|
||||
<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
|
||||
<td align="center"><a href="../../../more/index.htm">More</a></td>
|
||||
</table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="examples.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="rebinding_semantics_for_assignment_of_optional_references.html"><img src="../images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="boost_optional.optional_references"></a><a href="optional_references.html" title="Optional references">Optional references</a>
|
||||
</h2></div></div></div>
|
||||
<p>
|
||||
This library allows the template parameter <code class="computeroutput"><span class="identifier">T</span></code>
|
||||
to be of reference type: <code class="computeroutput"><span class="identifier">T</span><span class="special">&</span></code>, and to some extent, <code class="computeroutput"><span class="identifier">T</span>
|
||||
<span class="keyword">const</span><span class="special">&</span></code>.
|
||||
</p>
|
||||
<p>
|
||||
However, since references are not real objects some restrictions apply and
|
||||
some operations are not available in this case:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul type="disc">
|
||||
<li>
|
||||
Converting constructors
|
||||
</li>
|
||||
<li>
|
||||
Converting assignment
|
||||
</li>
|
||||
<li>
|
||||
InPlace construction
|
||||
</li>
|
||||
<li>
|
||||
InPlace assignment
|
||||
</li>
|
||||
<li>
|
||||
Value-access via pointer
|
||||
</li>
|
||||
</ul></div>
|
||||
<p>
|
||||
Also, even though <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">&></span></code>
|
||||
treats it wrapped pseudo-object much as a real value, a true real reference
|
||||
is stored so aliasing will ocurr:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul type="disc">
|
||||
<li>
|
||||
Copies of <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">&></span></code>
|
||||
will copy the references but all these references will nonetheless reefer
|
||||
to the same object.
|
||||
</li>
|
||||
<li>
|
||||
Value-access will actually provide access to the referenced object rather
|
||||
than the reference itself.
|
||||
</li>
|
||||
</ul></div>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
<td align="right"><small>Copyright <20> 2003 -2007 Fernando Luis Cacciola Carballal</small></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="examples.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="rebinding_semantics_for_assignment_of_optional_references.html"><img src="../images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@ -1,151 +0,0 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||||
<title>Rebinding
|
||||
semantics for assignment of optional references</title>
|
||||
<link rel="stylesheet" href="../boostbook.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
|
||||
<link rel="start" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
|
||||
<link rel="up" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
|
||||
<link rel="prev" href="optional_references.html" title="Optional references">
|
||||
<link rel="next" href="in_place_factories.html" title="In-Place Factories">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%">
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../index.htm">Home</a></td>
|
||||
<td align="center"><a href="../libraries.html">Libraries</a></td>
|
||||
<td align="center"><a href="../../../people/people.htm">People</a></td>
|
||||
<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
|
||||
<td align="center"><a href="../../../more/index.htm">More</a></td>
|
||||
</table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="optional_references.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="in_place_factories.html"><img src="../images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="boost_optional.rebinding_semantics_for_assignment_of_optional_references"></a><a href="rebinding_semantics_for_assignment_of_optional_references.html" title="Rebinding
|
||||
semantics for assignment of optional references">Rebinding
|
||||
semantics for assignment of optional references</a>
|
||||
</h2></div></div></div>
|
||||
<p>
|
||||
If you assign to an <span class="emphasis"><em>uninitialized </em></span> <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">&></span></code>
|
||||
the effect is to bind (for the first time) to the object. Clearly, there is
|
||||
no other choice.
|
||||
</p>
|
||||
<pre class="programlisting">
|
||||
<span class="keyword">int</span> <span class="identifier">x</span> <span class="special">=</span> <span class="number">1</span> <span class="special">;</span>
|
||||
<span class="keyword">int</span><span class="special">&</span> <span class="identifier">rx</span> <span class="special">=</span> <span class="identifier">x</span> <span class="special">;</span>
|
||||
<span class="identifier">optional</span><span class="special"><</span><span class="keyword">int</span><span class="special">&></span> <span class="identifier">ora</span> <span class="special">;</span>
|
||||
<span class="identifier">optional</span><span class="special"><</span><span class="keyword">int</span><span class="special">&></span> <span class="identifier">orb</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span> <span class="special">;</span>
|
||||
<span class="identifier">ora</span> <span class="special">=</span> <span class="identifier">orb</span> <span class="special">;</span> <span class="comment">// now 'ora' is bound to 'x' through 'rx'
|
||||
</span><span class="special">*</span><span class="identifier">ora</span> <span class="special">=</span> <span class="number">2</span> <span class="special">;</span> <span class="comment">// Changes value of 'x' through 'ora'
|
||||
</span><span class="identifier">assert</span><span class="special">(</span><span class="identifier">x</span><span class="special">==</span><span class="number">2</span><span class="special">);</span>
|
||||
</pre>
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
<pre class="programlisting">
|
||||
<span class="keyword">int</span> <span class="identifier">a</span> <span class="special">=</span> <span class="number">1</span> <span class="special">;</span>
|
||||
<span class="keyword">int</span><span class="special">&</span> <span class="identifier">ra</span> <span class="special">=</span> <span class="identifier">a</span> <span class="special">;</span>
|
||||
<span class="keyword">int</span> <span class="identifier">b</span> <span class="special">=</span> <span class="number">2</span> <span class="special">;</span>
|
||||
<span class="keyword">int</span><span class="special">&</span> <span class="identifier">rb</span> <span class="special">=</span> <span class="identifier">b</span> <span class="special">;</span>
|
||||
<span class="identifier">ra</span> <span class="special">=</span> <span class="identifier">rb</span> <span class="special">;</span> <span class="comment">// Changes the value of 'a' to 'b'
|
||||
</span><span class="identifier">assert</span><span class="special">(</span><span class="identifier">a</span><span class="special">==</span><span class="identifier">b</span><span class="special">);</span>
|
||||
<span class="identifier">b</span> <span class="special">=</span> <span class="number">3</span> <span class="special">;</span>
|
||||
<span class="identifier">assert</span><span class="special">(</span><span class="identifier">ra</span><span class="special">!=</span><span class="identifier">b</span><span class="special">);</span> <span class="comment">// 'ra' is not rebound to 'b'
|
||||
</span></pre>
|
||||
<p>
|
||||
Now, if you assign to an <span class="emphasis"><em>initialized </em></span> <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">&></span></code>,
|
||||
the effect is to <span class="bold"><strong>rebind</strong></span> to the new object
|
||||
instead of assigning the referee. This is unlike bare C++ references.
|
||||
</p>
|
||||
<pre class="programlisting">
|
||||
<span class="keyword">int</span> <span class="identifier">a</span> <span class="special">=</span> <span class="number">1</span> <span class="special">;</span>
|
||||
<span class="keyword">int</span> <span class="identifier">b</span> <span class="special">=</span> <span class="number">2</span> <span class="special">;</span>
|
||||
<span class="keyword">int</span><span class="special">&</span> <span class="identifier">ra</span> <span class="special">=</span> <span class="identifier">a</span> <span class="special">;</span>
|
||||
<span class="keyword">int</span><span class="special">&</span> <span class="identifier">rb</span> <span class="special">=</span> <span class="identifier">b</span> <span class="special">;</span>
|
||||
<span class="identifier">optional</span><span class="special"><</span><span class="keyword">int</span><span class="special">&></span> <span class="identifier">ora</span><span class="special">(</span><span class="identifier">ra</span><span class="special">)</span> <span class="special">;</span>
|
||||
<span class="identifier">optional</span><span class="special"><</span><span class="keyword">int</span><span class="special">&></span> <span class="identifier">orb</span><span class="special">(</span><span class="identifier">rb</span><span class="special">)</span> <span class="special">;</span>
|
||||
<span class="identifier">ora</span> <span class="special">=</span> <span class="identifier">orb</span> <span class="special">;</span> <span class="comment">// 'ora' is rebound to 'b'
|
||||
</span><span class="special">*</span><span class="identifier">ora</span> <span class="special">=</span> <span class="number">3</span> <span class="special">;</span> <span class="comment">// Changes value of 'b' (not 'a')
|
||||
</span><span class="identifier">assert</span><span class="special">(</span><span class="identifier">a</span><span class="special">==</span><span class="number">1</span><span class="special">);</span>
|
||||
<span class="identifier">assert</span><span class="special">(</span><span class="identifier">b</span><span class="special">==</span><span class="number">3</span><span class="special">);</span>
|
||||
</pre>
|
||||
<a name="boost_optional.rebinding_semantics_for_assignment_of_optional_references.rationale"></a><h4>
|
||||
<a name="id2639932"></a>
|
||||
<a href="rebinding_semantics_for_assignment_of_optional_references.html#boost_optional.rebinding_semantics_for_assignment_of_optional_references.rationale">Rationale</a>
|
||||
</h4>
|
||||
<p>
|
||||
Rebinding semantics for the assignment of <span class="emphasis"><em>initialized </em></span>
|
||||
<code class="computeroutput"><span class="identifier">optional</span></code> references has been
|
||||
chosen to provide <span class="bold"><strong>consistency among initialization states</strong></span>
|
||||
even at the expense of lack of consistency with the semantics of bare C++ references.
|
||||
It is true that <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">U</span><span class="special">></span></code> strives
|
||||
to behave as much as possible as <code class="computeroutput"><span class="identifier">U</span></code>
|
||||
does whenever it is initialized; but in the case when <code class="computeroutput"><span class="identifier">U</span></code>
|
||||
is <code class="computeroutput"><span class="identifier">T</span><span class="special">&</span></code>,
|
||||
doing so would result in inconsistent behavior w.r.t to the lvalue initialization
|
||||
state.
|
||||
</p>
|
||||
<p>
|
||||
Imagine <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">&></span></code>
|
||||
forwarding assignment to the referenced object (thus changing the referenced
|
||||
object value but not rebinding), and consider the following code:
|
||||
</p>
|
||||
<pre class="programlisting">
|
||||
<span class="identifier">optional</span><span class="special"><</span><span class="keyword">int</span><span class="special">&></span> <span class="identifier">a</span> <span class="special">=</span> <span class="identifier">get</span><span class="special">();</span>
|
||||
<span class="keyword">int</span> <span class="identifier">x</span> <span class="special">=</span> <span class="number">1</span> <span class="special">;</span>
|
||||
<span class="keyword">int</span><span class="special">&</span> <span class="identifier">rx</span> <span class="special">=</span> <span class="identifier">x</span> <span class="special">;</span>
|
||||
<span class="identifier">optional</span><span class="special"><</span><span class="keyword">int</span><span class="special">&></span> <span class="identifier">b</span><span class="special">(</span><span class="identifier">rx</span><span class="special">);</span>
|
||||
<span class="identifier">a</span> <span class="special">=</span> <span class="identifier">b</span> <span class="special">;</span>
|
||||
</pre>
|
||||
<p>
|
||||
What does the assignment do?
|
||||
</p>
|
||||
<p>
|
||||
If <code class="computeroutput"><span class="identifier">a</span></code> is <span class="emphasis"><em>uninitialized</em></span>,
|
||||
the answer is clear: it binds to <code class="computeroutput"><span class="identifier">x</span></code>
|
||||
(we now have another reference to <code class="computeroutput"><span class="identifier">x</span></code>).
|
||||
But what if <code class="computeroutput"><span class="identifier">a</span></code> is already <span class="emphasis"><em>initialized</em></span>?
|
||||
it would change the value of the referenced object (whatever that is); which
|
||||
is inconsistent with the other possible case.
|
||||
</p>
|
||||
<p>
|
||||
If <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">&></span></code>
|
||||
would assign just like <code class="computeroutput"><span class="identifier">T</span><span class="special">&</span></code>
|
||||
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, <code class="computeroutput"><span class="identifier">a</span></code>
|
||||
aliases the same object as <code class="computeroutput"><span class="identifier">b</span></code>
|
||||
or not.
|
||||
</p>
|
||||
<p>
|
||||
That is, you would have to discriminate in order to be consistency.
|
||||
</p>
|
||||
<p>
|
||||
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 <span class="emphasis"><em>uninitialized </em></span> <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">&></span></code>
|
||||
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:
|
||||
</p>
|
||||
<pre class="programlisting">
|
||||
<span class="identifier">assert</span><span class="special">(!!</span><span class="identifier">opt</span><span class="special">);</span>
|
||||
<span class="special">*</span><span class="identifier">opt</span><span class="special">=</span><span class="identifier">value</span><span class="special">;</span>
|
||||
</pre>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
<td align="right"><small>Copyright <20> 2003 -2007 Fernando Luis Cacciola Carballal</small></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="optional_references.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="in_place_factories.html"><img src="../images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@ -1,147 +0,0 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||||
<title>Synopsis</title>
|
||||
<link rel="stylesheet" href="../boostbook.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
|
||||
<link rel="start" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
|
||||
<link rel="up" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
|
||||
<link rel="prev" href="development.html" title="Development">
|
||||
<link rel="next" href="detailed_semantics.html" title="Detailed Semantics">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%">
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../index.htm">Home</a></td>
|
||||
<td align="center"><a href="../libraries.html">Libraries</a></td>
|
||||
<td align="center"><a href="../../../people/people.htm">People</a></td>
|
||||
<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
|
||||
<td align="center"><a href="../../../more/index.htm">More</a></td>
|
||||
</table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="development.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="detailed_semantics.html"><img src="../images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="boost_optional.synopsis"></a><a href="synopsis.html" title="Synopsis">Synopsis</a>
|
||||
</h2></div></div></div>
|
||||
<pre class="programlisting">
|
||||
<span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span>
|
||||
|
||||
<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span>
|
||||
<span class="keyword">class</span> <span class="identifier">optional</span>
|
||||
<span class="special">{</span>
|
||||
<span class="keyword">public</span> <span class="special">:</span>
|
||||
|
||||
<span class="comment">// (If T is of reference type, the parameters and results by reference are by value)
|
||||
</span>
|
||||
<span class="identifier">optional</span> <span class="special">()</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_constructor"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="identifier">optional</span> <span class="special">(</span> <span class="identifier">none_t</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_constructor_none_t"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="identifier">optional</span> <span class="special">(</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">v</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_constructor_value"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="comment">// [new in 1.34]
|
||||
</span> <span class="identifier">optional</span> <span class="special">(</span> <span class="keyword">bool</span> <span class="identifier">condition</span><span class="special">,</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">v</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_constructor_bool_value"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="identifier">optional</span> <span class="special">(</span> <span class="identifier">optional</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_constructor_optional"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">U</span><span class="special">></span> <span class="keyword">explicit</span> <span class="identifier">optional</span> <span class="special">(</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">U</span><span class="special">></span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_constructor_other_optional"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">InPlaceFactory</span><span class="special">></span> <span class="keyword">explicit</span> <span class="identifier">optional</span> <span class="special">(</span> <span class="identifier">InPlaceFactory</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">f</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_constructor_factory"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">TypedInPlaceFactory</span><span class="special">></span> <span class="keyword">explicit</span> <span class="identifier">optional</span> <span class="special">(</span> <span class="identifier">TypedInPlaceFactory</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">f</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_constructor_factory"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="identifier">optional</span><span class="special">&</span> <span class="keyword">operator</span> <span class="special">=</span> <span class="special">(</span> <span class="identifier">none_t</span> <span class="special">)</span> <span class="special">;</span>
|
||||
|
||||
<span class="identifier">optional</span><span class="special">&</span> <span class="keyword">operator</span> <span class="special">=</span> <span class="special">(</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">v</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_operator_equal_value"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="identifier">optional</span><span class="special">&</span> <span class="keyword">operator</span> <span class="special">=</span> <span class="special">(</span> <span class="identifier">optional</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_operator_equal_optional"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">U</span><span class="special">></span> <span class="identifier">optional</span><span class="special">&</span> <span class="keyword">operator</span> <span class="special">=</span> <span class="special">(</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">U</span><span class="special">></span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">rhs</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_operator_equal_other_optional"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">InPlaceFactory</span><span class="special">></span> <span class="identifier">optional</span><span class="special">&</span> <span class="keyword">operator</span> <span class="special">=</span> <span class="special">(</span> <span class="identifier">InPlaceFactory</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">f</span> <span class="special">)</span> <span class="special">;</span>
|
||||
|
||||
<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">TypedInPlaceFactory</span><span class="special">></span> <span class="identifier">optional</span><span class="special">&</span> <span class="keyword">operator</span> <span class="special">=</span> <span class="special">(</span> <span class="identifier">TypedInPlaceFactory</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">f</span> <span class="special">)</span> <span class="special">;</span>
|
||||
|
||||
<span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">get</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_get"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
<span class="identifier">T</span><span class="special">&</span> <span class="identifier">get</span><span class="special">()</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_get"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="comment">// [new in 1.34]
|
||||
</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">get_value_or</span><span class="special">(</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="keyword">default</span> <span class="special">)</span> <span class="keyword">const</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_get_value_or_value"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="identifier">T</span> <span class="keyword">const</span><span class="special">*</span> <span class="keyword">operator</span> <span class="special">->()</span> <span class="keyword">const</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_operator_arrow"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
<span class="identifier">T</span><span class="special">*</span> <span class="keyword">operator</span> <span class="special">->()</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_operator_arrow"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="keyword">operator</span> <span class="special">*()</span> <span class="keyword">const</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_get"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
<span class="identifier">T</span><span class="special">&</span> <span class="keyword">operator</span> <span class="special">*()</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_get"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="identifier">T</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">get_ptr</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_get_ptr"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
<span class="identifier">T</span><span class="special">*</span> <span class="identifier">get_ptr</span><span class="special">()</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_get_ptr"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="keyword">operator</span> <span class="identifier">unspecified</span><span class="special">-</span><span class="keyword">bool</span><span class="special">-</span><span class="identifier">type</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_operator_bool"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">!()</span> <span class="keyword">const</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_operator_not"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="comment">// deprecated methods
|
||||
</span>
|
||||
<span class="comment">// (deprecated)
|
||||
</span> <span class="keyword">void</span> <span class="identifier">reset</span><span class="special">()</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_reset"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="comment">// (deprecated)
|
||||
</span> <span class="keyword">void</span> <span class="identifier">reset</span> <span class="special">(</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_reset_value"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="comment">// (deprecated)
|
||||
</span> <span class="keyword">bool</span> <span class="identifier">is_initialized</span><span class="special">()</span> <span class="keyword">const</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_is_initialized"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="special">};</span>
|
||||
|
||||
<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">inline</span> <span class="keyword">bool</span> <span class="keyword">operator</span> <span class="special">==</span> <span class="special">(</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">y</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_operator_compare_equal_optional_optional"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">inline</span> <span class="keyword">bool</span> <span class="keyword">operator</span> <span class="special">!=</span> <span class="special">(</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">y</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_operator_compare_not_equal_optional_optional"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">inline</span> <span class="keyword">bool</span> <span class="keyword">operator</span> <span class="special"><</span> <span class="special">(</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">y</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_operator_compare_less_optional_optional"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">inline</span> <span class="keyword">bool</span> <span class="keyword">operator</span> <span class="special">></span> <span class="special">(</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">y</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_operator_compare_greater_optional_optional"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">inline</span> <span class="keyword">bool</span> <span class="keyword">operator</span> <span class="special"><=</span> <span class="special">(</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">y</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_operator_compare_less_or_equal_optional_optional"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">inline</span> <span class="keyword">bool</span> <span class="keyword">operator</span> <span class="special">>=</span> <span class="special">(</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">y</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_operator_compare_greater_or_equal_optional_optional"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="comment">// [new in 1.34]
|
||||
</span><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">inline</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="identifier">make_optional</span> <span class="special">(</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">v</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_make_optional_value"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="comment">// [new in 1.34]
|
||||
</span><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">inline</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="identifier">make_optional</span> <span class="special">(</span> <span class="keyword">bool</span> <span class="identifier">condition</span><span class="special">,</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">v</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_make_optional_bool_value"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="comment">// [new in 1.34]
|
||||
</span><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">inline</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">get_optional_value_or</span> <span class="special">(</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">opt</span><span class="special">,</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="keyword">default</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_get_value_or_value"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">inline</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">get</span> <span class="special">(</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">opt</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_get"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">inline</span> <span class="identifier">T</span><span class="special">&</span> <span class="identifier">get</span> <span class="special">(</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="special">&</span> <span class="identifier">opt</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_get"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">inline</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">get</span> <span class="special">(</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">opt</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_get"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">inline</span> <span class="identifier">T</span><span class="special">*</span> <span class="identifier">get</span> <span class="special">(</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">>*</span> <span class="identifier">opt</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_get"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">inline</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">get_pointer</span> <span class="special">(</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">opt</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_get_ptr"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">inline</span> <span class="identifier">T</span><span class="special">*</span> <span class="identifier">get_pointer</span> <span class="special">(</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="special">&</span> <span class="identifier">opt</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_optional_get_ptr"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">inline</span> <span class="keyword">void</span> <span class="identifier">swap</span><span class="special">(</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">>&</span> <span class="identifier">x</span><span class="special">,</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">>&</span> <span class="identifier">y</span> <span class="special">)</span> <span class="special">;</span> <a href="detailed_semantics.html#reference_swap_optional_optional"><span class="inlinemediaobject"><img src="../images/callouts/R.png" alt="R"></span></a>
|
||||
|
||||
<span class="special">}</span> <span class="comment">// namespace boost
|
||||
</span></pre>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
<td align="right"><small>Copyright <20> 2003 -2007 Fernando Luis Cacciola Carballal</small></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="development.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="detailed_semantics.html"><img src="../images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@ -1,50 +0,0 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||||
<title>Type requirements</title>
|
||||
<link rel="stylesheet" href="../boostbook.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
|
||||
<link rel="start" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
|
||||
<link rel="up" href="../index.html" title="Chapter<65>1.<2E>Boost.Optional">
|
||||
<link rel="prev" href="exception_safety_guarantees.html" title="Exception Safety
|
||||
Guarantees">
|
||||
<link rel="next" href="implementation_notes.html" title="Implementation Notes">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%">
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../index.htm">Home</a></td>
|
||||
<td align="center"><a href="../libraries.html">Libraries</a></td>
|
||||
<td align="center"><a href="../../../people/people.htm">People</a></td>
|
||||
<td align="center"><a href="../../../more/faq.htm">FAQ</a></td>
|
||||
<td align="center"><a href="../../../more/index.htm">More</a></td>
|
||||
</table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="exception_safety_guarantees.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="implementation_notes.html"><img src="../images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="boost_optional.type_requirements"></a><a href="type_requirements.html" title="Type requirements">Type requirements</a>
|
||||
</h2></div></div></div>
|
||||
<p>
|
||||
In general, <code class="computeroutput"><span class="identifier">T</span></code> must be <a href="../../../../utility/CopyConstructible.html" target="_top">Copy Constructible</a> and
|
||||
have a no-throw destructor. The copy-constructible requirement is not needed
|
||||
if <span class="bold"><strong>InPlaceFactories</strong></span> are used.
|
||||
</p>
|
||||
<p>
|
||||
<code class="computeroutput"><span class="identifier">T</span></code> <span class="underline">is
|
||||
not</span> required to be <a href="http://www.sgi.com/tech/stl/DefaultConstructible.html" target="_top">Default
|
||||
Constructible</a>.
|
||||
</p>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
<td align="right"><small>Copyright <20> 2003 -2007 Fernando Luis Cacciola Carballal</small></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="exception_safety_guarantees.html"><img src="../images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../images/home.png" alt="Home"></a><a accesskey="n" href="implementation_notes.html"><img src="../images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@ -1,582 +0,0 @@
|
||||
/*=============================================================================
|
||||
Copyright (c) 2004 Joel de Guzman
|
||||
http://spirit.sourceforge.net/
|
||||
|
||||
Use, modification and distribution is subject to the Boost Software
|
||||
License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
|
||||
http://www.boost.org/LICENSE_1_0.txt)
|
||||
=============================================================================*/
|
||||
|
||||
/*=============================================================================
|
||||
Body defaults
|
||||
=============================================================================*/
|
||||
|
||||
body
|
||||
{
|
||||
margin: 1em;
|
||||
font-family: sans-serif;
|
||||
}
|
||||
|
||||
/*=============================================================================
|
||||
Paragraphs
|
||||
=============================================================================*/
|
||||
|
||||
p
|
||||
{
|
||||
text-align: left;
|
||||
font-size: 10pt;
|
||||
line-height: 1.15;
|
||||
}
|
||||
|
||||
/*=============================================================================
|
||||
Program listings
|
||||
=============================================================================*/
|
||||
|
||||
/* Code on paragraphs */
|
||||
p tt.computeroutput
|
||||
{
|
||||
font-size: 10pt;
|
||||
}
|
||||
|
||||
pre.synopsis
|
||||
{
|
||||
font-size: 10pt;
|
||||
margin: 1pc 4% 0pc 4%;
|
||||
padding: 0.5pc 0.5pc 0.5pc 0.5pc;
|
||||
}
|
||||
|
||||
.programlisting,
|
||||
.screen
|
||||
{
|
||||
font-size: 10pt;
|
||||
display: block;
|
||||
margin: 1pc 4% 0pc 4%;
|
||||
padding: 0.5pc 0.5pc 0.5pc 0.5pc;
|
||||
}
|
||||
|
||||
/* Program listings in tables don't get borders */
|
||||
td .programlisting,
|
||||
td .screen
|
||||
{
|
||||
margin: 0pc 0pc 0pc 0pc;
|
||||
padding: 0pc 0pc 0pc 0pc;
|
||||
}
|
||||
|
||||
/*=============================================================================
|
||||
Headings
|
||||
=============================================================================*/
|
||||
|
||||
h1, h2, h3, h4, h5, h6
|
||||
{
|
||||
text-align: left;
|
||||
margin: 1em 0em 0.5em 0em;
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
h1 { font: 140% }
|
||||
h2 { font: bold 140% }
|
||||
h3 { font: bold 130% }
|
||||
h4 { font: bold 120% }
|
||||
h5 { font: italic 110% }
|
||||
h6 { font: italic 100% }
|
||||
|
||||
/* Top page titles */
|
||||
title,
|
||||
h1.title,
|
||||
h2.title
|
||||
h3.title,
|
||||
h4.title,
|
||||
h5.title,
|
||||
h6.title,
|
||||
.refentrytitle
|
||||
{
|
||||
font-weight: bold;
|
||||
margin-bottom: 1pc;
|
||||
}
|
||||
|
||||
h1.title { font-size: 140% }
|
||||
h2.title { font-size: 140% }
|
||||
h3.title { font-size: 130% }
|
||||
h4.title { font-size: 120% }
|
||||
h5.title { font-size: 110% }
|
||||
h6.title { font-size: 100% }
|
||||
|
||||
.section h1
|
||||
{
|
||||
margin: 0em 0em 0.5em 0em;
|
||||
font-size: 140%;
|
||||
}
|
||||
|
||||
.section h2 { font-size: 140% }
|
||||
.section h3 { font-size: 130% }
|
||||
.section h4 { font-size: 120% }
|
||||
.section h5 { font-size: 110% }
|
||||
.section h6 { font-size: 100% }
|
||||
|
||||
/* Code on titles */
|
||||
h1 tt.computeroutput { font-size: 140% }
|
||||
h2 tt.computeroutput { font-size: 140% }
|
||||
h3 tt.computeroutput { font-size: 130% }
|
||||
h4 tt.computeroutput { font-size: 120% }
|
||||
h5 tt.computeroutput { font-size: 110% }
|
||||
h6 tt.computeroutput { font-size: 100% }
|
||||
|
||||
/*=============================================================================
|
||||
Author
|
||||
=============================================================================*/
|
||||
|
||||
h3.author
|
||||
{
|
||||
font-size: 100%
|
||||
}
|
||||
|
||||
/*=============================================================================
|
||||
Lists
|
||||
=============================================================================*/
|
||||
|
||||
li
|
||||
{
|
||||
font-size: 10pt;
|
||||
line-height: 1.3;
|
||||
}
|
||||
|
||||
/* Unordered lists */
|
||||
ul
|
||||
{
|
||||
text-align: left;
|
||||
}
|
||||
|
||||
/* Ordered lists */
|
||||
ol
|
||||
{
|
||||
text-align: left;
|
||||
}
|
||||
|
||||
/*=============================================================================
|
||||
Links
|
||||
=============================================================================*/
|
||||
|
||||
a
|
||||
{
|
||||
text-decoration: none; /* no underline */
|
||||
}
|
||||
|
||||
a:hover
|
||||
{
|
||||
text-decoration: underline;
|
||||
}
|
||||
|
||||
/*=============================================================================
|
||||
Spirit style navigation
|
||||
=============================================================================*/
|
||||
|
||||
.spirit-nav
|
||||
{
|
||||
text-align: right;
|
||||
}
|
||||
|
||||
.spirit-nav a
|
||||
{
|
||||
color: white;
|
||||
padding-left: 0.5em;
|
||||
}
|
||||
|
||||
.spirit-nav img
|
||||
{
|
||||
border-width: 0px;
|
||||
}
|
||||
|
||||
/*=============================================================================
|
||||
Table of contents
|
||||
=============================================================================*/
|
||||
|
||||
.toc
|
||||
{
|
||||
margin: 1pc 4% 0pc 4%;
|
||||
padding: 0.1pc 1pc 0.1pc 1pc;
|
||||
font-size: 10pt;
|
||||
line-height: 1.15;
|
||||
}
|
||||
|
||||
.toc-main
|
||||
{
|
||||
text-align: center;
|
||||
margin: 3pc 16% 3pc 16%;
|
||||
padding: 3pc 1pc 3pc 1pc;
|
||||
line-height: 0.1;
|
||||
}
|
||||
|
||||
.boost-toc
|
||||
{
|
||||
float: right;
|
||||
padding: 0.5pc;
|
||||
}
|
||||
|
||||
/*=============================================================================
|
||||
Tables
|
||||
=============================================================================*/
|
||||
|
||||
.table-title,
|
||||
div.table p.title
|
||||
{
|
||||
margin-left: 4%;
|
||||
padding-right: 0.5em;
|
||||
padding-left: 0.5em;
|
||||
}
|
||||
|
||||
.informaltable table,
|
||||
.table table
|
||||
{
|
||||
width: 92%;
|
||||
margin-left: 4%;
|
||||
margin-right: 4%;
|
||||
}
|
||||
|
||||
div.informaltable table,
|
||||
div.table table
|
||||
{
|
||||
padding: 4px;
|
||||
}
|
||||
|
||||
/* Table Cells */
|
||||
div.informaltable table tr td,
|
||||
div.table table tr td
|
||||
{
|
||||
padding: 0.5em;
|
||||
text-align: left;
|
||||
}
|
||||
|
||||
div.informaltable table tr th,
|
||||
div.table table tr th
|
||||
{
|
||||
padding: 0.5em 0.5em 0.5em 0.5em;
|
||||
border: 1pt solid white;
|
||||
font-size: 120%;
|
||||
}
|
||||
|
||||
/*=============================================================================
|
||||
Blurbs
|
||||
=============================================================================*/
|
||||
|
||||
div.note,
|
||||
div.tip,
|
||||
div.important,
|
||||
div.caution,
|
||||
div.warning,
|
||||
div.sidebar
|
||||
{
|
||||
font-size: 10pt;
|
||||
line-height: 1.2;
|
||||
display: block;
|
||||
margin: 1pc 4% 0pc 4%;
|
||||
padding: 0.5pc 0.5pc 0.5pc 0.5pc;
|
||||
}
|
||||
|
||||
div.sidebar img
|
||||
{
|
||||
padding: 1pt;
|
||||
}
|
||||
|
||||
|
||||
|
||||
/*=============================================================================
|
||||
Callouts
|
||||
=============================================================================*/
|
||||
.line_callout_bug img
|
||||
{
|
||||
float: left;
|
||||
position:relative;
|
||||
left: 4px;
|
||||
top: -12px;
|
||||
clear: left;
|
||||
margin-left:-22px;
|
||||
}
|
||||
|
||||
.callout_bug img
|
||||
{
|
||||
}
|
||||
|
||||
|
||||
|
||||
/*=============================================================================
|
||||
Variable Lists
|
||||
=============================================================================*/
|
||||
|
||||
/* Make the terms in definition lists bold */
|
||||
div.variablelist dl dt,
|
||||
span.term
|
||||
{
|
||||
font-weight: bold;
|
||||
font-size: 10pt;
|
||||
}
|
||||
|
||||
div.variablelist table tbody tr td
|
||||
{
|
||||
text-align: left;
|
||||
vertical-align: top;
|
||||
padding: 0em 2em 0em 0em;
|
||||
font-size: 10pt;
|
||||
margin: 0em 0em 0.5em 0em;
|
||||
line-height: 1;
|
||||
}
|
||||
|
||||
/* Make the terms in definition lists bold */
|
||||
div.variablelist dl dt
|
||||
{
|
||||
margin-bottom: 0.2em;
|
||||
}
|
||||
|
||||
div.variablelist dl dd
|
||||
{
|
||||
margin: 0em 0em 0.5em 2em;
|
||||
font-size: 10pt;
|
||||
}
|
||||
|
||||
div.variablelist table tbody tr td p
|
||||
div.variablelist dl dd p
|
||||
{
|
||||
margin: 0em 0em 0.5em 0em;
|
||||
line-height: 1;
|
||||
}
|
||||
|
||||
/*=============================================================================
|
||||
Misc
|
||||
=============================================================================*/
|
||||
|
||||
/* Title of books and articles in bibliographies */
|
||||
span.title
|
||||
{
|
||||
font-style: italic;
|
||||
}
|
||||
|
||||
span.underline
|
||||
{
|
||||
text-decoration: underline;
|
||||
}
|
||||
|
||||
span.strikethrough
|
||||
{
|
||||
text-decoration: line-through;
|
||||
}
|
||||
|
||||
/* Copyright, Legal Notice */
|
||||
div div.legalnotice p
|
||||
{
|
||||
text-align: left
|
||||
}
|
||||
|
||||
/*=============================================================================
|
||||
Colors
|
||||
=============================================================================*/
|
||||
|
||||
@media screen
|
||||
{
|
||||
/* Links */
|
||||
a
|
||||
{
|
||||
color: #0C7445;
|
||||
}
|
||||
|
||||
a:visited
|
||||
{
|
||||
color: #663974;
|
||||
}
|
||||
|
||||
h1 a, h2 a, h3 a, h4 a, h5 a, h6 a,
|
||||
h1 a:hover, h2 a:hover, h3 a:hover, h4 a:hover, h5 a:hover, h6 a:hover,
|
||||
h1 a:visited, h2 a:visited, h3 a:visited, h4 a:visited, h5 a:visited, h6 a:visited
|
||||
{
|
||||
text-decoration: none; /* no underline */
|
||||
color: #000000;
|
||||
}
|
||||
|
||||
/* Syntax Highlighting */
|
||||
.keyword { color: #0000AA; }
|
||||
.identifier { color: #000000; }
|
||||
.special { color: #707070; }
|
||||
.preprocessor { color: #402080; }
|
||||
.char { color: teal; }
|
||||
.comment { color: #800000; }
|
||||
.string { color: teal; }
|
||||
.number { color: teal; }
|
||||
.white_bkd { background-color: #E8FBE9; }
|
||||
.dk_grey_bkd { background-color: #A0DAAC; }
|
||||
|
||||
/* Copyright, Legal Notice */
|
||||
.copyright
|
||||
{
|
||||
color: #666666;
|
||||
font-size: small;
|
||||
}
|
||||
|
||||
div div.legalnotice p
|
||||
{
|
||||
color: #666666;
|
||||
}
|
||||
|
||||
/* Program listing */
|
||||
pre.synopsis
|
||||
{
|
||||
border: 1px solid #DCDCDC;
|
||||
border-bottom: 3px solid #9D9D9D;
|
||||
border-right: 3px solid #9D9D9D;
|
||||
background-color: #FAFFFB;
|
||||
}
|
||||
|
||||
.programlisting,
|
||||
.screen
|
||||
{
|
||||
border: 1px solid #DCDCDC;
|
||||
border-bottom: 3px solid #9D9D9D;
|
||||
border-right: 3px solid #9D9D9D;
|
||||
background-color: #FAFFFB;
|
||||
}
|
||||
|
||||
td .programlisting,
|
||||
td .screen
|
||||
{
|
||||
border: 0px solid #DCDCDC;
|
||||
}
|
||||
|
||||
/* Blurbs */
|
||||
div.note,
|
||||
div.tip,
|
||||
div.important,
|
||||
div.caution,
|
||||
div.warning,
|
||||
div.sidebar
|
||||
{
|
||||
border: 1px solid #DCDCDC;
|
||||
border-bottom: 3px solid #9D9D9D;
|
||||
border-right: 3px solid #9D9D9D;
|
||||
background-color: #FAFFFB;
|
||||
}
|
||||
|
||||
/* Table of contents */
|
||||
.toc
|
||||
{
|
||||
border: 1px solid #DCDCDC;
|
||||
border-bottom: 3px solid #9D9D9D;
|
||||
border-right: 3px solid #9D9D9D;
|
||||
background-color: #FAFFFB;
|
||||
}
|
||||
|
||||
/* Table of contents */
|
||||
.toc-main
|
||||
{
|
||||
border: 1px solid #DCDCDC;
|
||||
border-bottom: 3px solid #9D9D9D;
|
||||
border-right: 3px solid #9D9D9D;
|
||||
background-color: #FAFFFB;
|
||||
}
|
||||
|
||||
|
||||
/* Tables */
|
||||
div.informaltable table tr td,
|
||||
div.table table tr td
|
||||
{
|
||||
border: 1px solid #DCDCDC;
|
||||
background-color: #FAFFFB;
|
||||
}
|
||||
|
||||
div.informaltable table tr th,
|
||||
div.table table tr th
|
||||
{
|
||||
background-color: #E3F9E4;
|
||||
border: 1px solid #DCDCDC;
|
||||
}
|
||||
|
||||
/* Misc */
|
||||
span.highlight
|
||||
{
|
||||
color: #00A000;
|
||||
}
|
||||
}
|
||||
|
||||
@media print
|
||||
{
|
||||
/* Links */
|
||||
a
|
||||
{
|
||||
color: black;
|
||||
}
|
||||
|
||||
a:visited
|
||||
{
|
||||
color: black;
|
||||
}
|
||||
|
||||
.spirit-nav
|
||||
{
|
||||
display: none;
|
||||
}
|
||||
|
||||
/* Program listing */
|
||||
pre.synopsis
|
||||
{
|
||||
border: 1px solid gray;
|
||||
background-color: #FAFFFB;
|
||||
}
|
||||
|
||||
.programlisting,
|
||||
.screen
|
||||
{
|
||||
border: 1px solid gray;
|
||||
background-color: #FAFFFB;
|
||||
}
|
||||
|
||||
td .programlisting,
|
||||
td .screen
|
||||
{
|
||||
border: 0px solid #DCDCDC;
|
||||
}
|
||||
|
||||
/* Table of contents */
|
||||
.toc
|
||||
{
|
||||
border: 1px solid #DCDCDC;
|
||||
border-bottom: 3px solid #9D9D9D;
|
||||
border-right: 3px solid #9D9D9D;
|
||||
background-color: #FAFFFB;
|
||||
}
|
||||
|
||||
/* Table of contents */
|
||||
.toc-main
|
||||
{
|
||||
border: 1px solid #DCDCDC;
|
||||
border-bottom: 3px solid #9D9D9D;
|
||||
border-right: 3px solid #9D9D9D;
|
||||
background-color: #FAFFFB;
|
||||
}
|
||||
|
||||
.informaltable table,
|
||||
.table table
|
||||
{
|
||||
border: 1px solid #DCDCDC;
|
||||
border-bottom: 3px solid #9D9D9D;
|
||||
border-right: 3px solid #9D9D9D;
|
||||
border-collapse: collapse;
|
||||
background-color: #FAFFFB;
|
||||
}
|
||||
|
||||
/* Tables */
|
||||
div.informaltable table tr td,
|
||||
div.table table tr td
|
||||
{
|
||||
border: 1px solid #DCDCDC;
|
||||
background-color: #FAFFFB;
|
||||
}
|
||||
|
||||
div.informaltable table tr th,
|
||||
div.table table tr th
|
||||
{
|
||||
border: 1px solid #DCDCDC;
|
||||
background-color: #FAFFFB;
|
||||
}
|
||||
|
||||
/* Misc */
|
||||
span.highlight
|
||||
{
|
||||
font-weight: bold;
|
||||
}
|
||||
}
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 391 B |
Binary file not shown.
|
Before Width: | Height: | Size: 485 B |
Binary file not shown.
|
Before Width: | Height: | Size: 410 B |
Binary file not shown.
|
Before Width: | Height: | Size: 488 B |
Binary file not shown.
|
Before Width: | Height: | Size: 509 B |
Binary file not shown.
|
Before Width: | Height: | Size: 499 B |
Binary file not shown.
|
Before Width: | Height: | Size: 507 B |
Binary file not shown.
|
Before Width: | Height: | Size: 446 B |
Binary file not shown.
|
Before Width: | Height: | Size: 431 B |
Binary file not shown.
|
Before Width: | Height: | Size: 441 B |
Binary file not shown.
|
Before Width: | Height: | Size: 423 B |
Binary file not shown.
|
Before Width: | Height: | Size: 431 B |
Binary file not shown.
|
Before Width: | Height: | Size: 397 B |
Binary file not shown.
|
Before Width: | Height: | Size: 434 B |
Binary file not shown.
|
Before Width: | Height: | Size: 420 B |
Binary file not shown.
|
Before Width: | Height: | Size: 293 B |
Binary file not shown.
|
Before Width: | Height: | Size: 4.2 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 1.1 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 4.6 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 768 B |
Binary file not shown.
|
Before Width: | Height: | Size: 4.5 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 741 B |
Binary file not shown.
|
Before Width: | Height: | Size: 81 B |
Binary file not shown.
|
Before Width: | Height: | Size: 3.8 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 766 B |
Binary file not shown.
|
Before Width: | Height: | Size: 3.8 KiB |
@ -1,168 +0,0 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||||
<title>Chapter<EFBFBD>1.<2E>Boost.Optional</title>
|
||||
<link rel="stylesheet" href="boostbook.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.70.1">
|
||||
<link rel="start" href="index.html" title="Chapter<65>1.<2E>Boost.Optional">
|
||||
<link rel="next" href="boost_optional/development.html" title="Development">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%">
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../boost.png"></td>
|
||||
<td align="center"><a href="../../index.htm">Home</a></td>
|
||||
<td align="center"><a href="libraries.html">Libraries</a></td>
|
||||
<td align="center"><a href="../../people/people.htm">People</a></td>
|
||||
<td align="center"><a href="../../more/faq.htm">FAQ</a></td>
|
||||
<td align="center"><a href="../../more/index.htm">More</a></td>
|
||||
</table>
|
||||
<hr>
|
||||
<div class="spirit-nav"><a accesskey="n" href="boost_optional/development.html"><img src="images/next.png" alt="Next"></a></div>
|
||||
<div class="chapter" lang="en">
|
||||
<div class="titlepage"><div>
|
||||
<div><h2 class="title">
|
||||
<a name="optional"></a>Chapter<EFBFBD>1.<2E>Boost.Optional</h2></div>
|
||||
<div><div class="author"><h3 class="author">
|
||||
<span class="firstname">Fernando Luis</span> <span class="surname">Cacciola Carballal</span>
|
||||
</h3></div></div>
|
||||
<div><p class="copyright">Copyright <20> 2003 -2007 Fernando Luis Cacciola Carballal</p></div>
|
||||
<div><div class="legalnotice">
|
||||
<a name="id2604804"></a><p>
|
||||
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
|
||||
</p>
|
||||
</div></div>
|
||||
</div></div>
|
||||
<div class="toc">
|
||||
<p><b>Table of Contents</b></p>
|
||||
<dl>
|
||||
<dt><span class="section"><a href="index.html#optional.motivation">Motivation</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_optional/development.html">Development</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_optional/synopsis.html">Synopsis</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_optional/detailed_semantics.html">Detailed Semantics</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_optional/examples.html">Examples</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_optional/optional_references.html">Optional references</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_optional/rebinding_semantics_for_assignment_of_optional_references.html">Rebinding
|
||||
semantics for assignment of optional references</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_optional/in_place_factories.html">In-Place Factories</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_optional/a_note_about_optional_bool_.html">A note about
|
||||
optional<bool></a></span></dt>
|
||||
<dt><span class="section"><a href="boost_optional/exception_safety_guarantees.html">Exception Safety
|
||||
Guarantees</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_optional/type_requirements.html">Type requirements</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_optional/implementation_notes.html">Implementation Notes</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_optional/dependencies_and_portability.html">Dependencies
|
||||
and Portability</a></span></dt>
|
||||
<dt><span class="section"><a href="boost_optional/acknowledgments.html">Acknowledgments</a></span></dt>
|
||||
</dl>
|
||||
</div>
|
||||
<div class="section" lang="en">
|
||||
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
|
||||
<a name="optional.motivation"></a><a href="index.html#optional.motivation" title="Motivation">Motivation</a>
|
||||
</h2></div></div></div>
|
||||
<p>
|
||||
Consider these functions which should return a value but which might not have
|
||||
a value to return:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul type="disc">
|
||||
<li>
|
||||
(A) <code class="computeroutput"><span class="keyword">double</span> <span class="identifier">sqrt</span><span class="special">(</span><span class="keyword">double</span> <span class="identifier">n</span>
|
||||
<span class="special">);</span></code>
|
||||
</li>
|
||||
<li>
|
||||
(B) <code class="computeroutput"><span class="keyword">char</span> <span class="identifier">get_async_input</span><span class="special">();</span></code>
|
||||
</li>
|
||||
<li>
|
||||
(C) <code class="computeroutput"><span class="identifier">point</span> <span class="identifier">polygon</span><span class="special">::</span><span class="identifier">get_any_point_effectively_inside</span><span class="special">();</span></code>
|
||||
</li>
|
||||
</ul></div>
|
||||
<p>
|
||||
There are different approaches to the issue of not having a value to return.
|
||||
</p>
|
||||
<p>
|
||||
A typical approach is to consider the existence of a valid return value as
|
||||
a postcondition, so that if the function cannot compute the value to return,
|
||||
it has either undefined behavior (and can use assert in a debug build) or uses
|
||||
a runtime check and throws an exception if the postcondition is violated. This
|
||||
is a reasonable choice for example, for function (A), because the lack of a
|
||||
proper return value is directly related to an invalid parameter (out of domain
|
||||
argument), so it is appropriate to require the callee to supply only parameters
|
||||
in a valid domain for execution to continue normally.
|
||||
</p>
|
||||
<p>
|
||||
However, function (B), because of its asynchronous nature, does not fail just
|
||||
because it can't find a value to return; so it is incorrect to consider such
|
||||
a situation an error and assert or throw an exception. This function must return,
|
||||
and somehow, must tell the callee that it is not returning a meaningful value.
|
||||
</p>
|
||||
<p>
|
||||
A similar situation occurs with function (C): it is conceptually an error to
|
||||
ask a <span class="emphasis"><em>null-area</em></span> polygon to return a point inside itself,
|
||||
but in many applications, it is just impractical for performance reasons to
|
||||
treat this as an error (because detecting that the polygon has no area might
|
||||
be too expensive to be required to be tested previously), and either an arbitrary
|
||||
point (typically at infinity) is returned, or some efficient way to tell the
|
||||
callee that there is no such point is used.
|
||||
</p>
|
||||
<p>
|
||||
There are various mechanisms to let functions communicate that the returned
|
||||
value is not valid. One such mechanism, which is quite common since it has
|
||||
zero or negligible overhead, is to use a special value which is reserved to
|
||||
communicate this. Classical examples of such special values are <code class="computeroutput"><span class="identifier">EOF</span></code>, <code class="computeroutput"><span class="identifier">string</span><span class="special">::</span><span class="identifier">npos</span></code>, points
|
||||
at infinity, etc...
|
||||
</p>
|
||||
<p>
|
||||
When those values exist, i.e. the return type can hold all meaningful values
|
||||
<span class="emphasis"><em>plus</em></span> the <span class="emphasis"><em>signal</em></span> value, this mechanism
|
||||
is quite appropriate and well known. Unfortunately, there are cases when such
|
||||
values do not exist. In these cases, the usual alternative is either to use
|
||||
a wider type, such as <code class="computeroutput"><span class="keyword">int</span></code> in place
|
||||
of <code class="computeroutput"><span class="keyword">char</span></code>; or a compound type, such
|
||||
as <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special"><</span><span class="identifier">point</span><span class="special">,</span><span class="keyword">bool</span><span class="special">></span></code>.
|
||||
</p>
|
||||
<p>
|
||||
Returning a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special"><</span><span class="identifier">T</span><span class="special">,</span><span class="keyword">bool</span><span class="special">></span></code>, thus attaching a boolean flag to the result
|
||||
which indicates if the result is meaningful, has the advantage that can be
|
||||
turned into a consistent idiom since the first element of the pair can be whatever
|
||||
the function would conceptually return. For example, the last two functions
|
||||
could have the following interface:
|
||||
</p>
|
||||
<pre class="programlisting">
|
||||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special"><</span><span class="keyword">char</span><span class="special">,</span><span class="keyword">bool</span><span class="special">></span> <span class="identifier">get_async_input</span><span class="special">();</span>
|
||||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special"><</span><span class="identifier">point</span><span class="special">,</span><span class="keyword">bool</span><span class="special">></span> <span class="identifier">polygon</span><span class="special">::</span><span class="identifier">get_any_point_effectively_inside</span><span class="special">();</span>
|
||||
</pre>
|
||||
<p>
|
||||
These functions use a consistent interface for dealing with possibly inexistent
|
||||
results:
|
||||
</p>
|
||||
<pre class="programlisting">
|
||||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special"><</span><span class="identifier">point</span><span class="special">,</span><span class="keyword">bool</span><span class="special">></span> <span class="identifier">p</span> <span class="special">=</span> <span class="identifier">poly</span><span class="special">.</span><span class="identifier">get_any_point_effectively_inside</span><span class="special">();</span>
|
||||
<span class="keyword">if</span> <span class="special">(</span> <span class="identifier">p</span><span class="special">.</span><span class="identifier">second</span> <span class="special">)</span>
|
||||
<span class="identifier">flood_fill</span><span class="special">(</span><span class="identifier">p</span><span class="special">.</span><span class="identifier">first</span><span class="special">);</span>
|
||||
</pre>
|
||||
<p>
|
||||
However, not only is this quite a burden syntactically, it is also error prone
|
||||
since the user can easily use the function result (first element of the pair)
|
||||
without ever checking if it has a valid value.
|
||||
</p>
|
||||
<p>
|
||||
Clearly, we need a better idiom.
|
||||
</p>
|
||||
</div>
|
||||
<p>
|
||||
</p>
|
||||
<a name="optional_refassign"></a><p>
|
||||
</p>
|
||||
<a name="optional_in_place_factories"></a><p>
|
||||
</p>
|
||||
<a name="optional_implementation_notes"></a><p>
|
||||
</p>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"><small><p>Last revised: May 29, 2007 at 06:31:03 GMT</p></small></td>
|
||||
<td align="right"><small></small></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav"><a accesskey="n" href="boost_optional/development.html"><img src="images/next.png" alt="Next"></a></div>
|
||||
</body>
|
||||
</html>
|
||||
@ -1,28 +0,0 @@
|
||||
[/
|
||||
Boost.Optional
|
||||
|
||||
Copyright (c) 2003-2007 Fernando Luis Cacciola Carballal
|
||||
|
||||
Distributed under the Boost Software License, Version 1.0.
|
||||
(See accompanying file LICENSE_1_0.txt or copy at
|
||||
http://www.boost.org/LICENSE_1_0.txt)
|
||||
]
|
||||
|
||||
|
||||
|
||||
[#optional_implementation_notes]
|
||||
|
||||
[section Implementation Notes]
|
||||
|
||||
`optional<T>` is currently implemented using a custom aligned storage facility
|
||||
built from `alignment_of` and `type_with_alignment` (both from Type Traits). It
|
||||
uses a separate boolean flag to indicate the initialization state.
|
||||
Placement new with `T`'s copy constructor and `T`'s destructor are explicitly used
|
||||
to initialize,copy and destroy optional values.
|
||||
As a result, `T`'s default constructor is effectively by-passed, but the exception
|
||||
guarantees are basic.
|
||||
It is planned to replace the current implementation with another with stronger
|
||||
exception safety, such as a future `boost::variant`.
|
||||
|
||||
[endsect]
|
||||
|
||||
@ -3,6 +3,7 @@
|
||||
<HTML>
|
||||
|
||||
<HEAD>
|
||||
<meta http-equiv="Content-Language" content="en-us">
|
||||
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
|
||||
<meta name="ProgId" content="FrontPage.Editor.Document">
|
||||
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=windows-1252">
|
||||
@ -23,6 +24,7 @@ HREF="../../../boost/optional/optional.hpp">boost/optional/optional.hpp</A>>
|
||||
<DT><A HREF="#examples">Examples</A></DT>
|
||||
<DT><A HREF="#ref">Optional references</A></DT>
|
||||
<DT><A HREF="#refassign">Rebinding semantics for assignment of optional references</A></DT>
|
||||
<DT><A HREF="#none">none_t and none</A></DT>
|
||||
<DT><A HREF="#inplace">In-Place Factories</A></DT>
|
||||
<DT><A HREF="#bool">A note about optional<bool></A></DT>
|
||||
<DT><A HREF="#exsafety">Exception Safety Guarantees</A></DT>
|
||||
@ -138,7 +140,7 @@ necessary in order to do so.</p>
|
||||
<u>purpose</u> of optional<T> suggests
|
||||
an alternative model: a <i>container</i> that either has a value of T or nothing.
|
||||
</p>
|
||||
<p>As of this writing I don't know of any precedence for a variable-size fixed-capacity (of 1)
|
||||
<p>As of this writing I don't know of any precedent for a variable-size fixed-capacity (of 1)
|
||||
stack-based container model for optional values, yet I believe this is the consequence of
|
||||
the lack of practical implementations of such a container rather than an inherent shortcoming
|
||||
of the container model.</p>
|
||||
@ -348,7 +350,7 @@ class optional
|
||||
T const& get() const ;
|
||||
T& get() ;
|
||||
|
||||
T<span lang="es"> const&</span> get_value_or( T const& default ) const ; <u><i>[new in 1.34]</u></i>
|
||||
T const& get_value_or( T const& default ) const ; <u><i>[new in 1.34]</u></i>
|
||||
|
||||
T const* operator ->() const ;
|
||||
T* operator ->() ;
|
||||
@ -383,11 +385,59 @@ template<class T> inline bool operator <= ( optional<T> const& x, op
|
||||
|
||||
template<class T> inline bool operator >= ( optional<T> const& x, optional<T> const& y ) ;
|
||||
|
||||
template<class T> inline bool operator == ( optional<T> const& x, T const& n ) ; <u><i>[new in 1.34]</u></i>
|
||||
|
||||
template<class T> inline bool operator != ( optional<T> const& x, T const& n ) ; <u><i>[new in 1.34]</u></i>
|
||||
|
||||
template<class T> inline bool operator < ( optional<T> const& x, T const& n ) ; <u><i>[new in 1.34]</u></i>
|
||||
|
||||
template<class T> inline bool operator > ( optional<T> const& x, T const& n ) ; <u><i>[new in 1.34]</u></i>
|
||||
|
||||
template<class T> inline bool operator <= ( optional<T> const& x, T const& n ) ; <u><i>[new in 1.34]</u></i>
|
||||
|
||||
template<class T> inline bool operator >= ( optional<T> const& x, T const& n ) ; <u><i>[new in 1.34]</u></i>
|
||||
|
||||
template<class T> inline bool operator == ( T const& n, optional<T> const& y ) ; <u><i>[new in 1.34]</u></i>
|
||||
|
||||
template<class T> inline bool operator != ( T const& n, optional<T> const& y ) ; <u><i>[new in 1.34]</u></i>
|
||||
|
||||
template<class T> inline bool operator < ( T const& n, optional<T> const& y ) ; <u><i>[new in 1.34]</u></i>
|
||||
|
||||
template<class T> inline bool operator > ( T const& n, optional<T> const& y ) ; <u><i>[new in 1.34]</u></i>
|
||||
|
||||
template<class T> inline bool operator <= ( T const& n, optional<T> const& y ) ; <u><i>[new in 1.34]</u></i>
|
||||
|
||||
template<class T> inline bool operator >= ( T const& n, optional<T> const& y ) ; <u><i>[new in 1.34]</u></i>
|
||||
|
||||
template<class T> inline bool operator == ( optional<T> const& x, none_t n ) ; <u><i>[new in 1.34]</u></i>
|
||||
|
||||
template<class T> inline bool operator != ( optional<T> const& x, none_t n ) ; <u><i>[new in 1.34]</u></i>
|
||||
|
||||
template<class T> inline bool operator < ( optional<T> const& x, none_t n ) ; <u><i>[new in 1.34]</u></i>
|
||||
|
||||
template<class T> inline bool operator > ( optional<T> const& x, none_t n ) ; <u><i>[new in 1.34]</u></i>
|
||||
|
||||
template<class T> inline bool operator <= ( optional<T> const& x, none_t n ) ; <u><i>[new in 1.34]</u></i>
|
||||
|
||||
template<class T> inline bool operator >= ( optional<T> const& x, none_t n ) ; <u><i>[new in 1.34]</u></i>
|
||||
|
||||
template<class T> inline bool operator == ( none_t n, optional<T> const& y ) ; <u><i>[new in 1.34]</u></i>
|
||||
|
||||
template<class T> inline bool operator != ( none_t n, optional<T> const& y ) ; <u><i>[new in 1.34]</u></i>
|
||||
|
||||
template<class T> inline bool operator < ( none_t n, optional<T> const& y ) ; <u><i>[new in 1.34]</u></i>
|
||||
|
||||
template<class T> inline bool operator > ( none_t n, optional<T> const& y ) ; <u><i>[new in 1.34]</u></i>
|
||||
|
||||
template<class T> inline bool operator <= ( none_t n, optional<T> const& y ) ; <u><i>[new in 1.34]</u></i>
|
||||
|
||||
template<class T> inline bool operator >= ( none_t n, optional<T> const& y ) ; <u><i>[new in 1.34]</u></i>
|
||||
|
||||
template<class T> inline optional<T> make_optional ( T const& v ) ; <u><i>[new in 1.34]</u></i>
|
||||
|
||||
template<class T> inline optional<T> make_optional ( bool condition, T const& v ) ; <u><i>[new in 1.34]</u></i>
|
||||
|
||||
template<class T> inline T <span lang="es">const& </span>get_<span lang="es">optional_</span>value_or ( optional<T> const& opt, T const& default ) ; <u><i>[new in 1.34]</u></i>
|
||||
template<class T> inline T const& get_optional_value_or ( optional<T> const& opt, T const& default ) ; <u><i>[new in 1.34]</u></i>
|
||||
|
||||
template<class T> inline T const& get ( optional<T> const& opt ) ;
|
||||
|
||||
@ -457,9 +507,11 @@ used as the parameter.</p>
|
||||
</blockquote>
|
||||
<p><b>Example:</b></p>
|
||||
<blockquote>
|
||||
<pre>#include <boost/none.hpp></pre>
|
||||
<pre>optional<T> n(none) ;
|
||||
assert ( !n ) ;</pre>
|
||||
<pre>
|
||||
#include <boost/none.hpp>
|
||||
optional<int> n(boost::none) ;
|
||||
assert ( !n ) ;
|
||||
</pre>
|
||||
</blockquote>
|
||||
</blockquote>
|
||||
|
||||
@ -476,9 +528,11 @@ in that case, this constructor has no effect.
|
||||
</p>
|
||||
<p><b>Example:</b></p>
|
||||
<blockquote>
|
||||
<pre>T v;
|
||||
<pre>
|
||||
T v;
|
||||
optional<T> opt(v);
|
||||
assert ( *opt == v ) ;</pre>
|
||||
assert ( *opt == v ) ;
|
||||
</pre>
|
||||
</blockquote>
|
||||
</blockquote>
|
||||
|
||||
@ -492,29 +546,32 @@ instance of an internal type wrapping the reference 'ref'.</p>
|
||||
<p><b>Throws:</b> Nothing.</p>
|
||||
<p><b>Example:</b></p>
|
||||
<blockquote>
|
||||
<pre>T v;
|
||||
<pre>
|
||||
T v;
|
||||
T& vref = v ;
|
||||
optional<T&> opt(vref);
|
||||
assert ( *opt == v ) ;
|
||||
++ v ; // mutate referee
|
||||
assert (*opt == v); </pre>
|
||||
assert (*opt == v);
|
||||
</pre>
|
||||
</blockquote>
|
||||
</blockquote>
|
||||
|
||||
<HR>
|
||||
|
||||
<pre>optional<T <i>(not a ref)</i>>::optional( bool condition, T const& v ) ;
|
||||
optional<T&> <span lang="es"> </span>::optional( bool condition, T& <span lang="es"> </span> v ) ;
|
||||
optional<T&> ::optional( bool condition, T& v ) ;
|
||||
</pre>
|
||||
|
||||
<blockquote>
|
||||
<p>If <i>condition</i> is <code>true</code>, same as:</p>
|
||||
<pre>optional<T <i>(not a ref)</i>>::optional( T const& v )
|
||||
optional<T&><span lang="es"> </span>::optional( T&<span lang="es"> </span> v )
|
||||
optional<T&> ::optional( T& v )
|
||||
</pre>
|
||||
<p>otherwise, same as:</p>
|
||||
<pre>optional<T <i>(not a ref)</i>>::optional()
|
||||
optional<T&><span lang="es"> </span>::optional()
|
||||
<pre>
|
||||
optional<T <i>(not a ref)</i>>::optional()
|
||||
optional<T&> ::optional()
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
@ -533,7 +590,8 @@ in that case, this constructor has no effect.
|
||||
</p>
|
||||
<p><b>Example:</b></p>
|
||||
<blockquote>
|
||||
<pre>optional<T> uninit ;
|
||||
<pre>
|
||||
optional<T> uninit ;
|
||||
assert (!uninit);
|
||||
|
||||
optional<T> uinit2 ( uninit ) ;
|
||||
@ -562,7 +620,8 @@ is uninitialized.</p>
|
||||
reefer to the same object<b> </b>(they alias).</p>
|
||||
<p><b>Example:</b></p>
|
||||
<blockquote>
|
||||
<pre>optional<T&> uninit ;
|
||||
<pre>
|
||||
optional<T&> uninit ;
|
||||
assert (!uninit);
|
||||
|
||||
optional<T&> uinit2 ( uninit ) ;
|
||||
@ -605,7 +664,8 @@ in that case, this constructor has no effect.
|
||||
<p><b>Example:</b></p>
|
||||
<blockquote>
|
||||
|
||||
<pre>optional<double> x(123.4);
|
||||
<pre>
|
||||
optional<double> x(123.4);
|
||||
assert ( *x == 123.4 ) ;
|
||||
|
||||
optional<int> y(x) ;
|
||||
@ -633,7 +693,8 @@ in that case, this constructor has no effect.
|
||||
<p><b>Example:</b></p>
|
||||
<blockquote>
|
||||
|
||||
<pre>class C { C ( char, double, std::string ) ; } ;
|
||||
<pre>
|
||||
class C { C ( char, double, std::string ) ; } ;
|
||||
|
||||
C v('A',123.4,"hello");
|
||||
|
||||
@ -649,6 +710,27 @@ assert ( *y == v ) ;
|
||||
|
||||
<HR>
|
||||
|
||||
<pre>optional& optional<T</i>>::operator= ( none_t n ) ;</pre>
|
||||
<blockquote>
|
||||
<p><b>Effect:</b> Same as opeator=(optional const& rhs), when rhs is default-constructed (uninitialized).</p>
|
||||
<p><b>Postconditions:</b> <b>*this</b> is uninitialized</p>
|
||||
<p><b>Example:</b></p>
|
||||
<blockquote>
|
||||
<pre>
|
||||
#include <boost/none.hpp>
|
||||
|
||||
optional<int> def ;
|
||||
optional<int> opt(123) ;
|
||||
|
||||
opt = boost::none ;
|
||||
|
||||
assert ( opt == def ) ;
|
||||
</pre>
|
||||
</blockquote>
|
||||
</blockquote>
|
||||
|
||||
<HR>
|
||||
|
||||
<pre>optional& optional<T <i>(not a ref)</i>>::operator= ( T const& rhs ) ;</pre>
|
||||
<blockquote>
|
||||
<p><b>Effect:</b> Assigns the value 'rhs' to an <b>optional</b>.</p>
|
||||
@ -664,7 +746,8 @@ uninitialized and T's <i>copy constructor</i> fails, <b>*this</b> is left
|
||||
properly uninitialized]</p>
|
||||
<p><b>Example:</b></p>
|
||||
<blockquote>
|
||||
<pre>T x;
|
||||
<pre>
|
||||
T x;
|
||||
optional<T> def ;
|
||||
optional<T> opt(x) ;
|
||||
|
||||
@ -687,7 +770,8 @@ and it references the same object referenced by <b>rhs.</b></p>
|
||||
new object. See <A HREF="#refassign">here</a> for details on this behavior.</p>
|
||||
<p><b>Example:</b></p>
|
||||
<blockquote>
|
||||
<pre>int a = 1 ;
|
||||
<pre>
|
||||
int a = 1 ;
|
||||
int b = 2 ;
|
||||
T& ra = a ;
|
||||
T& rb = b ;
|
||||
@ -817,7 +901,7 @@ assert ( *opt1 == static_cast<U>(v) ) ;
|
||||
<HR>
|
||||
<pre>void optional<T>::reset() ;</pre>
|
||||
<blockquote>
|
||||
<p><b>Deprecated: </b>Same as operator=( detail::none_t );</p>
|
||||
<p><b>Deprecated: </b>Same as operator=( none_t n);</p>
|
||||
</blockquote>
|
||||
|
||||
<HR>
|
||||
@ -852,32 +936,6 @@ assert ( *opt == w ) ;
|
||||
|
||||
<HR>
|
||||
|
||||
<pre>T const& optional<T <i>(not a ref)</i>>::get_value_or( T const& default) const ;
|
||||
T& optional<T <i>(not a ref)</i>>::get_value_or( T& default ) ;
|
||||
|
||||
inline T const& get_optional_value_or ( optional<T<i> (not a ref)</i>> const& o, T const& default ) ;
|
||||
inline T& get_optional_value_or ( optional<T <i>(not a ref)</i>>& o, T& default ) ;
|
||||
</pre>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> A reference to the contained value, if any, or <code>default</code></p>
|
||||
<p><b>Throws:</b> Nothing.</p>
|
||||
<p><b>Example:</b></p>
|
||||
<blockquote>
|
||||
<pre>T v, z ;
|
||||
optional<T> def;
|
||||
T const& y = def.get_value_or(z);
|
||||
assert ( y == z ) ;
|
||||
|
||||
optional<T> opt ( v );
|
||||
T const& u = get_optional_value_or(opt,z);
|
||||
assert ( u == v ) ;
|
||||
assert ( u != z ) ;
|
||||
</pre>
|
||||
</blockquote>
|
||||
<pre></pre>
|
||||
</blockquote>
|
||||
<HR>
|
||||
|
||||
|
||||
<pre>T const& optional<T&>::operator*() const ;
|
||||
T & optional<T<i>&</i>>::operator*();</pre>
|
||||
@ -907,29 +965,66 @@ assert ( *opt == v ) ;</pre>
|
||||
|
||||
<HR>
|
||||
|
||||
<pre>T const* optional<T <i>(not a ref)</i>>::get_ptr() const ;
|
||||
T* optional<T <i>(not a ref)</i>>::get_ptr() ;
|
||||
<pre>T const& optional<T>::get_value_or( T const& default) const ;
|
||||
T& optional<T>::get_value_or( T& default ) ;
|
||||
|
||||
inline T const* get_pointer ( optional<T <i>(not a ref)</i>> const& ) ;
|
||||
inline T* get_pointer ( optional<T <i>(not a ref)</i>> &) ;
|
||||
inline T const& get_optional_value_or ( optional<T> const& o, T const& default ) ;
|
||||
inline T& get_optional_value_or ( optional<T>& o, T& default ) ;
|
||||
</pre>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> A reference to the contained value (which can be itself a reference), if any, or <code>default</code></p>
|
||||
<p><b>Throws:</b> Nothing.</p>
|
||||
<p><b>Example:</b></p>
|
||||
<blockquote>
|
||||
<pre>T v, z ;
|
||||
optional<T> def;
|
||||
T const& y = def.get_value_or(z);
|
||||
assert ( y == z ) ;
|
||||
|
||||
optional<T> opt ( v );
|
||||
T const& u = get_optional_value_or(opt,z);
|
||||
assert ( u == v ) ;
|
||||
assert ( u != z ) ;
|
||||
</pre>
|
||||
</blockquote>
|
||||
<pre></pre>
|
||||
</blockquote>
|
||||
|
||||
<HR>
|
||||
|
||||
<pre>T const* optional<T>::get_ptr() const ;
|
||||
T* optional<T>::get_ptr() ;
|
||||
|
||||
inline T const* get_pointer ( optional<T> const& ) ;
|
||||
inline T* get_pointer ( optional<T> &) ;
|
||||
</pre>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> If <b>*this</b> is initialized, a pointer to the contained
|
||||
value; else 0 (<i>null</i>).
|
||||
</p>
|
||||
<p><b>Throws:</b> Nothing.</p>
|
||||
<p><b>Notes:</b> If T is a reference type, the pointer is to the referenced object</p>
|
||||
<p><b>Notes:</b> The contained value is permanently stored within *this, so
|
||||
you should not hold nor delete this pointer
|
||||
you should not hold nor delete this pointer.
|
||||
</p>
|
||||
<p><b>Example:</b></p>
|
||||
<blockquote>
|
||||
<pre>T v;
|
||||
optional<T> opt(v);
|
||||
optional<T> const copt(v);
|
||||
T* p = opt.get_ptr() ;
|
||||
T const* cp = copt.get_ptr();
|
||||
<pre>int v=123;
|
||||
optional<int> opt(v);
|
||||
optional<int> const copt(v);
|
||||
int* p = opt.get_ptr() ;
|
||||
int const* cp = copt.get_ptr();
|
||||
assert ( p == get_pointer(opt) );
|
||||
assert ( cp == get_pointer(copt) ) ;
|
||||
|
||||
int& rv = v ;
|
||||
optional<int&> optr(rv);
|
||||
|
||||
*(optr.get_ptr()) = 456 ;
|
||||
|
||||
assert ( v == 456 );
|
||||
|
||||
|
||||
</pre>
|
||||
</blockquote>
|
||||
</blockquote>
|
||||
@ -938,13 +1033,14 @@ assert ( cp == get_pointer(copt) ) ;
|
||||
<HR>
|
||||
|
||||
|
||||
<pre>T const* optional<T <i>(not a ref)</i>>::operator ->() const ;
|
||||
T* optional<T <i>(not a ref)</i>>::operator ->() ;
|
||||
<pre>T const* optional<T>::operator ->() const ;
|
||||
T* optional<T>::operator ->() ;
|
||||
</pre>
|
||||
<blockquote>
|
||||
<p><b>Requirements: *this</b> is initialized.</p>
|
||||
<p><b>Returns:</b> A pointer to the contained value.</p>
|
||||
<p><b>Throws:</b> Nothing.</p>
|
||||
<p><b>Notes:</b> If T is a reference type, the pointer is to the referenced object</p>
|
||||
<p><b>Notes:</b> The requirement is asserted via BOOST_ASSERT().</p>
|
||||
<p><b>Example:</b></p>
|
||||
<blockquote>
|
||||
@ -952,6 +1048,14 @@ T* optional<T <i>(not a ref)</i>>::operator ->() ;
|
||||
X x ;
|
||||
optional<X> opt (x);
|
||||
opt->mdata = 2 ;
|
||||
|
||||
X& rx = x ;
|
||||
|
||||
optional<X&> optr (rx);
|
||||
optr->mdata = 4 ;
|
||||
|
||||
assert ( x.mdata = 4 )
|
||||
|
||||
</pre>
|
||||
</blockquote>
|
||||
</blockquote>
|
||||
@ -1154,13 +1258,50 @@ assert ( optX != optZ ) ;
|
||||
<p><b>Throws:</b> Nothing.</p>
|
||||
</blockquote>
|
||||
|
||||
<HR>
|
||||
<pre>
|
||||
bool operator == ( optional<T> const& x, T const& n );
|
||||
bool operator != ( optional<T> const& x, T const& n );
|
||||
bool operator < ( optional<T> const& x, T const& n );
|
||||
bool operator > ( optional<T> const& x, T const& n );
|
||||
bool operator <= ( optional<T> const& x, T const& n );
|
||||
bool operator >= ( optional<T> const& x, T const& n );
|
||||
bool operator == ( T const& n, optional<T> const& y );
|
||||
bool operator != ( T const& n, optional<T> const& y );
|
||||
bool operator < ( T const& n, optional<T> const& y );
|
||||
bool operator > ( T const& n, optional<T> const& y );
|
||||
bool operator <= ( T const& n, optional<T> const& y );
|
||||
bool operator >= ( T const& n, optional<T> const& y );
|
||||
</pre>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> The result obtained by replacing the argument 'n' by optional<T>(n).</p>
|
||||
</blockquote>
|
||||
|
||||
<HR>
|
||||
<pre>
|
||||
bool operator == ( optional<T> const& x, none_t n );
|
||||
bool operator != ( optional<T> const& x, none_t n );
|
||||
bool operator < ( optional<T> const& x, none_t n );
|
||||
bool operator > ( optional<T> const& x, none_t n );
|
||||
bool operator <= ( optional<T> const& x, none_t n );
|
||||
bool operator >= ( optional<T> const& x, none_t n );
|
||||
bool operator == ( none_t n, optional<T> const& y );
|
||||
bool operator != ( none_t n, optional<T> const& y );
|
||||
bool operator < ( none_t n, optional<T> const& y );
|
||||
bool operator > ( none_t n, optional<T> const& y );
|
||||
bool operator <= ( none_t n, optional<T> const& y );
|
||||
bool operator >= ( none_t n, optional<T> const& y );
|
||||
</pre>
|
||||
<blockquote>
|
||||
<p><b>Returns:</b> The result obtained by replacing the argument 'n' by optional<T>().</p>
|
||||
</blockquote>
|
||||
<HR>
|
||||
|
||||
<pre>void swap ( optional<T>& x, optional<T>& y );</pre>
|
||||
|
||||
<blockquote>
|
||||
<p><b>Effect:</b> If both <b>x</b> and <b>y</b> are initialized, calls <code>swap(*x,*y)</code> using std::swap.<br>
|
||||
If only one is initialized, say x, calls: <code>y.reset(*x); x.reset();</code><br>
|
||||
If only one is initialized, say x, calls: <code>y = *x; x = boost:none;</code><br>
|
||||
If none is initialized, does nothing. </p>
|
||||
<p><b>Postconditions:</b> The states of x and y interchanged.</p>
|
||||
<p><b>Throws:</b> If both are initialized, whatever swap(T&,T&) throws.
|
||||
@ -1169,7 +1310,7 @@ If only one is initialized, whatever T::T ( T const& ) throws. </p>
|
||||
If only one is initialized, T::~T() and T::T( T const& ) is called. </p>
|
||||
<p><b>Exception Safety:</b> If both are initialized, this operation has the exception
|
||||
safety guarantees of swap(T&,T&).<br>
|
||||
If only one is initialized, it has the same <b>basic</b> guarantee as optional<T>::reset( T const& ). </p>
|
||||
If only one is initialized, it has the same <b>basic</b> guarantee as optional<T>::operator=( T const& ). </p>
|
||||
<p><b>Example:</b></p>
|
||||
<blockquote>
|
||||
<pre>T x(12);
|
||||
@ -1219,12 +1360,12 @@ void receive_async_message()
|
||||
<pre>optional<string> name ;
|
||||
if ( database.open() )
|
||||
{
|
||||
name.reset ( database.lookup(employer_name) ) ;
|
||||
name = database.lookup(employer_name) ;
|
||||
}
|
||||
else
|
||||
{
|
||||
if ( can_ask_user )
|
||||
name.reset ( user.ask(employer_name) ) ;
|
||||
name = user.ask(employer_name) ;
|
||||
}
|
||||
|
||||
if ( name )
|
||||
@ -1245,7 +1386,7 @@ else print("employer's name not found!");
|
||||
void clip_in_rect ( rect const& rect )
|
||||
{
|
||||
....
|
||||
m_clipping_rect.reset ( rect ) ; // initialized here.
|
||||
m_clipping_rect = rect ; // initialized here.
|
||||
}
|
||||
|
||||
void draw ( canvas& cvs )
|
||||
@ -1289,16 +1430,17 @@ some operations are not available in this case:</p>
|
||||
<li>Converting assignment</li>
|
||||
<li>InPlace construction</li>
|
||||
<li>InPlace assignment</li>
|
||||
<li>Value-access via pointer</li>
|
||||
</ul>
|
||||
<p>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: </p>
|
||||
value, a true real reference is stored, thus aliasing can ocurr: </p>
|
||||
|
||||
<ul>
|
||||
<li>Copies of optional<T&> will copy the references but all these references
|
||||
<li>Copies of optional<T&> copies the reference, but all copied references
|
||||
will nonetheless reefer to the same object.</li>
|
||||
<li>Value-access will actually provide access to the referenced object rather
|
||||
<li>Value-access provides access to the referenced object rather
|
||||
than the reference itself.</li>
|
||||
<li>Pointer-access provides a pointer to the referenced object rather
|
||||
than a pointer to the reference itself.</li>
|
||||
</ul>
|
||||
|
||||
<HR>
|
||||
@ -1309,7 +1451,7 @@ Clearly, there is no other choice.</p>
|
||||
<pre>int x = 1 ;
|
||||
int& rx = x ;
|
||||
optional<int&> ora ;
|
||||
optional<int&> orb(x) ;
|
||||
optional<int&> orb(rx) ;
|
||||
ora = orb ; // now 'ora' is bound to 'x' through 'rx'
|
||||
*ora = 2 ; // Changes value of 'x' through 'ora'
|
||||
assert(x==2);
|
||||
@ -1320,7 +1462,7 @@ referenced object; it's value changes but the reference is never rebound.</p>
|
||||
int& ra = a ;
|
||||
int b = 2 ;
|
||||
int& rb = b ;
|
||||
ra = rb ; // Changes the value of 'a' to 'b'
|
||||
ra = rb ; // Changes the VALUE of 'a' to that of 'b'
|
||||
assert(a==b);
|
||||
b = 3 ;
|
||||
assert(ra!=b); // 'ra' is not rebound to 'b'
|
||||
@ -1346,38 +1488,68 @@ C++ references.<br>
|
||||
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.</p>
|
||||
<p>Imagine optional<T&> forwarding assignment to the referenced object (thus
|
||||
changing the referenced object value but not rebinding), and consider the
|
||||
following code :</p>
|
||||
<pre> optional<int&> a = get();
|
||||
int x = 1 ;
|
||||
int& rx = x ;
|
||||
optional<int&> b(rx);
|
||||
a = b ;
|
||||
<p>Consider the following code :</p>
|
||||
<pre>
|
||||
int x = 1 ;
|
||||
int& rx = x ;
|
||||
void foo ( optional<int&> & outer )
|
||||
{
|
||||
optional<int&> b(rx);
|
||||
outer = b ;
|
||||
}
|
||||
</pre>
|
||||
<p>What should the assignment to 'outer' do?<br>
|
||||
If 'outer' is <i>uninitialized</i>, the answer is clear: it should bind to 'x' (so we now have
|
||||
a second reference to 'x').<br>
|
||||
But what if 'outer' is already <i>initialized?</i><br>
|
||||
The assignment could change the value of the
|
||||
referenced object (whatever that is), but doing that would be inconsistent with the uninitialized case
|
||||
and then you wouldn't be able to reason at compile time about all the references to x since
|
||||
the appearance of a new reference to it would depend on wheter the lvalue ('outer')
|
||||
is initialized or not.</p>
|
||||
<p>Arguably, if rebinding the reference to another object is wrong for your code, then is
|
||||
likely that binding it for the fist time via assignment instead of intialization is also wrong.
|
||||
In that case, you can always just assign the value to the referenced object directly via
|
||||
the access operator <code>*opt=value</code>.</p>
|
||||
<p>If rebinding is wrong but first-time binding
|
||||
isn't (via assignment), you can always work around the rebinding semantics using a discriminator:</p>
|
||||
<pre>
|
||||
if ( !opt )
|
||||
opt = value ; // first-time binding
|
||||
else *opt = value ; // assign to referee without rebinding
|
||||
</pre>
|
||||
|
||||
<HR>
|
||||
|
||||
<H2><A NAME="none">none_t and none</A></H2>
|
||||
<p>optional<T> supports uninitialized states with a convenient syntax via a constant of
|
||||
the <i>implementation-defined</i> type <code>boost::none_t</code>, identified as <code>boost::none</code>.</p>
|
||||
<p>Starting with Boost version 1.34.0, both <code>boost::none_t</code> and <code>boost::none</code> are
|
||||
included in <code>boost/none.hpp</code>, which is automatically included by <code>boost/optional/optional.hpp</code>
|
||||
</p>
|
||||
<p>This contant is similar in purpose to NULL, except that is not a <i>null pointer value</i>. You can use it to initialize
|
||||
an optional<T> instance, which has the same effect of a default constructor, and you can assign it which has the
|
||||
effect of reseting the optional<T> instance. You can also use it in relational operators to make the predicate expression
|
||||
more clear.</p>
|
||||
<p>Here are some typical examples:</p>
|
||||
<pre>
|
||||
#include "boost/optional/optional.hpp" // boost/none.hpp is included automatically
|
||||
|
||||
boost::optional<int> foo ( int a )
|
||||
{
|
||||
return some_condition(a) ? boost::make_optional(a) : boost::none ;
|
||||
|
||||
// NOTE: in real code you can just use this: make_optional(some_condition(a), a )
|
||||
}
|
||||
|
||||
boost::optional<int> opt = boost::none ;
|
||||
|
||||
if ( opt == boost::none )
|
||||
opt = foo(123);
|
||||
|
||||
opt = boost::none ;
|
||||
|
||||
</pre>
|
||||
<p>What does the assignment do?<br>
|
||||
If 'a' is <i>uninitialized</i>, the answer is clear: it binds to 'x' (we now have
|
||||
another reference to 'x').<br>
|
||||
But what if 'a' is already <i>initialized? </i>it would change the value of the
|
||||
referenced object (whatever that is); which is inconsistent with the other
|
||||
possible case.</p>
|
||||
<p>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.</p>
|
||||
<p>That is, you would have to discriminate in order to be consistency.<br>
|
||||
<br>
|
||||
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 <i>uninitialized</i> 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.<br>
|
||||
In such scenario, you can assign the value itself directly, as in:</p>
|
||||
<pre>assert(!!opt);
|
||||
*opt=value; </pre>
|
||||
|
||||
<HR>
|
||||
|
||||
@ -1506,9 +1678,8 @@ public:
|
||||
the <i>maybe</i> state <u>represents a valid value</u>, unlike the corresponding state
|
||||
of an uninitialized optional<bool>.<br>
|
||||
It should be carefully considered if an optional<bool> instead of a tribool is really needed</p>
|
||||
<p>Second, optional<> provides an implicit conversion to bool. This conversion
|
||||
refers to the initialization state and not to the contained value.<br>
|
||||
Using optional<bool> can lead to subtle errors due to the implicit bool conversion:</p>
|
||||
<p>Second, optional<> provides a simple way to test initialization state: an implicit conversion to a type that evaluates as a 'bool' in a boolean context.<br>
|
||||
Using optional<bool> can lead to subtle errors due to this implicit conversion:</p>
|
||||
<pre>void foo ( bool v ) ;
|
||||
void bar()
|
||||
{
|
||||
@ -1524,7 +1695,9 @@ void bar()
|
||||
integral promotions don't apply (i.e. if foo() takes an 'int' instead, it won't compile). <HR>
|
||||
|
||||
<H2><A NAME="exsafety">Exception Safety Guarantees</A></H2>
|
||||
<H3><u>Assignment and Reset:</u></H3>
|
||||
|
||||
<H3><u>Assignment:</u></H3>
|
||||
<p><i>IMPORTANT NOTE: This changed in 1.33.1 with respect to previous versions</i></p>
|
||||
<p>Because of the current implementation (see <A HREF="#impl">Implementation Notes</A>), all
|
||||
of the assignment methods:</p>
|
||||
<ul>
|
||||
@ -1537,60 +1710,17 @@ of the assignment methods:</p>
|
||||
InPlaceFactory const& ) </code></li>
|
||||
<li> <code>template<class TypedInPlaceFactory> optional<T>::operator= (
|
||||
TypedInPlaceFactory const& ) </code></li>
|
||||
<li> <code>optional<T>:::reset ( T const&)</code></li>
|
||||
</ul>
|
||||
<p>Can only <i>guarantee</i> the <u>basic exception safety</u>: The lvalue optional is left <u>uninitialized</u> if an exception is thrown (any previous value is <i>first</i> destroyed using T::~T())</p>
|
||||
<p>cannot offer any <i>exception safety guarantee</i> beyond that provided by <code>T::operator=( T const& )</code></p>
|
||||
<p>On the other hand, the <i>uninitializing</i> methods:</p>
|
||||
<ul>
|
||||
<li><code>optional<T>::operator= ( detail::none_t ) </code></li>
|
||||
<li><code>optional<T>::reset()</code></li>
|
||||
</ul>
|
||||
<p>Provide the no-throw guarantee (assuming a no-throw T::~T())</p>
|
||||
<p>However, since <code>optional<></code> 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.</p>
|
||||
<pre>//
|
||||
// Case 1: Exception thrown during assignment.
|
||||
//
|
||||
T v0(123);
|
||||
optional<T> opt0(v0);
|
||||
try
|
||||
{
|
||||
T v1(456);
|
||||
optional<T> opt1(v1);
|
||||
opt0 = opt1 ;
|
||||
<p>Provides the no-throw guarantee (assuming a no-throw T::~T()) becuse it only destroys the stored object.</p>
|
||||
|
||||
// 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 ) ;
|
||||
}
|
||||
</pre>
|
||||
<H3><u>Swap:</u></H3>
|
||||
<p><code>void swap( optional<T>&, optional<T>& )</code> has the same exception guarantee as <code>swap(T&,T&)</code> when both optionals are initialized.<br>
|
||||
If only one of the optionals is initialized, it gives the same <i>basic</i> exception guarantee as <code>optional<T>::reset( T const& )</code> (since <code>optional<T>::reset()</code> doesn't throw).<br>
|
||||
If only one of the optionals is initialized, it gives the same exception guarantee as <code>T::operator=( T const& )</code> (since <code>optional<T>::operator=( none_t )</code> doesn't throw).<br>
|
||||
If none of the optionals is initialized, it has no-throw guarantee since it is a no-op. </p>
|
||||
|
||||
<HR>
|
||||
@ -1604,14 +1734,11 @@ T <u>is not</u> required to be <a href="http://www.sgi.com/tech/stl/DefaultConst
|
||||
|
||||
<H2><A NAME="impl">Implementation Notes</A></H2>
|
||||
<p>optional<T> is currently implemented
|
||||
using a custom aligned storage facility built from <code>alignment_of</code> and <code>type_with_alignment</code> (both from Type Traits).
|
||||
It uses a separate boolean flag to indicate the initialization state.<br>
|
||||
Placement new with T's copy constructor and T's destructor
|
||||
are explicitly used to initialize,copy and destroy optional values.<br>
|
||||
As a result, T's default constructor is effectively by-passed, but the exception
|
||||
guarantees are basic.<br>
|
||||
It is planned to replace the current implementation with another with
|
||||
stronger exception safety, such as a future boost::variant<T,nil_t>. </p>
|
||||
using a custom aligned storage facility built from <code>alignment_of</code> and <code>type_with_alignment</code> (both from Type Traits).
|
||||
It uses a separate boolean flag to indicate the initialization state.</p>
|
||||
<p>Placement new with T's copy constructor and T's destructor
|
||||
is explicitly used to initialize and destroy optional values. This allows T's default constructor to be effectively by-passed.</p>
|
||||
<p>If assignment is used and the lvalue optional is uninitialized, T's copy constructor is used. However, if it is already initialized, T's assignment operator is used. This prevents optional from offering any exception guarantee stronger than the one offered by the type T itself</p>
|
||||
|
||||
<HR>
|
||||
|
||||
@ -1665,12 +1792,12 @@ T <u>is not</u> required to be <a href="http://www.sgi.com/tech/stl/DefaultConst
|
||||
</blockquote>
|
||||
<HR>
|
||||
|
||||
<P>Revised April 21, 2005</P>
|
||||
<p><EFBFBD> Copyright Fernando Luis Cacciola Carballal, 2003,2004,2005</p>
|
||||
<P>Revised March 27, 2007</P>
|
||||
<p><EFBFBD> Copyright Fernando Luis Cacciola Carballal, 2003-2007</p>
|
||||
<p> Use, modification, and distribution are subject to the Boost Software
|
||||
License, Version 1.0. (See accompanying file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)</p>
|
||||
<P>Developed by <A HREF="mailto:fernando_cacciola@hotmail.com">Fernando Cacciola</A>,
|
||||
the latest version of this file can be found at <A
|
||||
HREF="http://www.boost.org">www.boost.org</A>, and the boost <A HREF="http://www.boost.org/more/mailing_lists.htm#main">discussion lists</A></P>
|
||||
</pre></BODY>
|
||||
</HTML>
|
||||
</HTML>
|
||||
131
doc/optional.qbk
131
doc/optional.qbk
@ -1,131 +0,0 @@
|
||||
[library Boost.Optional
|
||||
[quickbook 1.4]
|
||||
[authors [Cacciola Carballal, Fernando Luis]]
|
||||
[copyright 2003-2007 Fernando Luis Cacciola Carballal]
|
||||
[category miscellaneous]
|
||||
[id optional]
|
||||
[dirname optional]
|
||||
[purpose
|
||||
Discriminated-union wrapper for optional values
|
||||
]
|
||||
[source-mode c++]
|
||||
[license
|
||||
Distributed under the Boost Software License, Version 1.0.
|
||||
(See accompanying file LICENSE_1_0.txt or copy at
|
||||
[@http://www.boost.org/LICENSE_1_0.txt])
|
||||
]
|
||||
]
|
||||
|
||||
[/ Macros will be used for links so we have a central place to change them ]
|
||||
|
||||
|
||||
[/ Cited Boost resources ]
|
||||
|
||||
[def __BOOST_VARIANT__ [@../../../variant/index.html Boost.Variant]]
|
||||
[def __BOOST_TRIBOOL__ [@../../../tribool/index.html boost::tribool]]
|
||||
|
||||
[def __OPTIONAL_POINTEE__ [@../../../utility/OptionalPointee.html OptionalPointee]]
|
||||
[def __COPY_CONSTRUCTIBLE__ [@../../../utility/CopyConstructible.html Copy Constructible]]
|
||||
[def __FUNCTION_EQUAL_POINTEES__ [@../../../utility/OptionalPointee.html#equal `equal_pointees()`]]
|
||||
[def __FUNCTION_LESS_POINTEES__ [@../../../utility/OptionalPointee.html#less `less_pointees()`]]
|
||||
|
||||
[def __IN_PLACE_FACTORY_HPP__ [@../../../../boost/utility/in_place_factory.hpp in_place_factory.hpp]]
|
||||
[def __TYPED_IN_PLACE_FACTORY_HPP__ [@../../../../boost/utility/typed_in_place_factory.hpp typed_in_place_factory.hpp]]
|
||||
|
||||
[/ Other web resources ]
|
||||
|
||||
[def __HASKELL__ [@http://www.haskell.org/ Haskell]]
|
||||
[def __SGI_DEFAULT_CONSTRUCTIBLE__ [@http://www.sgi.com/tech/stl/DefaultConstructible.html Default Constructible]]
|
||||
|
||||
|
||||
[/ Icons ]
|
||||
|
||||
[def __NOTE__ [$images/note.png]]
|
||||
[def __ALERT__ [$images/caution.png]]
|
||||
[def __DETAIL__ [$images/note.png]]
|
||||
[def __TIP__ [$images/tip.png]]
|
||||
[def __QUESTION_MARK__ [$images/question.png]]
|
||||
[def __SPACE__ [$images/space.png]]
|
||||
[def __GO_TO__ [$images/callouts/R.png]]
|
||||
|
||||
|
||||
[section Motivation]
|
||||
|
||||
Consider these functions which should return a value but which might not have
|
||||
a value to return:
|
||||
|
||||
* (A) `double sqrt(double n );`
|
||||
* (B) `char get_async_input();`
|
||||
* (C) `point polygon::get_any_point_effectively_inside();`
|
||||
|
||||
There are different approaches to the issue of not having a value to return.
|
||||
|
||||
A typical approach is to consider the existence of a valid return value as a
|
||||
postcondition, so that if the function cannot compute the value to return, it
|
||||
has either undefined behavior (and can use assert in a debug build) or uses a
|
||||
runtime check and throws an exception if the postcondition is violated. This
|
||||
is a reasonable choice for example, for function (A), because the lack of a
|
||||
proper return value is directly related to an invalid parameter (out of domain
|
||||
argument), so it is appropriate to require the callee to supply only parameters
|
||||
in a valid domain for execution to continue normally.
|
||||
|
||||
However, function (B), because of its asynchronous nature, does not fail just
|
||||
because it can't find a value to return; so it is incorrect to consider such
|
||||
a situation an error and assert or throw an exception. This function must
|
||||
return, and somehow, must tell the callee that it is not returning a meaningful
|
||||
value.
|
||||
|
||||
A similar situation occurs with function (C): it is conceptually an error to
|
||||
ask a ['null-area] polygon to return a point inside itself, but in many
|
||||
applications, it is just impractical for performance reasons to treat this as
|
||||
an error (because detecting that the polygon has no area might be too expensive
|
||||
to be required to be tested previously), and either an arbitrary point
|
||||
(typically at infinity) is returned, or some efficient way to tell the callee
|
||||
that there is no such point is used.
|
||||
|
||||
There are various mechanisms to let functions communicate that the returned
|
||||
value is not valid. One such mechanism, which is quite common since it has
|
||||
zero or negligible overhead, is to use a special value which is reserved to
|
||||
communicate this. Classical examples of such special values are `EOF`,
|
||||
`string::npos`, points at infinity, etc...
|
||||
|
||||
When those values exist, i.e. the return type can hold all meaningful values
|
||||
['plus] the ['signal] value, this mechanism is quite appropriate and well known.
|
||||
Unfortunately, there are cases when such values do not exist. In these cases,
|
||||
the usual alternative is either to use a wider type, such as `int` in place of
|
||||
`char`; or a compound type, such as `std::pair<point,bool>`.
|
||||
|
||||
Returning a `std::pair<T,bool>`, thus attaching a boolean flag to the result
|
||||
which indicates if the result is meaningful, has the advantage that can be
|
||||
turned into a consistent idiom since the first element of the pair can be
|
||||
whatever the function would conceptually return. For example, the last two
|
||||
functions could have the following interface:
|
||||
|
||||
std::pair<char,bool> get_async_input();
|
||||
std::pair<point,bool> polygon::get_any_point_effectively_inside();
|
||||
|
||||
These functions use a consistent interface for dealing with possibly inexistent
|
||||
results:
|
||||
|
||||
std::pair<point,bool> p = poly.get_any_point_effectively_inside();
|
||||
if ( p.second )
|
||||
flood_fill(p.first);
|
||||
|
||||
However, not only is this quite a burden syntactically, it is also error prone
|
||||
since the user can easily use the function result (first element of the pair)
|
||||
without ever checking if it has a valid value.
|
||||
|
||||
Clearly, we need a better idiom.
|
||||
|
||||
[endsect]
|
||||
|
||||
|
||||
[include development.qbk]
|
||||
[include reference.qbk]
|
||||
[include examples.qbk]
|
||||
[include special_cases.qbk]
|
||||
[include implementation_notes.qbk]
|
||||
[include dependencies.qbk]
|
||||
[include acknowledgments.qbk]
|
||||
|
||||
|
||||
@ -1,880 +0,0 @@
|
||||
[/
|
||||
Boost.Optional
|
||||
|
||||
Copyright (c) 2003-2007 Fernando Luis Cacciola Carballal
|
||||
|
||||
Distributed under the Boost Software License, Version 1.0.
|
||||
(See accompanying file LICENSE_1_0.txt or copy at
|
||||
http://www.boost.org/LICENSE_1_0.txt)
|
||||
]
|
||||
|
||||
|
||||
[section Synopsis]
|
||||
|
||||
namespace boost {
|
||||
|
||||
template<class T>
|
||||
class optional
|
||||
{
|
||||
public :
|
||||
|
||||
// (If T is of reference type, the parameters and results by reference are by value)
|
||||
|
||||
optional () ; ``[link reference_optional_constructor __GO_TO__]``
|
||||
|
||||
optional ( none_t ) ; ``[link reference_optional_constructor_none_t __GO_TO__]``
|
||||
|
||||
optional ( T const& v ) ; ``[link reference_optional_constructor_value __GO_TO__]``
|
||||
|
||||
// [new in 1.34]
|
||||
optional ( bool condition, T const& v ) ; ``[link reference_optional_constructor_bool_value __GO_TO__]``
|
||||
|
||||
optional ( optional const& rhs ) ; ``[link reference_optional_constructor_optional __GO_TO__]``
|
||||
|
||||
template<class U> explicit optional ( optional<U> const& rhs ) ; ``[link reference_optional_constructor_other_optional __GO_TO__]``
|
||||
|
||||
template<class InPlaceFactory> explicit optional ( InPlaceFactory const& f ) ; ``[link reference_optional_constructor_factory __GO_TO__]``
|
||||
|
||||
template<class TypedInPlaceFactory> explicit optional ( TypedInPlaceFactory const& f ) ; ``[link reference_optional_constructor_factory __GO_TO__]``
|
||||
|
||||
optional& operator = ( none_t ) ; ``[/[link reference_optional_operator_equal_none_t __GO_TO__]]``
|
||||
|
||||
optional& operator = ( T const& v ) ; ``[link reference_optional_operator_equal_value __GO_TO__]``
|
||||
|
||||
optional& operator = ( optional const& rhs ) ; ``[link reference_optional_operator_equal_optional __GO_TO__]``
|
||||
|
||||
template<class U> optional& operator = ( optional<U> const& rhs ) ; ``[link reference_optional_operator_equal_other_optional __GO_TO__]``
|
||||
|
||||
template<class InPlaceFactory> optional& operator = ( InPlaceFactory const& f ) ; ``[/[link reference_optional_operator_equal_factory __GO_TO__]]``
|
||||
|
||||
template<class TypedInPlaceFactory> optional& operator = ( TypedInPlaceFactory const& f ) ; ``[/[link reference_optional_operator_equal_factory __GO_TO__]]``
|
||||
|
||||
T const& get() const ; ``[link reference_optional_get __GO_TO__]``
|
||||
T& get() ; ``[link reference_optional_get __GO_TO__]``
|
||||
|
||||
// [new in 1.34]
|
||||
T const& get_value_or( T const& default ) const ; ``[link reference_optional_get_value_or_value __GO_TO__]``
|
||||
|
||||
T const* operator ->() const ; ``[link reference_optional_operator_arrow __GO_TO__]``
|
||||
T* operator ->() ; ``[link reference_optional_operator_arrow __GO_TO__]``
|
||||
|
||||
T const& operator *() const ; ``[link reference_optional_get __GO_TO__]``
|
||||
T& operator *() ; ``[link reference_optional_get __GO_TO__]``
|
||||
|
||||
T const* get_ptr() const ; ``[link reference_optional_get_ptr __GO_TO__]``
|
||||
T* get_ptr() ; ``[link reference_optional_get_ptr __GO_TO__]``
|
||||
|
||||
operator unspecified-bool-type() const ; ``[link reference_optional_operator_bool __GO_TO__]``
|
||||
|
||||
bool operator!() const ; ``[link reference_optional_operator_not __GO_TO__]``
|
||||
|
||||
// deprecated methods
|
||||
|
||||
// (deprecated)
|
||||
void reset() ; ``[link reference_optional_reset __GO_TO__]``
|
||||
|
||||
// (deprecated)
|
||||
void reset ( T const& ) ; ``[link reference_optional_reset_value __GO_TO__]``
|
||||
|
||||
// (deprecated)
|
||||
bool is_initialized() const ; ``[link reference_optional_is_initialized __GO_TO__]``
|
||||
|
||||
};
|
||||
|
||||
template<class T> inline bool operator == ( optional<T> const& x, optional<T> const& y ) ; ``[link reference_operator_compare_equal_optional_optional __GO_TO__]``
|
||||
|
||||
template<class T> inline bool operator != ( optional<T> const& x, optional<T> const& y ) ; ``[link reference_operator_compare_not_equal_optional_optional __GO_TO__]``
|
||||
|
||||
template<class T> inline bool operator < ( optional<T> const& x, optional<T> const& y ) ; ``[link reference_operator_compare_less_optional_optional __GO_TO__]``
|
||||
|
||||
template<class T> inline bool operator > ( optional<T> const& x, optional<T> const& y ) ; ``[link reference_operator_compare_greater_optional_optional __GO_TO__]``
|
||||
|
||||
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__]``
|
||||
|
||||
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__]``
|
||||
|
||||
// [new in 1.34]
|
||||
template<class T> inline optional<T> make_optional ( T const& v ) ; ``[link reference_make_optional_value __GO_TO__]``
|
||||
|
||||
// [new in 1.34]
|
||||
template<class T> inline optional<T> make_optional ( bool condition, T const& v ) ; ``[link reference_make_optional_bool_value __GO_TO__]``
|
||||
|
||||
// [new in 1.34]
|
||||
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__]``
|
||||
|
||||
template<class T> inline T const& get ( optional<T> const& opt ) ; ``[link reference_optional_get __GO_TO__]``
|
||||
|
||||
template<class T> inline T& get ( optional<T> & opt ) ; ``[link reference_optional_get __GO_TO__]``
|
||||
|
||||
template<class T> inline T const* get ( optional<T> const* opt ) ; ``[link reference_optional_get __GO_TO__]``
|
||||
|
||||
template<class T> inline T* get ( optional<T>* opt ) ; ``[link reference_optional_get __GO_TO__]``
|
||||
|
||||
template<class T> inline T const* get_pointer ( optional<T> const& opt ) ; ``[link reference_optional_get_ptr __GO_TO__]``
|
||||
|
||||
template<class T> inline T* get_pointer ( optional<T> & opt ) ; ``[link reference_optional_get_ptr __GO_TO__]``
|
||||
|
||||
template<class T> inline void swap( optional<T>& x, optional<T>& y ) ; ``[link reference_swap_optional_optional __GO_TO__]``
|
||||
|
||||
} // namespace boost
|
||||
|
||||
|
||||
[endsect]
|
||||
|
||||
[section Detailed Semantics]
|
||||
|
||||
Because `T` might be of reference type, in the sequel, those entries whose
|
||||
semantic depends on `T` being of reference type or not will be distinguished
|
||||
using the following convention:
|
||||
* If the entry reads: `optional<T`['(not a ref)]`>`, the description
|
||||
corresponds only to the case where `T` is not of reference type.
|
||||
* If the entry reads: `optional<T&>`, the description corresponds only to
|
||||
the case where `T` is of reference type.
|
||||
* If the entry reads: `optional<T>`, the description is the same for both
|
||||
cases.
|
||||
|
||||
[note
|
||||
The following section contains various `assert()` which are used only to show
|
||||
the postconditions as sample code. It is not implied that the type `T` must
|
||||
support each particular expression but that if the expression is supported,
|
||||
the implied condition holds.
|
||||
]
|
||||
|
||||
__SPACE__
|
||||
|
||||
[heading optional class member functions]
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_constructor]
|
||||
|
||||
[: `optional<T>::optional();`]
|
||||
|
||||
* [*Effect:] Default-Constructs an `optional`.
|
||||
* [*Postconditions:] `*this` is [_uninitialized].
|
||||
* [*Throws:] Nothing.
|
||||
* Notes: T's default constructor [_is not] called.
|
||||
* [*Example:]
|
||||
``
|
||||
optional<T> def ;
|
||||
assert ( !def ) ;
|
||||
``
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_constructor_none_t]
|
||||
|
||||
[: `optional<T>::optional( none_t );`]
|
||||
|
||||
* [*Effect:] Constructs an `optional` uninitialized.
|
||||
* [*Postconditions:] `*this` is [_uninitialized].
|
||||
* [*Throws:] Nothing.
|
||||
* [*Notes:] `T`'s default constructor [_is not] called. The expression
|
||||
`boost::none` denotes an instance of `boost::none_t` that can be used as
|
||||
the parameter.
|
||||
* [*Example:]
|
||||
``
|
||||
#include <boost/none.hpp>
|
||||
optional<T> n(none) ;
|
||||
assert ( !n ) ;
|
||||
``
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_constructor_value]
|
||||
|
||||
[: `optional<T `['(not a ref)]`>::optional( T const& v )`]
|
||||
|
||||
* [*Effect:] Directly-Constructs an `optional`.
|
||||
* [*Postconditions:] `*this` is [_initialized] and its value is a['copy]
|
||||
of `v`.
|
||||
* [*Throws:] Whatever `T::T( T const& )` throws.
|
||||
* [*Notes: ] `T::T( T const& )` is called.
|
||||
* [*Exception Safety:] Exceptions can only be thrown during
|
||||
`T::T( T const& );` in that case, this constructor has no effect.
|
||||
* [*Example:]
|
||||
``
|
||||
T v;
|
||||
optional<T> opt(v);
|
||||
assert ( *opt == v ) ;
|
||||
``
|
||||
|
||||
__SPACE__
|
||||
|
||||
[: `optional<T&>::optional( T& ref )`]
|
||||
|
||||
* [*Effect:] Directly-Constructs an `optional`.
|
||||
* [*Postconditions:] `*this` is [_initialized] and its value is an instance
|
||||
of an internal type wrapping the reference `ref`.
|
||||
* [*Throws:] Nothing.
|
||||
* [*Example:]
|
||||
``
|
||||
T v;
|
||||
T& vref = v ;
|
||||
optional<T&> opt(vref);
|
||||
assert ( *opt == v ) ;
|
||||
++ v ; // mutate referee
|
||||
assert (*opt == v);
|
||||
``
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_constructor_bool_value]
|
||||
|
||||
[: `optional<T` ['(not a ref)]`>::optional( bool condition, T const& v ) ;` ]
|
||||
[: `optional<T&> ::optional( bool condition, T& v ) ;` ]
|
||||
|
||||
* If condition is true, same as:
|
||||
|
||||
[: `optional<T` ['(not a ref)]`>::optional( T const& v )`]
|
||||
[: `optional<T&> ::optional( T& v )`]
|
||||
|
||||
* otherwise, same as:
|
||||
|
||||
[: `optional<T ['(not a ref)]>::optional()`]
|
||||
[: `optional<T&> ::optional()`]
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_constructor_optional]
|
||||
|
||||
[: `optional<T `['(not a ref)]`>::optional( optional const& rhs );`]
|
||||
|
||||
* [*Effect:] Copy-Constructs an `optional`.
|
||||
* [*Postconditions:] If rhs is initialized, `*this` is initialized and
|
||||
its value is a ['copy] of the value of `rhs`; else `*this` is uninitialized.
|
||||
* [*Throws:] Whatever `T::T( T const& )` throws.
|
||||
* [*Notes:] If rhs is initialized, `T::T(T const& )` is called.
|
||||
* [*Exception Safety:] Exceptions can only be thrown during
|
||||
`T::T( T const& );` in that case, this constructor has no effect.
|
||||
* [*Example:]
|
||||
``
|
||||
optional<T> uninit ;
|
||||
assert (!uninit);
|
||||
|
||||
optional<T> uinit2 ( uninit ) ;
|
||||
assert ( uninit2 == uninit );
|
||||
|
||||
optional<T> init( T(2) );
|
||||
assert ( *init == T(2) ) ;
|
||||
|
||||
optional<T> init2 ( init ) ;
|
||||
assert ( init2 == init ) ;
|
||||
``
|
||||
|
||||
__SPACE__
|
||||
|
||||
[: `optional<T&>::optional( optional const& rhs );`]
|
||||
|
||||
* [*Effect:] Copy-Constructs an `optional`.
|
||||
* [*Postconditions:] If `rhs` is initialized, `*this` is initialized and its
|
||||
value is another reference to the same object referenced by `*rhs`; else
|
||||
`*this` is uninitialized.
|
||||
* [*Throws:] Nothing.
|
||||
* [*Notes:] If `rhs` is initialized, both `*this` and `*rhs` will reefer to the
|
||||
same object (they alias).
|
||||
* [*Example:]
|
||||
``
|
||||
optional<T&> uninit ;
|
||||
assert (!uninit);
|
||||
|
||||
optional<T&> uinit2 ( uninit ) ;
|
||||
assert ( uninit2 == uninit );
|
||||
|
||||
T v = 2 ; T& ref = v ;
|
||||
optional<T> init(ref);
|
||||
assert ( *init == v ) ;
|
||||
|
||||
optional<T> init2 ( init ) ;
|
||||
assert ( *init2 == v ) ;
|
||||
|
||||
v = 3 ;
|
||||
|
||||
assert ( *init == 3 ) ;
|
||||
assert ( *init2 == 3 ) ;
|
||||
``
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_constructor_other_optional]
|
||||
|
||||
[: `template<U> explicit optional<T` ['(not a ref)]`>::optional( optional<U> const& rhs );`]
|
||||
|
||||
* [*Effect:] Copy-Constructs an `optional`.
|
||||
* [*Postconditions:] If `rhs` is initialized, `*this` is initialized and its
|
||||
value is a ['copy] of the value of rhs converted to type `T`; else `*this` is
|
||||
uninitialized.
|
||||
* [*Throws:] Whatever `T::T( U const& )` throws.
|
||||
* [*Notes: ] `T::T( U const& )` is called if `rhs` is initialized, which requires a
|
||||
valid conversion from `U` to `T`.
|
||||
* [*Exception Safety:] Exceptions can only be thrown during `T::T( U const& );`
|
||||
in that case, this constructor has no effect.
|
||||
* [*Example:]
|
||||
``
|
||||
optional<double> x(123.4);
|
||||
assert ( *x == 123.4 ) ;
|
||||
|
||||
optional<int> y(x) ;
|
||||
assert( *y == 123 ) ;
|
||||
``
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_constructor_factory]
|
||||
|
||||
[: `template<InPlaceFactory> explicit optional<T` ['(not a ref)]`>::optional( InPlaceFactory const& f );`]
|
||||
[: `template<TypedInPlaceFactory> explicit optional<T` ['(not a ref)]`>::optional( TypedInPlaceFactory const& f );`]
|
||||
|
||||
* [*Effect:] Constructs an `optional` with a value of `T` obtained from the
|
||||
factory.
|
||||
* [*Postconditions: ] `*this` is [_initialized] and its value is ['directly given]
|
||||
from the factory `f` (i.e., the value [_is not copied]).
|
||||
* [*Throws:] Whatever the `T` constructor called by the factory throws.
|
||||
* [*Notes:] See [link optional_in_place_factories In-Place Factories]
|
||||
* [*Exception Safety:] Exceptions can only be thrown during the call to
|
||||
the `T` constructor used by the factory; in that case, this constructor has
|
||||
no effect.
|
||||
* [*Example:]
|
||||
``
|
||||
class C { C ( char, double, std::string ) ; } ;
|
||||
|
||||
C v('A',123.4,"hello");
|
||||
|
||||
optional<C> x( in_place ('A', 123.4, "hello") ); // InPlaceFactory used
|
||||
optional<C> y( in_place<C>('A', 123.4, "hello") ); // TypedInPlaceFactory used
|
||||
|
||||
assert ( *x == v ) ;
|
||||
assert ( *y == v ) ;
|
||||
``
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_operator_equal_value]
|
||||
|
||||
[: `optional& optional<T` ['(not a ref)]`>::operator= ( T const& rhs ) ;`]
|
||||
|
||||
* [*Effect:] Assigns the value `rhs` to an `optional`.
|
||||
* [*Postconditions: ] `*this` is initialized and its value is a ['copy] of `rhs`.
|
||||
* [*Throws:] Whatever `T::operator=( T const& )` or `T::T(T const&)` throws.
|
||||
* [*Notes:] If `*this` was initialized, `T`'s assignment operator is used,
|
||||
otherwise, its copy-constructor is used.
|
||||
* [*Exception Safety:] In the event of an exception, the initialization
|
||||
state of `*this` is unchanged and its value unspecified as far as `optional`
|
||||
is concerned (it is up to `T`'s `operator=()`). If `*this` is initially
|
||||
uninitialized and `T`'s ['copy constructor] fails, `*this` is left properly
|
||||
uninitialized.
|
||||
* [*Example:]
|
||||
``
|
||||
T x;
|
||||
optional<T> def ;
|
||||
optional<T> opt(x) ;
|
||||
|
||||
T y;
|
||||
def = y ;
|
||||
assert ( *def == y ) ;
|
||||
opt = y ;
|
||||
assert ( *opt == y ) ;
|
||||
``
|
||||
|
||||
__SPACE__
|
||||
|
||||
[: `optional<T&>& optional<T&>::operator= ( T& const& rhs ) ;`]
|
||||
|
||||
* [*Effect:] (Re)binds thee wrapped reference.
|
||||
* [*Postconditions: ] `*this` is initialized and it references the same
|
||||
object referenced by `rhs`.
|
||||
* [*Notes:] If `*this` was initialized, is is ['rebound] to the new object.
|
||||
See [link optional_refassign here] for details on this behavior.
|
||||
* [*Example:]
|
||||
``
|
||||
int a = 1 ;
|
||||
int b = 2 ;
|
||||
T& ra = a ;
|
||||
T& rb = b ;
|
||||
optional<int&> def ;
|
||||
optional<int&> opt(ra) ;
|
||||
|
||||
def = rb ; // binds 'def' to 'b' through 'rb'
|
||||
assert ( *def == b ) ;
|
||||
*def = a ; // changes the value of 'b' to a copy of the value of 'a'
|
||||
assert ( b == a ) ;
|
||||
int c = 3;
|
||||
int& rc = c ;
|
||||
opt = rc ; // REBINDS to 'c' through 'rc'
|
||||
c = 4 ;
|
||||
assert ( *opt == 4 ) ;
|
||||
``
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_operator_equal_optional]
|
||||
|
||||
[: `optional& optional<T` ['(not a ref)]`>::operator= ( optional const& rhs ) ;`]
|
||||
|
||||
* [*Effect:] Assigns another `optional` to an `optional`.
|
||||
* [*Postconditions:] If `rhs` is initialized, `*this` is initialized and
|
||||
its value is a ['copy] of the value of `rhs`; else `*this` is uninitialized.
|
||||
* [*Throws:] Whatever `T::operator( T const&)` or `T::T( T const& )` throws.
|
||||
* [*Notes:] If both `*this` and `rhs` are initially initialized, `T`'s
|
||||
['assignment operator] is used. If `*this` is initially initialized but `rhs` is
|
||||
uninitialized, `T`'s [destructor] is called. If `*this` is initially uninitialized
|
||||
but `rhs` is initialized, `T`'s ['copy constructor] is called.
|
||||
* [*Exception Safety:] In the event of an exception, the initialization state of
|
||||
`*this` is unchanged and its value unspecified as far as optional is concerned
|
||||
(it is up to `T`'s `operator=()`). If `*this` is initially uninitialized and
|
||||
`T`'s ['copy constructor] fails, `*this` is left properly uninitialized.
|
||||
* [*Example:]
|
||||
``
|
||||
T v;
|
||||
optional<T> opt(v);
|
||||
optional<T> def ;
|
||||
|
||||
opt = def ;
|
||||
assert ( !def ) ;
|
||||
// previous value (copy of 'v') destroyed from within 'opt'.
|
||||
``
|
||||
|
||||
__SPACE__
|
||||
|
||||
[: `optional<T&> & optional<T&>::operator= ( optional<T&> const& rhs ) ;`]
|
||||
|
||||
* [*Effect:] (Re)binds thee wrapped reference.
|
||||
* [*Postconditions:] If `*rhs` is initialized, `*this` is initialized and it
|
||||
references the same object referenced by `*rhs`; otherwise, `*this` is
|
||||
uninitialized (and references no object).
|
||||
* [*Notes:] If `*this` was initialized and so is *rhs, this is is ['rebound] to
|
||||
the new object. See [link optional_refassign here] for details on this behavior.
|
||||
* [*Example:]
|
||||
``
|
||||
int a = 1 ;
|
||||
int b = 2 ;
|
||||
T& ra = a ;
|
||||
T& rb = b ;
|
||||
optional<int&> def ;
|
||||
optional<int&> ora(ra) ;
|
||||
optional<int&> orb(rb) ;
|
||||
|
||||
def = orb ; // binds 'def' to 'b' through 'rb' wrapped within 'orb'
|
||||
assert ( *def == b ) ;
|
||||
*def = ora ; // changes the value of 'b' to a copy of the value of 'a'
|
||||
assert ( b == a ) ;
|
||||
int c = 3;
|
||||
int& rc = c ;
|
||||
optional<int&> orc(rc) ;
|
||||
ora = orc ; // REBINDS ora to 'c' through 'rc'
|
||||
c = 4 ;
|
||||
assert ( *ora == 4 ) ;
|
||||
``
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_operator_equal_other_optional]
|
||||
|
||||
[: `template<U> optional& optional<T` ['(not a ref)]`>::operator= ( optional<U> const& rhs ) ;`]
|
||||
|
||||
* [*Effect:] Assigns another convertible optional to an optional.
|
||||
* [*Postconditions:] If `rhs` is initialized, `*this` is initialized and
|
||||
its value is a ['copy] of the value of `rhs` ['converted] to type `T`; else
|
||||
`*this` is uninitialized.
|
||||
* [*Throws:] Whatever `T::operator=( U const& )` or `T::T( U const& )` throws.
|
||||
* [*Notes:] If both `*this` and rhs are initially initialized, `T`'s
|
||||
['assignment operator] (from `U`) is used. If `*this` is initially initialized
|
||||
but `rhs` is uninitialized, `T`'s ['destructor] is called. If `*this` is
|
||||
initially uninitialized but rhs is initialized, `T`'s ['converting constructor]
|
||||
(from `U`) is called.
|
||||
* [*Exception Safety:] In the event of an exception, the initialization state
|
||||
of `*this` is unchanged and its value unspecified as far as optional is
|
||||
concerned (it is up to `T`'s `operator=()`). If `*this` is initially
|
||||
uninitialized and `T`'s converting constructor fails, `*this` is left properly
|
||||
uninitialized.
|
||||
* [*Example:]
|
||||
``
|
||||
T v;
|
||||
optional<T> opt0(v);
|
||||
optional<U> opt1;
|
||||
|
||||
opt1 = opt0 ;
|
||||
assert ( *opt1 == static_cast<U>(v) ) ;
|
||||
``
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_reset_value]
|
||||
|
||||
[: `void optional<T` ['(not a ref)]`>::reset( T const& v ) ;`]
|
||||
* [*Deprecated:] same as `operator= ( T const& v) ;`
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_reset]
|
||||
|
||||
[: `void optional<T>::reset() ;`]
|
||||
* [*Deprecated:] Same as `operator=( detail::none_t );`
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_get]
|
||||
|
||||
[: `T const& optional<T` ['(not a ref)]`>::operator*() const ;`]
|
||||
[: `T& optional<T` ['(not a ref)]`>::operator*();`]
|
||||
[: `T const& optional<T` ['(not a ref)]`>::get() const ;`]
|
||||
[: `T& optional<T` ['(not a ref)]`>::get() ;`]
|
||||
|
||||
[: `inline T const& get ( optional<T` ['(not a ref)]`> const& ) ;`]
|
||||
[: `inline T& get ( optional<T` ['(not a ref)]`> &) ;`]
|
||||
|
||||
* [*Requirements:] `*this` is initialized
|
||||
* [*Returns:] A reference to the contained value
|
||||
* [*Throws:] Nothing.
|
||||
* [*Notes:] The requirement is asserted via `BOOST_ASSERT()`.
|
||||
* [*Example:]
|
||||
``
|
||||
T v ;
|
||||
optional<T> opt ( v );
|
||||
T const& u = *opt;
|
||||
assert ( u == v ) ;
|
||||
T w ;
|
||||
*opt = w ;
|
||||
assert ( *opt == w ) ;
|
||||
``
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_get_value_or_value]
|
||||
|
||||
[: `T const& optional<T` ['(not a ref)]`>::get_value_or( T const& default) const ;`]
|
||||
[: `T& optional<T` ['(not a ref)]`>::get_value_or( T& default ) ;`]
|
||||
|
||||
[: `inline T const& get_optional_value_or ( optional<T` ['(not a ref)]`> const& o, T const& default ) ;`]
|
||||
[: `inline T& get_optional_value_or ( optional<T` ['(not a ref)]`>& o, T& default ) ;`]
|
||||
|
||||
* [*Returns:] A reference to the contained value, if any, or `default`.
|
||||
* [*Throws:] Nothing.
|
||||
* [*Example:]
|
||||
``
|
||||
T v, z ;
|
||||
optional<T> def;
|
||||
T const& y = def.get_value_or(z);
|
||||
assert ( y == z ) ;
|
||||
|
||||
optional<T> opt ( v );
|
||||
T const& u = get_optional_value_or(opt,z);
|
||||
assert ( u == v ) ;
|
||||
assert ( u != z ) ;
|
||||
``
|
||||
|
||||
__SPACE__
|
||||
|
||||
[: `T const& optional<T&>::operator*() const ;`]
|
||||
[: `T & optional<T&>::operator*();`]
|
||||
[: `T const& optional<T&>::get() const ;`]
|
||||
[: `T& optional<T&>::get() ;`]
|
||||
|
||||
[: `inline T const& get ( optional<T&> const& ) ;`]
|
||||
[: `inline T& get ( optional<T&> &) ;`]
|
||||
|
||||
* [*Requirements: ] `*this` is initialized
|
||||
* [*Returns:] [_The] reference contained.
|
||||
* [*Throws:] Nothing.
|
||||
* [*Notes:] The requirement is asserted via `BOOST_ASSERT()`.
|
||||
* [*Example:]
|
||||
``
|
||||
T v ;
|
||||
T& vref = v ;
|
||||
optional<T&> opt ( vref );
|
||||
T const& vref2 = *opt;
|
||||
assert ( vref2 == v ) ;
|
||||
++ v ;
|
||||
assert ( *opt == v ) ;
|
||||
``
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_get_ptr]
|
||||
|
||||
[: `T const* optional<T` ['(not a ref)]`>::get_ptr() const ;`]
|
||||
[: `T* optional<T` ['(not a ref)]`>::get_ptr() ;`]
|
||||
|
||||
[: `inline T const* get_pointer ( optional<T` ['(not a ref)]`> const& ) ;`]
|
||||
[: `inline T* get_pointer ( optional<T` ['(not a ref)]`> &) ;`]
|
||||
|
||||
* [*Returns:] If `*this` is initialized, a pointer to the contained value;
|
||||
else `0` (['null]).
|
||||
* [*Throws:] Nothing.
|
||||
* [*Notes:] The contained value is permanently stored within `*this`, so you
|
||||
should not hold nor delete this pointer
|
||||
* [*Example:]
|
||||
``
|
||||
T v;
|
||||
optional<T> opt(v);
|
||||
optional<T> const copt(v);
|
||||
T* p = opt.get_ptr() ;
|
||||
T const* cp = copt.get_ptr();
|
||||
assert ( p == get_pointer(opt) );
|
||||
assert ( cp == get_pointer(copt) ) ;
|
||||
``
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_operator_arrow]
|
||||
|
||||
[: `T const* optional<T` ['(not a ref)]`>::operator ->() const ;`]
|
||||
[: `T* optional<T` ['(not a ref)]`>::operator ->() ;`]
|
||||
|
||||
* [*Requirements: ] `*this` is initialized.
|
||||
* [*Returns:] A pointer to the contained value.
|
||||
* [*Throws:] Nothing.
|
||||
* [*Notes:] The requirement is asserted via `BOOST_ASSERT()`.
|
||||
* [*Example:]
|
||||
``
|
||||
struct X { int mdata ; } ;
|
||||
X x ;
|
||||
optional<X> opt (x);
|
||||
opt->mdata = 2 ;
|
||||
``
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_operator_bool]
|
||||
|
||||
[: `optional<T>::operator `['unspecified-bool-type]`() const ;`]
|
||||
|
||||
* [*Returns:] An unspecified value which if used on a boolean context
|
||||
is equivalent to (`get() != 0`)
|
||||
* [*Throws:] Nothing.
|
||||
* [*Example:]
|
||||
``
|
||||
optional<T> def ;
|
||||
assert ( def == 0 );
|
||||
optional<T> opt ( v ) ;
|
||||
assert ( opt );
|
||||
assert ( opt != 0 );
|
||||
``
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_operator_not]
|
||||
|
||||
[: `bool optional<T>::operator!() ;`]
|
||||
|
||||
* [*Returns:] If `*this` is uninitialized, `true`; else `false`.
|
||||
* [*Throws:] Nothing.
|
||||
* [*Notes:] This operator is provided for those compilers which can't
|
||||
use the ['unspecified-bool-type operator] in certain boolean contexts.
|
||||
* [*Example:]
|
||||
``
|
||||
optional<T> opt ;
|
||||
assert ( !opt );
|
||||
*opt = some_T ;
|
||||
|
||||
// Notice the "double-bang" idiom here.
|
||||
assert ( !!opt ) ;
|
||||
``
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_is_initialized]
|
||||
|
||||
[: `bool optional<T>::is_initialized() const ;`]
|
||||
|
||||
* [*Returns: ] `true` if the `optional` is initialized, `false` otherwise.
|
||||
* [*Throws:] Nothing.
|
||||
* [*Example:]
|
||||
``
|
||||
optional<T> def ;
|
||||
assert ( !def.is_initialized() );
|
||||
optional<T> opt ( v ) ;
|
||||
assert ( opt.is_initialized() );
|
||||
``
|
||||
|
||||
__SPACE__
|
||||
|
||||
[heading Free functions]
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_make_optional_value]
|
||||
|
||||
[: `optional<T` ['(not a ref)]`> make_optional( T const& v )`]
|
||||
|
||||
* [*Returns: ] `optional<T>(v)` for the ['deduced] type `T` of `v`.
|
||||
* [*Example:]
|
||||
``
|
||||
template<class T> void foo ( optional<T> const& opt ) ;
|
||||
|
||||
foo ( make_optional(1+1) ) ; // Creates an optional<int>
|
||||
``
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_make_optional_bool_value]
|
||||
|
||||
[: `optional<T` ['(not a ref)]`> make_optional( bool condition, T const& v )`]
|
||||
|
||||
* [*Returns: ] `optional<T>(condition,v)` for the ['deduced] type `T` of `v`.
|
||||
* [*Example:]
|
||||
``
|
||||
optional<double> calculate_foo()
|
||||
{
|
||||
double val = compute_foo();
|
||||
return make_optional(is_not_nan_and_finite(val),val);
|
||||
}
|
||||
|
||||
optional<double> v = calculate_foo();
|
||||
if ( !v )
|
||||
error("foo wasn't computed");
|
||||
``
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_operator_compare_equal_optional_optional]
|
||||
|
||||
[: `bool operator == ( optional<T> const& x, optional<T> const& y );`]
|
||||
|
||||
* [*Returns:] If both `x` and `y` are initialized, `(*x == *y)`. If only
|
||||
`x` or `y` is initialized, `false`. If both are uninitialized, `true`.
|
||||
* [*Throws:] Nothing.
|
||||
* [*Notes:] Pointers have shallow relational operators while `optional` has
|
||||
deep relational operators. Do not use `operator ==` directly in generic
|
||||
code which expect to be given either an `optional<T>` or a pointer; use
|
||||
__FUNCTION_EQUAL_POINTEES__ instead
|
||||
* [*Example:]
|
||||
``
|
||||
T x(12);
|
||||
T y(12);
|
||||
T z(21);
|
||||
optional<T> def0 ;
|
||||
optional<T> def1 ;
|
||||
optional<T> optX(x);
|
||||
optional<T> optY(y);
|
||||
optional<T> optZ(z);
|
||||
|
||||
// Identity always hold
|
||||
assert ( def0 == def0 );
|
||||
assert ( optX == optX );
|
||||
|
||||
// Both uninitialized compare equal
|
||||
assert ( def0 == def1 );
|
||||
|
||||
// Only one initialized compare unequal.
|
||||
assert ( def0 != optX );
|
||||
|
||||
// Both initialized compare as (*lhs == *rhs)
|
||||
assert ( optX == optY ) ;
|
||||
assert ( optX != optZ ) ;
|
||||
``
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_operator_compare_less_optional_optional]
|
||||
|
||||
[: `bool operator < ( optional<T> const& x, optional<T> const& y );`]
|
||||
|
||||
* [*Returns:] If `y` is not initialized, `false`. If `y` is initialized
|
||||
and `x` is not initialized, `true`. If both `x` and `y` are initialized,
|
||||
`(*x < *y)`.
|
||||
* [*Throws:] Nothing.
|
||||
* [*Notes:] Pointers have shallow relational operators while `optional` has
|
||||
deep relational operators. Do not use `operator <` directly in generic code
|
||||
which expect to be given either an `optional<T>` or a pointer; use __FUNCTION_LESS_POINTEES__ instead.
|
||||
* [*Example:]
|
||||
``
|
||||
T x(12);
|
||||
T y(34);
|
||||
optional<T> def ;
|
||||
optional<T> optX(x);
|
||||
optional<T> optY(y);
|
||||
|
||||
// Identity always hold
|
||||
assert ( !(def < def) );
|
||||
assert ( optX == optX );
|
||||
|
||||
// Both uninitialized compare equal
|
||||
assert ( def0 == def1 );
|
||||
|
||||
// Only one initialized compare unequal.
|
||||
assert ( def0 != optX );
|
||||
|
||||
// Both initialized compare as (*lhs == *rhs)
|
||||
assert ( optX == optY ) ;
|
||||
assert ( optX != optZ ) ;
|
||||
``
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_operator_compare_not_equal_optional_optional]
|
||||
|
||||
[: `bool operator != ( optional<T> const& x, optional<T> const& y );`]
|
||||
|
||||
* [*Returns: ] `!( x == y );`
|
||||
* [*Throws:] Nothing.
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_operator_compare_greater_optional_optional]
|
||||
|
||||
[: `bool operator > ( optional<T> const& x, optional<T> const& y );`]
|
||||
|
||||
* [*Returns: ] `( y < x );`
|
||||
* [*Throws:] Nothing.
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_operator_compare_less_or_equal_optional_optional]
|
||||
|
||||
[: `bool operator <= ( optional<T> const& x, optional<T> const& y );`]
|
||||
|
||||
* [*Returns: ] `!( y<x );`
|
||||
* [*Throws:] Nothing.
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_operator_compare_greater_or_equal_optional_optional]
|
||||
|
||||
[: `bool operator >= ( optional<T> const& x, optional<T> const& y );`]
|
||||
|
||||
* [*Returns: ] `!( x<y );`
|
||||
* [*Throws:] Nothing.
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_swap_optional_optional]
|
||||
|
||||
[: `void swap ( optional<T>& x, optional<T>& y );`]
|
||||
|
||||
* [*Effect:] If both `x` and `y` are initialized, calls `swap(*x,*y)`
|
||||
using `std::swap`. If only one is initialized, say `x`, calls:
|
||||
`y.reset(*x); x.reset();` If none is initialized, does nothing.
|
||||
* [*Postconditions:] The states of `x` and `y` interchanged.
|
||||
* [*Throws:] If both are initialized, whatever `swap(T&,T&)` throws. If only
|
||||
one is initialized, whatever `T::T ( T const& )` throws.
|
||||
* [*Notes:] If both are initialized, `swap(T&,T&)` is used unqualified but
|
||||
with `std::swap` introduced in scope.
|
||||
If only one is initialized, `T::~T()` and `T::T( T const& )` is called.
|
||||
* [*Exception Safety:] If both are initialized, this operation has the
|
||||
exception safety guarantees of `swap(T&,T&)`.
|
||||
If only one is initialized, it has the same basic guarantee as
|
||||
`optional<T>::reset( T const& )`.
|
||||
* [*Example:]
|
||||
``
|
||||
T x(12);
|
||||
T y(21);
|
||||
optional<T> def0 ;
|
||||
optional<T> def1 ;
|
||||
optional<T> optX(x);
|
||||
optional<T> optY(y);
|
||||
|
||||
boost::swap(def0,def1); // no-op
|
||||
|
||||
boost::swap(def0,optX);
|
||||
assert ( *def0 == x );
|
||||
assert ( !optX );
|
||||
|
||||
boost::swap(def0,optX); // Get back to original values
|
||||
|
||||
boost::swap(optX,optY);
|
||||
assert ( *optX == y );
|
||||
assert ( *optY == x );
|
||||
``
|
||||
|
||||
[endsect]
|
||||
@ -1,376 +0,0 @@
|
||||
|
||||
[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]
|
||||
|
||||
[#optional_refassign]
|
||||
|
||||
[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]
|
||||
|
||||
[#optional_in_place_factories]
|
||||
|
||||
[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&rt(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 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]
|
||||
|
||||
|
||||
@ -1,4 +1,6 @@
|
||||
// Copyright (C) 2003, Fernando Luis Cacciola Carballal.
|
||||
// Copyright (C) 2007, Anthony Williams
|
||||
// Copyright (C) 2007, Steven Watanabe, Richard Smith
|
||||
//
|
||||
// Distributed under the Boost Software License, Version 1.0.
|
||||
// (See accompanying file LICENSE_1_0.txt or copy at
|
||||
@ -7,22 +9,35 @@
|
||||
// See http://www.boost.org/lib/optional/ for documentation.
|
||||
//
|
||||
// You are welcome to contact the author at:
|
||||
// fernando_cacciola@hotmail.com
|
||||
// fernando.cacciola@gmail.com
|
||||
//
|
||||
#ifndef BOOST_NONE_17SEP2003_HPP
|
||||
#define BOOST_NONE_17SEP2003_HPP
|
||||
|
||||
#include "boost/none_t.hpp"
|
||||
namespace boost
|
||||
{
|
||||
namespace detail
|
||||
{
|
||||
class none_helper;
|
||||
}
|
||||
|
||||
// NOTE: Borland users have to include this header outside any precompiled headers
|
||||
// (bcc<=5.64 cannot include instance data in a precompiled header)
|
||||
// -- * To be verified, now that there's no unnamed namespace
|
||||
inline void none(detail::none_helper);
|
||||
|
||||
namespace boost {
|
||||
namespace detail
|
||||
{
|
||||
class none_helper
|
||||
{
|
||||
private:
|
||||
|
||||
none_helper( none_helper const& ) {}
|
||||
|
||||
friend void boost::none(none_helper);
|
||||
};
|
||||
}
|
||||
|
||||
none_t const none = ((none_t)0) ;
|
||||
typedef void (*none_t)(detail::none_helper);
|
||||
|
||||
} // namespace boost
|
||||
inline void none(detail::none_helper) {}
|
||||
}
|
||||
|
||||
#endif
|
||||
|
||||
|
||||
@ -1,24 +0,0 @@
|
||||
// Copyright (C) 2003, Fernando Luis Cacciola Carballal.
|
||||
//
|
||||
// Use, modification, and distribution is subject to the Boost Software
|
||||
// License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
|
||||
// http://www.boost.org/LICENSE_1_0.txt)
|
||||
//
|
||||
// See http://www.boost.org/lib/optional for documentation.
|
||||
//
|
||||
// You are welcome to contact the author at:
|
||||
// fernando_cacciola@hotmail.com
|
||||
//
|
||||
#ifndef BOOST_NONE_T_17SEP2003_HPP
|
||||
#define BOOST_NONE_T_17SEP2003_HPP
|
||||
|
||||
namespace boost {
|
||||
|
||||
namespace detail { struct none_helper{}; }
|
||||
|
||||
typedef int detail::none_helper::*none_t ;
|
||||
|
||||
} // namespace boost
|
||||
|
||||
#endif
|
||||
|
||||
@ -26,7 +26,7 @@
|
||||
#include "boost/mpl/bool.hpp"
|
||||
#include "boost/mpl/not.hpp"
|
||||
#include "boost/detail/reference_content.hpp"
|
||||
#include "boost/none_t.hpp"
|
||||
#include "boost/none.hpp"
|
||||
#include "boost/utility/compare_pointees.hpp"
|
||||
|
||||
#include "boost/optional/optional_fwd.hpp"
|
||||
@ -76,6 +76,19 @@
|
||||
#define BOOST_OPTIONAL_WEAK_OVERLOAD_RESOLUTION
|
||||
#endif
|
||||
|
||||
// Daniel Wallin discovered that bind/apply.hpp badly interacts with the apply<>
|
||||
// member template of a factory as used in the optional<> implementation.
|
||||
// He proposed this simple fix which is to move the call to apply<> outside
|
||||
// namespace boost.
|
||||
namespace boost_optional_detail
|
||||
{
|
||||
template <class T, class Factory>
|
||||
void construct(Factory const& factory, void* address)
|
||||
{
|
||||
factory.BOOST_NESTED_TEMPLATE apply<T>(address);
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
namespace boost {
|
||||
|
||||
@ -173,7 +186,7 @@ class optional_base : public optional_tag
|
||||
|
||||
// Creates an optional<T> uninitialized.
|
||||
// No-throw
|
||||
optional_base ( none_t const& )
|
||||
optional_base ( none_t )
|
||||
:
|
||||
m_initialized(false) {}
|
||||
|
||||
@ -266,7 +279,7 @@ class optional_base : public optional_tag
|
||||
|
||||
// Assigns from "none", destroying the current value, if any, leaving this UNINITIALIZED
|
||||
// No-throw (assuming T::~T() doesn't)
|
||||
void assign ( none_t const& ) { destroy(); }
|
||||
void assign ( none_t ) { destroy(); }
|
||||
|
||||
#ifndef BOOST_OPTIONAL_NO_INPLACE_FACTORY_SUPPORT
|
||||
template<class Expr>
|
||||
@ -309,7 +322,7 @@ class optional_base : public optional_tag
|
||||
void construct ( Expr const& factory, in_place_factory_base const* )
|
||||
{
|
||||
BOOST_STATIC_ASSERT ( ::boost::mpl::not_<is_reference_predicate>::value ) ;
|
||||
factory.BOOST_NESTED_TEMPLATE apply<value_type>(m_storage.address()) ;
|
||||
boost_optional_detail::construct<value_type>(factory, m_storage.address());
|
||||
m_initialized = true ;
|
||||
}
|
||||
|
||||
@ -428,6 +441,8 @@ class optional_base : public optional_tag
|
||||
// the following olverloads are used to filter out the case and guarantee an error in case of T being a reference.
|
||||
pointer_const_type cast_ptr( internal_type const* p, is_not_reference_tag ) const { return p ; }
|
||||
pointer_type cast_ptr( internal_type * p, is_not_reference_tag ) { return p ; }
|
||||
pointer_const_type cast_ptr( internal_type const* p, is_reference_tag ) const { return &p->get() ; }
|
||||
pointer_type cast_ptr( internal_type * p, is_reference_tag ) { return &p->get() ; }
|
||||
|
||||
bool m_initialized ;
|
||||
storage_type m_storage ;
|
||||
@ -459,7 +474,7 @@ class optional : public optional_detail::optional_base<T>
|
||||
|
||||
// Creates an optional<T> uninitialized.
|
||||
// No-throw
|
||||
optional( none_t const& none_ ) : base(none_) {}
|
||||
optional( none_t none_ ) : base(none_) {}
|
||||
|
||||
// Creates an optional<T> initialized with 'val'.
|
||||
// Can throw if T::T(T const&) does
|
||||
@ -550,7 +565,7 @@ class optional : public optional_detail::optional_base<T>
|
||||
// Assigns from a "none"
|
||||
// Which destroys the current value, if any, leaving this UNINITIALIZED
|
||||
// No-throw (assuming T::~T() doesn't)
|
||||
optional& operator= ( none_t const& none_ )
|
||||
optional& operator= ( none_t none_ )
|
||||
{
|
||||
this->assign( none_ ) ;
|
||||
return *this ;
|
||||
@ -678,6 +693,11 @@ get_pointer ( optional<T>& opt )
|
||||
// optional's relational operators ( ==, !=, <, >, <=, >= ) have deep-semantics (compare values).
|
||||
// WARNING: This is UNLIKE pointers. Use equal_pointees()/less_pointess() in generic code instead.
|
||||
|
||||
|
||||
//
|
||||
// optional<T> vs optional<T> cases
|
||||
//
|
||||
|
||||
template<class T>
|
||||
inline
|
||||
bool operator == ( optional<T> const& x, optional<T> const& y )
|
||||
@ -708,64 +728,141 @@ inline
|
||||
bool operator >= ( optional<T> const& x, optional<T> const& y )
|
||||
{ return !( x < y ) ; }
|
||||
|
||||
|
||||
//
|
||||
// optional<T> vs T cases
|
||||
//
|
||||
template<class T>
|
||||
inline
|
||||
bool operator == ( optional<T> const& x, none_t const& )
|
||||
bool operator == ( optional<T> const& x, T const& y )
|
||||
{ return equal_pointees(x, optional<T>(y)); }
|
||||
|
||||
template<class T>
|
||||
inline
|
||||
bool operator < ( optional<T> const& x, T const& y )
|
||||
{ return less_pointees(x, optional<T>(y)); }
|
||||
|
||||
template<class T>
|
||||
inline
|
||||
bool operator != ( optional<T> const& x, T const& y )
|
||||
{ return !( x == y ) ; }
|
||||
|
||||
template<class T>
|
||||
inline
|
||||
bool operator > ( optional<T> const& x, T const& y )
|
||||
{ return y < x ; }
|
||||
|
||||
template<class T>
|
||||
inline
|
||||
bool operator <= ( optional<T> const& x, T const& y )
|
||||
{ return !( y < x ) ; }
|
||||
|
||||
template<class T>
|
||||
inline
|
||||
bool operator >= ( optional<T> const& x, T const& y )
|
||||
{ return !( x < y ) ; }
|
||||
|
||||
//
|
||||
// T vs optional<T> cases
|
||||
//
|
||||
|
||||
template<class T>
|
||||
inline
|
||||
bool operator == ( T const& x, optional<T> const& y )
|
||||
{ return equal_pointees( optional<T>(x), y ); }
|
||||
|
||||
template<class T>
|
||||
inline
|
||||
bool operator < ( T const& x, optional<T> const& y )
|
||||
{ return less_pointees( optional<T>(x), y ); }
|
||||
|
||||
template<class T>
|
||||
inline
|
||||
bool operator != ( T const& x, optional<T> const& y )
|
||||
{ return !( x == y ) ; }
|
||||
|
||||
template<class T>
|
||||
inline
|
||||
bool operator > ( T const& x, optional<T> const& y )
|
||||
{ return y < x ; }
|
||||
|
||||
template<class T>
|
||||
inline
|
||||
bool operator <= ( T const& x, optional<T> const& y )
|
||||
{ return !( y < x ) ; }
|
||||
|
||||
template<class T>
|
||||
inline
|
||||
bool operator >= ( T const& x, optional<T> const& y )
|
||||
{ return !( x < y ) ; }
|
||||
|
||||
|
||||
//
|
||||
// optional<T> vs none cases
|
||||
//
|
||||
|
||||
template<class T>
|
||||
inline
|
||||
bool operator == ( optional<T> const& x, none_t )
|
||||
{ return equal_pointees(x, optional<T>() ); }
|
||||
|
||||
template<class T>
|
||||
inline
|
||||
bool operator < ( optional<T> const& x, none_t const& )
|
||||
bool operator < ( optional<T> const& x, none_t )
|
||||
{ return less_pointees(x,optional<T>() ); }
|
||||
|
||||
template<class T>
|
||||
inline
|
||||
bool operator != ( optional<T> const& x, none_t const& y )
|
||||
bool operator != ( optional<T> const& x, none_t y )
|
||||
{ return !( x == y ) ; }
|
||||
|
||||
template<class T>
|
||||
inline
|
||||
bool operator > ( optional<T> const& x, none_t const& y )
|
||||
bool operator > ( optional<T> const& x, none_t y )
|
||||
{ return y < x ; }
|
||||
|
||||
template<class T>
|
||||
inline
|
||||
bool operator <= ( optional<T> const& x, none_t const& y )
|
||||
bool operator <= ( optional<T> const& x, none_t y )
|
||||
{ return !( y < x ) ; }
|
||||
|
||||
template<class T>
|
||||
inline
|
||||
bool operator >= ( optional<T> const& x, none_t const& y )
|
||||
bool operator >= ( optional<T> const& x, none_t y )
|
||||
{ return !( x < y ) ; }
|
||||
|
||||
//
|
||||
// none vs optional<T> cases
|
||||
//
|
||||
|
||||
template<class T>
|
||||
inline
|
||||
bool operator == ( none_t const& x, optional<T> const& y )
|
||||
bool operator == ( none_t x, optional<T> const& y )
|
||||
{ return equal_pointees(optional<T>() ,y); }
|
||||
|
||||
template<class T>
|
||||
inline
|
||||
bool operator < ( none_t const& x, optional<T> const& y )
|
||||
bool operator < ( none_t x, optional<T> const& y )
|
||||
{ return less_pointees(optional<T>() ,y); }
|
||||
|
||||
template<class T>
|
||||
inline
|
||||
bool operator != ( none_t const& x, optional<T> const& y )
|
||||
bool operator != ( none_t x, optional<T> const& y )
|
||||
{ return !( x == y ) ; }
|
||||
|
||||
template<class T>
|
||||
inline
|
||||
bool operator > ( none_t const& x, optional<T> const& y )
|
||||
bool operator > ( none_t x, optional<T> const& y )
|
||||
{ return y < x ; }
|
||||
|
||||
template<class T>
|
||||
inline
|
||||
bool operator <= ( none_t const& x, optional<T> const& y )
|
||||
bool operator <= ( none_t x, optional<T> const& y )
|
||||
{ return !( y < x ) ; }
|
||||
|
||||
template<class T>
|
||||
inline
|
||||
bool operator >= ( none_t const& x, optional<T> const& y )
|
||||
bool operator >= ( none_t x, optional<T> const& y )
|
||||
{ return !( x < y ) ; }
|
||||
|
||||
//
|
||||
|
||||
@ -22,11 +22,9 @@ import testing ;
|
||||
[ run optional_test_inplace.cpp ]
|
||||
[ run optional_test_io.cpp ]
|
||||
[ compile-fail optional_test_fail1.cpp ]
|
||||
[ compile-fail optional_test_fail2.cpp ]
|
||||
[ compile-fail optional_test_fail3a.cpp ]
|
||||
[ compile-fail optional_test_fail3b.cpp ]
|
||||
[ compile-fail optional_test_ref_fail1.cpp ]
|
||||
[ compile-fail optional_test_ref_fail2.cpp ]
|
||||
[ compile-fail optional_test_ref_fail3.cpp ]
|
||||
[ compile-fail optional_test_ref_fail4.cpp ]
|
||||
[ compile-fail optional_test_inplace_fail.cpp ]
|
||||
|
||||
@ -704,16 +704,16 @@ void test_relops( T const* )
|
||||
{
|
||||
TRACE( std::endl << BOOST_CURRENT_FUNCTION );
|
||||
|
||||
T v0(18);
|
||||
T v1(19);
|
||||
T v2(19);
|
||||
T v0(0);
|
||||
T v1(1);
|
||||
T v2(1);
|
||||
|
||||
optional<T> def0 ;
|
||||
optional<T> def1 ;
|
||||
optional<T> opt0(v0);
|
||||
optional<T> opt1(v1);
|
||||
optional<T> opt2(v2);
|
||||
|
||||
|
||||
// Check identity
|
||||
BOOST_CHECK ( def0 == def0 ) ;
|
||||
BOOST_CHECK ( opt0 == opt0 ) ;
|
||||
@ -751,6 +751,33 @@ void test_relops( T const* )
|
||||
BOOST_CHECK ( opt1 > opt0 ) ;
|
||||
BOOST_CHECK ( opt1 <= opt2 ) ;
|
||||
BOOST_CHECK ( opt1 >= opt0 ) ;
|
||||
|
||||
// Compare against a value directly
|
||||
BOOST_CHECK ( opt0 == v0 ) ;
|
||||
BOOST_CHECK ( opt0 != v1 ) ;
|
||||
BOOST_CHECK ( opt1 == v2 ) ;
|
||||
BOOST_CHECK ( opt0 < v1 ) ;
|
||||
BOOST_CHECK ( opt1 > v0 ) ;
|
||||
BOOST_CHECK ( opt1 <= v2 ) ;
|
||||
BOOST_CHECK ( opt1 >= v0 ) ;
|
||||
BOOST_CHECK ( v0 != opt1 ) ;
|
||||
BOOST_CHECK ( v1 == opt2 ) ;
|
||||
BOOST_CHECK ( v0 < opt1 ) ;
|
||||
BOOST_CHECK ( v1 > opt0 ) ;
|
||||
BOOST_CHECK ( v1 <= opt2 ) ;
|
||||
BOOST_CHECK ( v1 >= opt0 ) ;
|
||||
BOOST_CHECK ( def0 != v0 ) ;
|
||||
BOOST_CHECK ( !(def0 == v0) ) ;
|
||||
BOOST_CHECK ( def0 < v0 ) ;
|
||||
BOOST_CHECK ( !(def0 > v0) ) ;
|
||||
BOOST_CHECK ( def0 <= v0 ) ;
|
||||
BOOST_CHECK ( !(def0 >= v0) ) ;
|
||||
BOOST_CHECK ( v0 != def0 ) ;
|
||||
BOOST_CHECK ( !(v0 == def0) ) ;
|
||||
BOOST_CHECK ( !(v0 < def0) ) ;
|
||||
BOOST_CHECK ( v0 > def0 ) ;
|
||||
BOOST_CHECK ( !(v0 <= def0) ) ;
|
||||
BOOST_CHECK ( v0 >= opt0 ) ;
|
||||
}
|
||||
|
||||
template<class T>
|
||||
@ -767,6 +794,10 @@ void test_none( T const* )
|
||||
BOOST_CHECK ( def0 == none ) ;
|
||||
BOOST_CHECK ( non_def != none ) ;
|
||||
BOOST_CHECK ( !def1 ) ;
|
||||
BOOST_CHECK ( !(non_def < none) ) ;
|
||||
BOOST_CHECK ( non_def > none ) ;
|
||||
BOOST_CHECK ( !(non_def <= none) ) ;
|
||||
BOOST_CHECK ( non_def >= none ) ;
|
||||
|
||||
non_def = none ;
|
||||
BOOST_CHECK ( !non_def ) ;
|
||||
@ -774,6 +805,24 @@ void test_none( T const* )
|
||||
test_default_implicit_construction(T(1),none);
|
||||
}
|
||||
|
||||
template<class T>
|
||||
void test_arrow( T const* )
|
||||
{
|
||||
TRACE( std::endl << BOOST_CURRENT_FUNCTION );
|
||||
|
||||
T a(1234);
|
||||
|
||||
optional<T> oa(a) ;
|
||||
optional<T> const coa(a) ;
|
||||
|
||||
BOOST_CHECK ( coa->V() == 1234 ) ;
|
||||
|
||||
oa->V() = 4321 ;
|
||||
|
||||
BOOST_CHECK ( a.V() = 1234 ) ;
|
||||
BOOST_CHECK ( (*oa).V() = 4321 ) ;
|
||||
}
|
||||
|
||||
void test_with_builtin_types()
|
||||
{
|
||||
TRACE( std::endl << BOOST_CURRENT_FUNCTION );
|
||||
@ -804,6 +853,7 @@ void test_with_class_type()
|
||||
test_throwing_swap( ARG(X) );
|
||||
test_relops( ARG(X) ) ;
|
||||
test_none( ARG(X) ) ;
|
||||
test_arrow( ARG(X) ) ;
|
||||
BOOST_CHECK ( X::count == 0 ) ;
|
||||
}
|
||||
|
||||
|
||||
@ -299,6 +299,23 @@ void test_none( T const* )
|
||||
BOOST_CHECK ( !non_def ) ;
|
||||
}
|
||||
|
||||
template<class T>
|
||||
void test_arrow( T const* )
|
||||
{
|
||||
TRACE( std::endl << BOOST_CURRENT_FUNCTION );
|
||||
|
||||
T a(1234);
|
||||
|
||||
optional<T&> oa(a) ;
|
||||
optional<T&> const coa(a) ;
|
||||
|
||||
BOOST_CHECK ( coa->V() == 1234 ) ;
|
||||
|
||||
oa->V() = 4321 ;
|
||||
|
||||
BOOST_CHECK ( a.V() = 4321 ) ;
|
||||
}
|
||||
|
||||
void test_with_builtin_types()
|
||||
{
|
||||
TRACE( std::endl << BOOST_CURRENT_FUNCTION );
|
||||
@ -315,6 +332,7 @@ void test_with_class_type()
|
||||
test_basics( ARG(X) );
|
||||
test_relops( ARG(X) ) ;
|
||||
test_none ( ARG(X) ) ;
|
||||
test_arrow ( ARG(X) ) ;
|
||||
|
||||
BOOST_CHECK ( X::count == 0 ) ;
|
||||
}
|
||||
|
||||
@ -1,23 +0,0 @@
|
||||
// Copyright (C) 2003, Fernando Luis Cacciola Carballal.
|
||||
//
|
||||
// Use, modification, and distribution is subject to the Boost Software
|
||||
// License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
|
||||
// http://www.boost.org/LICENSE_1_0.txt)
|
||||
//
|
||||
// See http://www.boost.org/lib/optional for documentation.
|
||||
//
|
||||
// You are welcome to contact the author at:
|
||||
// fernando_cacciola@hotmail.com
|
||||
//
|
||||
#include "boost/optional.hpp"
|
||||
|
||||
//
|
||||
// THIS TEST SHOULD FAIL TO COMPILE
|
||||
//
|
||||
void optional_reference__test_no_ptr_access()
|
||||
{
|
||||
boost::optional<int&> opt ;
|
||||
opt.get_ptr();
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user