[ceph.git] / ceph / src / boost / libs / convert / doc / getting_started.qbk

[/
  Copyright (c) Vladimir Batov 2009-2016
  Distributed under the Boost Software License, Version 1.0.
  See copy at http://www.boost.org/LICENSE_1_0.txt.
]

[section Getting Started]

[note Given the ubiquity of `boost::lexical_cast` and the familiarity of the programming community with it, here and further in the documentation `boost::lexical_cast` is often mentioned as a reference.]

[import ../example/getting_started.cpp]

[section Basic Deployment]

For die-hard `boost::lexical_cast` users or as a transitional path to `boost::convert`, one of `boost::convert` deployments is not that different from `boost::lexical_cast` and, in fact, the original `boost::lexical_cast` functionality is easily deployed through `boost::convert` interface:

[getting_started_headers1]
[getting_started_using]
[getting_started_default_converter]
[getting_started_example1]

[important As we explore `boost::convert` behavior and interface further, at first they might appear unduly complex, verbose, etc... nothing like `atoi()`... so famous for all the wrong reasons. :-) It is important to remember that a conversion request is only a ['request] which may succeed but may also fail... which might not be as rare or as exceptional as one might hope. `boost::convert` (as well as `boost::lexical_cast`) behavior and interfaces reflect that reality.]

[endsect]
[section Flexibility and Adaptability to Change]

[:[*['"There is nothing more constant than change" Heraclitus]]]

Sooner or later (during initial development or in the maintenance phase) flexibility and adaptability become important. Deployment of ['Boost.Convert] helps to adjust and to change in line with the evolution of the requirements. Say, the program flow would benefit from the non-throwing behavior. Then:

[getting_started_using]
[getting_started_example2]

Or, the component is identified as too slow. Then the performance could be improved with minimal effort by replacing the converter:

[getting_started_headers3]
[getting_started_example3]

If, instead, the requirements change to support more input formats or to require a certain output format, then, again, that could be accommodated with:

[getting_started_headers4]
[getting_started_example4]

[endsect]
[section Basic Conversion-Failure Detection]

[getting_started_using]
[getting_started_example5]

The above is translated to English as

* "['convert a string to int]" for `i1` and `i2` and
* "['convert a string to int and return -1 if the conversion fails]" for `i3`.

The `i1` and `i2` deployments look sufficiently close and behave identically. Namely, with the user instructions silent about the conversion failure, those are treated as "exceptional" and throw.

The `i3` specification, on the other hand, is explicit about conversion failures. The supplied fallback value is returned if the requested conversion fails.

That basic error detection and processing might be sufficient for a variety of conversion deployments. For example:

[getting_started_example6]

Or

[getting_started_example9_func]
[getting_started_example9]

Or, if we do not care about logging conversion failures:

[getting_started_example7]

So far the deployment of `boost::convert` seems more flexible, more compact and natural (your mileage may vary) and potentially more efficient compared to `boost::lexical_cast` which achieves somewhat similar results with:

[getting_started_example8]

By design, this is `boost::lexical_cast`'s only behavior -- straightforward and comprehensible, but limited.
It makes quite a few legitimate process\/program flows difficult and awkward to implement.
['Boost.Convert] addresses that with additional functionality, flexibility and convenience.

[endsect]
[endsect]
Commit	Line	Data
7c673cae FG	1	[/
	2	Copyright (c) Vladimir Batov 2009-2016
	3	Distributed under the Boost Software License, Version 1.0.
	4	See copy at http://www.boost.org/LICENSE_1_0.txt.
	5	]
	6
	7	[section Getting Started]
	8
	9	[note Given the ubiquity of `boost::lexical_cast` and the familiarity of the programming community with it, here and further in the documentation `boost::lexical_cast` is often mentioned as a reference.]
	10
	11	[import ../example/getting_started.cpp]
	12
	13	[section Basic Deployment]
	14
	15	For die-hard `boost::lexical_cast` users or as a transitional path to `boost::convert`, one of `boost::convert` deployments is not that different from `boost::lexical_cast` and, in fact, the original `boost::lexical_cast` functionality is easily deployed through `boost::convert` interface:
	16
	17	[getting_started_headers1]
	18	[getting_started_using]
	19	[getting_started_default_converter]
	20	[getting_started_example1]
	21
	22	[important As we explore `boost::convert` behavior and interface further, at first they might appear unduly complex, verbose, etc... nothing like `atoi()`... so famous for all the wrong reasons. :-) It is important to remember that a conversion request is only a ['request] which may succeed but may also fail... which might not be as rare or as exceptional as one might hope. `boost::convert` (as well as `boost::lexical_cast`) behavior and interfaces reflect that reality.]
	23
	24	[endsect]
	25	[section Flexibility and Adaptability to Change]
	26
	27	[:[*['"There is nothing more constant than change" Heraclitus]]]
	28
	29	Sooner or later (during initial development or in the maintenance phase) flexibility and adaptability become important. Deployment of ['Boost.Convert] helps to adjust and to change in line with the evolution of the requirements. Say, the program flow would benefit from the non-throwing behavior. Then:
	30
	31	[getting_started_using]
	32	[getting_started_example2]
	33
	34	Or, the component is identified as too slow. Then the performance could be improved with minimal effort by replacing the converter:
	35
	36	[getting_started_headers3]
	37	[getting_started_example3]
	38
	39	If, instead, the requirements change to support more input formats or to require a certain output format, then, again, that could be accommodated with:
	40
	41	[getting_started_headers4]
	42	[getting_started_example4]
	43
	44	[endsect]
	45	[section Basic Conversion-Failure Detection]
	46
	47	[getting_started_using]
	48	[getting_started_example5]
	49
	50	The above is translated to English as
	51
	52	* "['convert a string to int]" for `i1` and `i2` and
	53	* "['convert a string to int and return -1 if the conversion fails]" for `i3`.
	54
	55	The `i1` and `i2` deployments look sufficiently close and behave identically. Namely, with the user instructions silent about the conversion failure, those are treated as "exceptional" and throw.
	56
	57	The `i3` specification, on the other hand, is explicit about conversion failures. The supplied fallback value is returned if the requested conversion fails.
	58
	59	That basic error detection and processing might be sufficient for a variety of conversion deployments. For example:
	60
	61	[getting_started_example6]
	62
	63	Or
	64
65	[getting_started_example9_func]
66	[getting_started_example9]
67
68	Or, if we do not care about logging conversion failures:
69
70	[getting_started_example7]
71
72	So far the deployment of `boost::convert` seems more flexible, more compact and natural (your mileage may vary) and potentially more efficient compared to `boost::lexical_cast` which achieves somewhat similar results with:
73
74	[getting_started_example8]
75
76	By design, this is `boost::lexical_cast`'s only behavior -- straightforward and comprehensible, but limited.
77	It makes quite a few legitimate process\/program flows difficult and awkward to implement.
78	['Boost.Convert] addresses that with additional functionality, flexibility and convenience.
79
80	[endsect]
81	[endsect]