Blame - doc/html/boost_optional/tutorial.html - RealtimeRoboticsGroup/test

<a name="boost_optional.tutorial.motivation"></a><a class="link" href="tutorial.html#boost_optional.tutorial.motivation" title="Motivation">Motivation</a>

36

</h3></div></div></div>

37

38

Consider these functions which should return a value but which might not

39

have a value to return:

(A) <code class="computeroutput">double sqrt(double n );</code>

44

</li>

45

46

(B) <code class="computeroutput">char get_async_input();</code>

47

</li>

48

49

(C) <code class="computeroutput">point polygon::get_any_point_effectively_inside();</code>

</li>

</ul></div>

There are different approaches to the issue of not having a value to return.

54

55

56

A typical approach is to consider the existence of a valid return value as

57

a postcondition, so that if the function cannot compute the value to return,

58

it has either undefined behavior (and can use assert in a debug build) or

59

uses a runtime check and throws an exception if the postcondition is violated.

60

This is a reasonable choice for example, for function (A), because the lack

61

of a proper return value is directly related to an invalid parameter (out

62

of domain argument), so it is appropriate to require the callee to supply

63

only parameters in a valid domain for execution to continue normally.

64

65

66

However, function (B), because of its asynchronous nature, does not fail

67

just because it can't find a value to return; so it is incorrect to consider

68

such a situation an error and assert or throw an exception. This function

69

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

74

to ask a null-area polygon to return a point inside

75

itself, but in many applications, it is just impractical for performance

76

reasons to treat this as an error (because detecting that the polygon has

77

no area might be too expensive to be required to be tested previously), and

78

either an arbitrary point (typically at infinity) is returned, or some efficient

79

way to tell the callee that there is no such point is used.

80

81

82

There are various mechanisms to let functions communicate that the returned

83

value is not valid. One such mechanism, which is quite common since it has

84

zero or negligible overhead, is to use a special value which is reserved

85

to communicate this. Classical examples of such special values are <code class="computeroutput">EOF</code>, <code class="computeroutput">string::npos</code>,

86

points at infinity, etc...

87

88

89

When those values exist, i.e. the return type can hold all meaningful values

90

plus the signal value, this mechanism

91

is quite appropriate and well known. Unfortunately, there are cases when

92

such values do not exist. In these cases, the usual alternative is either

93

to use a wider type, such as <code class="computeroutput">int</code>

94

in place of <code class="computeroutput">char</code>; or a compound

95

type, such as <code class="computeroutput">std::pair<point,bool></code>.

96

97

98

Returning a <code class="computeroutput">std::pair<T,bool></code>, thus attaching a boolean flag to the

99

result which indicates if the result is meaningful, has the advantage that

100

can be turned into a consistent idiom since the first element of the pair

101

can be whatever the function would conceptually return. For example, the

102

last two functions could have the following interface:

103

104

<pre class="programlisting">std::pair<char,bool> get_async_input();

105

std::pair<point,bool> polygon::get_any_point_effectively_inside();

106

</pre>

107

108

These functions use a consistent interface for dealing with possibly nonexistent

109

results:

110

111

<pre class="programlisting">std::pair<point,bool> p = poly.get_any_point_effectively_inside();

if ( p.second )

flood_fill(p.first);

</pre>

However, not only is this quite a burden syntactically, it is also error

117

prone since the user can easily use the function result (first element of

118

the pair) without ever checking if it has a valid value.

119

120

121

Clearly, we need a better idiom.

</div>

<a name="boost_optional.tutorial.design_overview"></a><a class="link" href="tutorial.html#boost_optional.tutorial.design_overview" title="Design Overview">Design Overview</a>

127

</h3></div></div></div>

128

129

<dt><a href="tutorial.html#boost_optional.tutorial.design_overview.the_models">The

130

models</a></dt>

131

<dt><a href="tutorial.html#boost_optional.tutorial.design_overview.the_semantics">The

132

semantics</a></dt>

133

<dt><a href="tutorial.html#boost_optional.tutorial.design_overview.the_interface">The

Interface</a></dt>

</dl></div>

<a name="boost_optional.tutorial.design_overview.the_models"></a><a class="link" href="tutorial.html#boost_optional.tutorial.design_overview.the_models" title="The models">The

139

models</a>

140

</h4></div></div></div>

141

142

In C++, we can declare an object (a variable) of type

143

<code class="computeroutput">T</code>, and we can give this

144

variable an initial value (through an initializer.

145

(cf. 8.5)). When a declaration includes a non-empty initializer (an initial

146

value is given), it is said that the object has been initialized. If the

147

declaration uses an empty initializer (no initial value is given), and

148

neither default nor value initialization applies, it is said that the object

149

is uninitialized. Its actual value exist

150

but has an indeterminate initial value (cf. 8.5/11).

151

<code class="computeroutput">optional<T></code>

152

intends to formalize the notion of initialization (or lack of it) allowing

153

a program to test whether an object has been initialized and stating that

154

access to the value of an uninitialized object is undefined behavior. That

155

is, when a variable is declared as <code class="computeroutput">optional<T></code> and no initial value is given, the

156

variable is formally uninitialized. A formally uninitialized

157

optional object has conceptually no value at all and this situation can

158

be tested at runtime. It is formally undefined behavior

159

to try to access the value of an uninitialized optional. An uninitialized

160

optional can be assigned a value, in which case its initialization state

161

changes to initialized. Furthermore, given the formal treatment of initialization

162

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

167

that objects always have an initial value even if indeterminate. As discussed

168

on the previous section, this has a drawback because you need additional

169

information to tell if an object has been effectively initialized. One

170

of the typical ways in which this has been historically dealt with is via

171

a special value: <code class="computeroutput">EOF</code>,

172

<code class="computeroutput">npos</code>, -1, etc... This is

173

equivalent to adding the special value to the set of possible values of

174

a given type. This super set of <code class="computeroutput">T</code>

175

plus some nil_t—where <code class="computeroutput">nil_t</code>

176

is some stateless POD—can be modeled in modern languages as a discriminated union of T and nil_t. Discriminated

177

unions are often called variants. A variant has a

178

current type, which in our case is either <code class="computeroutput">T</code> or <code class="computeroutput">nil_t</code>.

179

Using the <a href="../../../../variant/index.html" target="_top">Boost.Variant</a>

180

library, this model can be implemented in terms of <code class="computeroutput">boost::variant<T,nil_t></code>. There is precedent for a discriminated

181

union as a model for an optional value: the <a href="http://www.haskell.org/" target="_top">Haskell</a>

182

Maybe built-in type constructor. Thus,

183

a discriminated union <code class="computeroutput">T+nil_t</code>

184

serves as a conceptual foundation.

185

186

187

A <code class="computeroutput">variant<T,nil_t></code> follows naturally from the traditional

188

idiom of extending the range of possible values adding an additional sentinel

189

value with the special meaning of Nothing. However,

190

this additional Nothing value is largely irrelevant

191

for our purpose since our goal is to formalize the notion of uninitialized

192

objects and, while a special extended value can be used to convey that

193

meaning, it is not strictly necessary in order to do so.

194

195

196

The observation made in the last paragraph about the irrelevant nature

197

of the additional <code class="computeroutput">nil_t</code>

198

with respect to purpose of <code class="computeroutput">optional<T></code>

199

suggests an alternative model: a container that either

200

has a value of <code class="computeroutput">T</code> or nothing.

201

202

203

As of this writing I don't know of any precedent for a variable-size fixed-capacity

204

(of 1) stack-based container model for optional values, yet I believe this

205

is the consequence of the lack of practical implementations of such a container

206

rather than an inherent shortcoming of the container model.

207

208

209

In any event, both the discriminated-union or the single-element container

210

models serve as a conceptual ground for a class representing optional—i.e.

211

possibly uninitialized—objects. For instance, these models show the

212

exact semantics required for a wrapper of optional

values:

Discriminated-union:

deep-copy semantics: copies of the

221

variant implies copies of the value.

222

</li>

223

224

deep-relational semantics: comparisons

225

between variants matches both current types and values

226

</li>

227

228

If the variant's current type is <code class="computeroutput">T</code>,

229

it is modeling an initialized optional.

230

</li>

231

232

If the variant's current type is not <code class="computeroutput">T</code>,

233

it is modeling an uninitialized optional.

234

</li>

235

236

Testing if the variant's current type is <code class="computeroutput">T</code>

237

models testing if the optional is initialized

238

</li>

239

240

Trying to extract a <code class="computeroutput">T</code>

241

from a variant when its current type is not <code class="computeroutput">T</code>,

242

models the undefined behavior of trying to access the value of an uninitialized

optional

</li>

</ul></div>

Single-element container:

deep-copy semantics: copies of the

252

container implies copies of the value.

253

</li>

254

255

deep-relational semantics: comparisons

256

between containers compare container size and if match, contained value

257

</li>

258

259

If the container is not empty (contains an object of type <code class="computeroutput">T</code>), it is modeling an initialized

optional.

</li>

If the container is empty, it is modeling an uninitialized

optional.

</li>

Testing if the container is empty models testing if the optional is

initialized

</li>

Trying to extract a <code class="computeroutput">T</code>

272

from an empty container models the undefined behavior of trying to

273

access the value of an uninitialized optional

</li>

</ul></div>

</div>

<a name="boost_optional.tutorial.design_overview.the_semantics"></a><a class="link" href="tutorial.html#boost_optional.tutorial.design_overview.the_semantics" title="The semantics">The

280

semantics</a>

281

</h4></div></div></div>

282

283

Objects of type <code class="computeroutput">optional<T></code> are intended to be used in places where

284

objects of type <code class="computeroutput">T</code> would

285

but which might be uninitialized. Hence, <code class="computeroutput">optional<T></code>'s purpose is to formalize the additional

286

possibly uninitialized state. From the perspective of this role, <code class="computeroutput">optional<T></code>

287

can have the same operational semantics of <code class="computeroutput">T</code>

288

plus the additional semantics corresponding to this special state. As such,

289

<code class="computeroutput">optional<T></code>

290

could be thought of as a supertype of <code class="computeroutput">T</code>. Of course, we can't do that in C++,

291

so we need to compose the desired semantics using a different mechanism.

292

Doing it the other way around, that is, making <code class="computeroutput">optional<T></code> a subtype of

293

<code class="computeroutput">T</code> is not only conceptually

294

wrong but also impractical: it is not allowed to derive from a non-class

295

type, such as a built-in type.

296

297

298

We can draw from the purpose of <code class="computeroutput">optional<T></code> the required basic semantics:

Default Construction: To introduce

303

a formally uninitialized wrapped object.

304

</li>

305

306

Direct Value Construction via copy:

307

To introduce a formally initialized wrapped object whose value is obtained

308

as a copy of some object.

309

</li>

310

311

Deep Copy Construction: To obtain

312

a new yet equivalent wrapped object.

313

</li>

314

315

Direct Value Assignment (upon initialized):

316

To assign a value to the wrapped object.

317

</li>

318

319

Direct Value Assignment (upon uninitialized):

320

To initialize the wrapped object with a value obtained as a copy of

some object.

</li>

Assignment (upon initialized): To

325

assign to the wrapped object the value of another wrapped object.

326

</li>

327

328

Assignment (upon uninitialized): To

329

initialize the wrapped object with value of another wrapped object.

330

</li>

331

332

Deep Relational Operations (when supported by

333

the type T): To compare wrapped object values taking into

334

account the presence of uninitialized states.

335

</li>

336

337

Value access: To unwrap the wrapped

object.

</li>

Initialization state query: To determine

342

if the object is formally initialized or not.

343

</li>

344

345

Swap: To exchange wrapped objects.

346

(with whatever exception safety guarantees are provided by <code class="computeroutput">T</code>'s swap).

347

</li>

348

349

De-initialization: To release the

350

wrapped object (if any) and leave the wrapper in the uninitialized

state.

</li>

</ul></div>

Additional operations are useful, such as converting constructors and converting

356

assignments, in-place construction and assignment, and safe value access

357

via a pointer to the wrapped object or null.

</div>

<a name="boost_optional.tutorial.design_overview.the_interface"></a><a class="link" href="tutorial.html#boost_optional.tutorial.design_overview.the_interface" title="The Interface">The

363

Interface</a>

364

</h4></div></div></div>

365

366

Since the purpose of optional is to allow us to use objects with a formal

367

uninitialized additional state, the interface could try to follow the interface

368

of the underlying <code class="computeroutput">T</code> type

369

as much as possible. In order to choose the proper degree of adoption of

370

the native <code class="computeroutput">T</code> interface,

371

the following must be noted: Even if all the operations supported by an

372

instance of type <code class="computeroutput">T</code> are

373

defined for the entire range of values for such a type, an <code class="computeroutput">optional<T></code>

374

extends such a set of values with a new value for which most (otherwise

375

valid) operations are not defined in terms of <code class="computeroutput">T</code>.

376

377

378

Furthermore, since <code class="computeroutput">optional<T></code> itself is merely a <code class="computeroutput">T</code>

379

wrapper (modeling a <code class="computeroutput">T</code> supertype),

380

any attempt to define such operations upon uninitialized optionals will

381

be totally artificial w.r.t. <code class="computeroutput">T</code>.

382

383

384

This library chooses an interface which follows from <code class="computeroutput">T</code>'s

385

interface only for those operations which are well defined (w.r.t the type

386

<code class="computeroutput">T</code>) even if any of the operands

387

are uninitialized. These operations include: construction, copy-construction,

388

assignment, swap and relational operations.

389

390

391

For the value access operations, which are undefined (w.r.t the type <code class="computeroutput">T</code>) when the operand is uninitialized,

392

a different interface is chosen (which will be explained next).

393

394

395

Also, the presence of the possibly uninitialized state requires additional

396

operations not provided by <code class="computeroutput">T</code>

397

itself which are supported by a special interface.

<h6>

<a name="boost_optional.tutorial.design_overview.the_interface.lexically_hinted_value_access_in_the_presence_of_possibly_untitialized_optional_objects__the_operators___and___gt_"></a><a class="link" href="tutorial.html#boost_optional.tutorial.design_overview.the_interface.lexically_hinted_value_access_in_the_presence_of_possibly_untitialized_optional_objects__the_operators___and___gt_">Lexically-hinted

402

Value Access in the presence of possibly untitialized optional objects:

403

The operators * and -></a>

404

</h6>

405

406

A relevant feature of a pointer is that it can have a null

407

pointer value. This is a special value

408

which is used to indicate that the pointer is not referring to any object

409

at all. In other words, null pointer values convey the notion of nonexistent

objects.

This meaning of the null pointer value allowed pointers to became a de

414

facto standard for handling optional objects because all you

415

have to do to refer to a value which you don't really have is to use a

416

null pointer value of the appropriate type. Pointers have been used for

417

decades—from the days of C APIs to modern C++ libraries—to refer

418

to optional (that is, possibly nonexistent) objects; particularly as optional

419

arguments to a function, but also quite often as optional data members.

420

421

422

The possible presence of a null pointer value makes the operations that

423

access the pointee's value possibly undefined, therefore, expressions which

424

use dereference and access operators, such as: <code class="computeroutput">(

425

*p

426

= 2 )</code> and <code class="computeroutput">(

427

p->foo() )</code>, implicitly convey the notion of optionality,

428

and this information is tied to the syntax of the

429

expressions. That is, the presence of operators <code class="computeroutput">*</code>

430

and <code class="computeroutput">-></code> tell by themselves

431

—without any additional context— that the expression will be undefined

432

unless the implied pointee actually exist.

433

434

435

Such a de facto idiom for referring to optional objects

436

can be formalized in the form of a concept: the <a href="../../../../utility/OptionalPointee.html" target="_top">OptionalPointee</a>

437

concept. This concept captures the syntactic usage of operators <code class="computeroutput">*</code>, <code class="computeroutput">-></code>

438

and contextual conversion to <code class="computeroutput">bool</code>

439

to convey the notion of optionality.

440

441

442

However, pointers are good to refer

443

to optional objects, but not particularly good to handle the optional objects

444

in all other respects, such as initializing or moving/copying them. The

445

problem resides in the shallow-copy of pointer semantics: if you need to

446

effectively move or copy the object, pointers alone are not enough. The

447

problem is that copies of pointers do not imply copies of pointees. For

448

example, as was discussed in the motivation, pointers alone cannot be used

449

to return optional objects from a function because the object must move

450

outside from the function and into the caller's context.

451

452

453

A solution to the shallow-copy problem that is often used is to resort

454

to dynamic allocation and use a smart pointer to automatically handle the

455

details of this. For example, if a function is to optionally return an

456

object <code class="computeroutput">X</code>, it can use <code class="computeroutput">shared_ptr<X></code>

457

as the return value. However, this requires dynamic allocation of <code class="computeroutput">X</code>. If <code class="computeroutput">X</code>

458

is a built-in or small POD, this technique is very poor in terms of required

459

resources. Optional objects are essentially values so it is very convenient

460

to be able to use automatic storage and deep-copy semantics to manipulate

461

optional values just as we do with ordinary values. Pointers do not have

462

this semantics, so are inappropriate for the initialization and transport

463

of optional values, yet are quite convenient for handling the access to

464

the possible undefined value because of the idiomatic aid present in the

465

<a href="../../../../utility/OptionalPointee.html" target="_top">OptionalPointee</a>

466

concept incarnated by pointers.

<h6>

<a name="boost_optional.tutorial.design_overview.the_interface.optional_lt_t_gt__as_a_model_of_optionalpointee"></a><a class="link" href="tutorial.html#boost_optional.tutorial.design_overview.the_interface.optional_lt_t_gt__as_a_model_of_optionalpointee">Optional<T>

471

as a model of OptionalPointee</a>

472

</h6>

473

474

For value access operations <code class="computeroutput">optional<></code> uses operators <code class="computeroutput">*</code>

475

and <code class="computeroutput">-></code> to lexically warn

476

about the possibly uninitialized state appealing to the familiar pointer

477

semantics w.r.t. to null pointers.

<tr>

<th align="left">Warning</th>

483

</tr>

484

485

However, it is particularly important to note that <code class="computeroutput">optional<></code> objects are not pointers. <code class="computeroutput">optional<></code> is not, and does not model, a

pointer.

</td></tr>

</table></div>