[ceph.git] / ceph / src / boost / libs / optional / doc / html / boost_optional / tutorial / design_overview.html

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Design Overview</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
<link rel="home" href="../../index.html" title="Boost.Optional">
<link rel="up" href="../../optional/tutorial.html" title="Tutorial">
<link rel="prev" href="../../optional/tutorial.html" title="Tutorial">
<link rel="next" href="design_overview/the_semantics.html" title="The semantics">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="design_overview/the_semantics.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_optional.tutorial.design_overview"></a><a class="link" href="design_overview.html" title="Design Overview">Design Overview</a>
</h3></div></div></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="boost_optional.tutorial.design_overview.the_models"></a><a class="link" href="design_overview.html#boost_optional.tutorial.design_overview.the_models" title="The models">The
        models</a>
</h4></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>.
          (cf. 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> (cf. 8.5/11).
          <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</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">&lt;</span><span class="identifier">T</span><span class="special">&gt;</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>&#8212;where <code class="computeroutput"><span class="identifier">nil_t</span></code>
          is some stateless POD&#8212;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">&lt;</span><span class="identifier">T</span><span class="special">,</span><span class="identifier">nil_t</span><span class="special">&gt;</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">&lt;</span><span class="identifier">T</span><span class="special">,</span><span class="identifier">nil_t</span><span class="special">&gt;</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">&lt;</span><span class="identifier">T</span><span class="special">&gt;</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 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>
<p>
          In any event, both the discriminated-union or the single-element container
          models serve as a conceptual ground for a class representing optional&#8212;i.e.
          possibly uninitialized&#8212;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 class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
              <span class="bold"><strong>deep-copy</strong></span> semantics: copies of the
              variant implies copies of the value.
            </li>
<li class="listitem">
              <span class="bold"><strong>deep-relational</strong></span> semantics: comparisons
              between variants matches both current types and values
            </li>
<li class="listitem">
              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 class="listitem">
              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 class="listitem">
              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 class="listitem">
              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 class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
              <span class="bold"><strong>deep-copy</strong></span> semantics: copies of the
              container implies copies of the value.
            </li>
<li class="listitem">
              <span class="bold"><strong>deep-relational</strong></span> semantics: comparisons
              between containers compare container size and if match, contained value
            </li>
<li class="listitem">
              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 class="listitem">
              If the container is empty, it is modeling an <span class="emphasis"><em>uninitialized</em></span>
              optional.
            </li>
<li class="listitem">
              Testing if the container is empty models testing if the optional is
              initialized
            </li>
<li class="listitem">
              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>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2003-2007 Fernando Luis Cacciola Carballal<br>Copyright &#169; 2014-2016 Andrzej Krzemie&#324;ski<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></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="design_overview/the_semantics.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
Commit	Line	Data
7c673cae FG	1	<html>
	2	<head>
	3	<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
	4	<title>Design Overview</title>
	5	<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
	6	<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
	7	<link rel="home" href="../../index.html" title="Boost.Optional">
	8	<link rel="up" href="../../optional/tutorial.html" title="Tutorial">
	9	<link rel="prev" href="../../optional/tutorial.html" title="Tutorial">
	10	<link rel="next" href="design_overview/the_semantics.html" title="The semantics">
	11	</head>
	12	<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
	13	<table cellpadding="2" width="100%"><tr>
	14	<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
	15	<td align="center"><a href="../../../../../../index.html">Home</a></td>
	16	<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
	17	<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
	18	<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
	19	<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
	20	</tr></table>
	21	<hr>
	22	<div class="spirit-nav">
	23	<a accesskey="p" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="design_overview/the_semantics.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
	24	</div>
	25	<div class="section">
	26	<div class="titlepage"><div><div><h3 class="title">
	27	<a name="boost_optional.tutorial.design_overview"></a><a class="link" href="design_overview.html" title="Design Overview">Design Overview</a>
	28	</h3></div></div></div>
	29	<div class="section">
	30	<div class="titlepage"><div><div><h4 class="title">
	31	<a name="boost_optional.tutorial.design_overview.the_models"></a><a class="link" href="design_overview.html#boost_optional.tutorial.design_overview.the_models" title="The models">The
	32	models</a>
	33	</h4></div></div></div>
	34	<p>
	35	In C++, we can <span class="emphasis"><em>declare</em></span> an object (a variable) of type
	36	<code class="computeroutput"><span class="identifier">T</span></code>, and we can give this
	37	variable an <span class="emphasis"><em>initial value</em></span> (through an <span class="emphasis"><em>initializer</em></span>.
	38	(cf. 8.5)). When a declaration includes a non-empty initializer (an initial
	39	value is given), it is said that the object has been initialized. If the
	40	declaration uses an empty initializer (no initial value is given), and
	41	neither default nor value initialization applies, it is said that the object
	42	is <span class="bold"><strong>uninitialized</strong></span>. Its actual value exist
	43	but has an <span class="emphasis"><em>indeterminate initial value</em></span> (cf. 8.5/11).
	44	<code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code>
	45	intends to formalize the notion of initialization (or lack of it) allowing
	46	a program to test whether an object has been initialized and stating that
	47	access to the value of an uninitialized object is undefined behavior. That
	48	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
	49	variable is <span class="emphasis"><em>formally</em></span> uninitialized. A formally uninitialized
	50	optional object has conceptually no value at all and this situation can
	51	be tested at runtime. It is formally <span class="emphasis"><em>undefined behavior</em></span>
	52	to try to access the value of an uninitialized optional. An uninitialized
	53	optional can be assigned a value, in which case its initialization state
	54	changes to initialized. Furthermore, given the formal treatment of initialization
	55	states in optional objects, it is even possible to reset an optional to
	56	<span class="emphasis"><em>uninitialized</em></span>.
	57	</p>
	58	<p>
	59	In C++ there is no formal notion of uninitialized objects, which means
	60	that objects always have an initial value even if indeterminate. As discussed
	61	on the previous section, this has a drawback because you need additional
	62	information to tell if an object has been effectively initialized. One
	63	of the typical ways in which this has been historically dealt with is via
	64	a special value: <code class="computeroutput"><span class="identifier">EOF</span></code>,
65	<code class="computeroutput"><span class="identifier">npos</span></code>, -1, etc... This is
66	equivalent to adding the special value to the set of possible values of
67	a given type. This super set of <code class="computeroutput"><span class="identifier">T</span></code>
68	plus some <span class="emphasis"><em>nil_t</em></span>—where <code class="computeroutput"><span class="identifier">nil_t</span></code>
69	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
70	unions are often called <span class="emphasis"><em>variants</em></span>. A variant has a
71	<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>.
72	Using the <a href="../../../../../variant/index.html" target="_top">Boost.Variant</a>
73	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
74	union as a model for an optional value: the <a href="http://www.haskell.org/" target="_top">Haskell</a>
75	<span class="bold"><strong>Maybe</strong></span> built-in type constructor. Thus,
76	a discriminated union <code class="computeroutput"><span class="identifier">T</span><span class="special">+</span><span class="identifier">nil_t</span></code>
77	serves as a conceptual foundation.
78	</p>
79	<p>
80	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
81	idiom of extending the range of possible values adding an additional sentinel
82	value with the special meaning of <span class="emphasis"><em>Nothing</em></span>. However,
83	this additional <span class="emphasis"><em>Nothing</em></span> value is largely irrelevant
84	for our purpose since our goal is to formalize the notion of uninitialized
85	objects and, while a special extended value can be used to convey that
86	meaning, it is not strictly necessary in order to do so.
87	</p>
88	<p>
89	The observation made in the last paragraph about the irrelevant nature
90	of the additional <code class="computeroutput"><span class="identifier">nil_t</span></code>
91	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>
92	suggests an alternative model: a <span class="emphasis"><em>container</em></span> that either
93	has a value of <code class="computeroutput"><span class="identifier">T</span></code> or nothing.
94	</p>
95	<p>
96	As of this writing I don't know of any precedent for a variable-size fixed-capacity
97	(of 1) stack-based container model for optional values, yet I believe this
98	is the consequence of the lack of practical implementations of such a container
99	rather than an inherent shortcoming of the container model.
100	</p>
101	<p>
102	In any event, both the discriminated-union or the single-element container
103	models serve as a conceptual ground for a class representing optional—i.e.
104	possibly uninitialized—objects. For instance, these models show the
105	<span class="emphasis"><em>exact</em></span> semantics required for a wrapper of optional
106	values:
107	</p>
108	<p>
109	Discriminated-union:
110	</p>
111	<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
112	<li class="listitem">
113	<span class="bold"><strong>deep-copy</strong></span> semantics: copies of the
114	variant implies copies of the value.
115	</li>
116	<li class="listitem">
117	<span class="bold"><strong>deep-relational</strong></span> semantics: comparisons
118	between variants matches both current types and values
119	</li>
120	<li class="listitem">
121	If the variant's current type is <code class="computeroutput"><span class="identifier">T</span></code>,
122	it is modeling an <span class="emphasis"><em>initialized</em></span> optional.
123	</li>
124	<li class="listitem">
125	If the variant's current type is not <code class="computeroutput"><span class="identifier">T</span></code>,
126	it is modeling an <span class="emphasis"><em>uninitialized</em></span> optional.
127	</li>
128	<li class="listitem">
129	Testing if the variant's current type is <code class="computeroutput"><span class="identifier">T</span></code>
130	models testing if the optional is initialized
131	</li>
132	<li class="listitem">
133	Trying to extract a <code class="computeroutput"><span class="identifier">T</span></code>
134	from a variant when its current type is not <code class="computeroutput"><span class="identifier">T</span></code>,
135	models the undefined behavior of trying to access the value of an uninitialized
136	optional
137	</li>
138	</ul></div>
139	<p>
140	Single-element container:
141	</p>
142	<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
143	<li class="listitem">
144	<span class="bold"><strong>deep-copy</strong></span> semantics: copies of the
145	container implies copies of the value.
146	</li>
147	<li class="listitem">
148	<span class="bold"><strong>deep-relational</strong></span> semantics: comparisons
149	between containers compare container size and if match, contained value
150	</li>
151	<li class="listitem">
152	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>
153	optional.
154	</li>
155	<li class="listitem">
156	If the container is empty, it is modeling an <span class="emphasis"><em>uninitialized</em></span>
157	optional.
158	</li>
159	<li class="listitem">
160	Testing if the container is empty models testing if the optional is
161	initialized
162	</li>
163	<li class="listitem">
164	Trying to extract a <code class="computeroutput"><span class="identifier">T</span></code>
165	from an empty container models the undefined behavior of trying to
166	access the value of an uninitialized optional
167	</li>
168	</ul></div>
169	</div>
170	</div>
171	<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
172	<td align="left"></td>
173	<td align="right"><div class="copyright-footer">Copyright © 2003-2007 Fernando Luis Cacciola Carballal<br>Copyright © 2014-2016 Andrzej Krzemieński<p>
174	Distributed under the Boost Software License, Version 1.0. (See accompanying
175	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>)
176	</p>
177	</div></td>
178	</tr></table>
179	<hr>
180	<div class="spirit-nav">
181	<a accesskey="p" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="design_overview/the_semantics.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
182	</div>
183	</body>
184	</html>