mirror of
https://github.com/boostorg/convert.git
synced 2026-02-17 13:42:18 +00:00
70 lines
3.0 KiB
Plaintext
70 lines
3.0 KiB
Plaintext
[/
|
|
Copyright (c) Vladimir Batov 2009-2014
|
|
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]
|
|
|
|
`boost::convert` basic deployment is not that different from `boost::lexical_cast` and, in fact, `boost::lexical_cast` functionality is easily deployed through `boost::convert` interface:
|
|
|
|
[getting_started_headers1]
|
|
[using_header]
|
|
[getting_started_example1]
|
|
|
|
[endsect]
|
|
[section Flexibility and Adaptability to Change]
|
|
|
|
Sooner or later (during development or in the maintenance phase) these qualities become important when, say, the program flow favors a non-throwing behavior:
|
|
|
|
[using_header]
|
|
[getting_started_example2]
|
|
|
|
Or, when the code is identified as too slow, the performance could be improved with minimal effort by replacing the original converter:
|
|
|
|
[getting_started_headers3]
|
|
[getting_started_example3]
|
|
|
|
If, instead, the requirements change and legitimize more lenient user inputs or require a certain output format, then, again, that could be achieved with minimal effort:
|
|
|
|
[getting_started_headers4]
|
|
[getting_started_example4]
|
|
|
|
[endsect]
|
|
[section Basic Conversion-Failure Detection]
|
|
|
|
[using_header]
|
|
[getting_started_example5]
|
|
|
|
The above calls can be interpreted 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, in fact, are identical behaviorally. Namely, if the requested conversion fails, an exception is thrown. The user request -- "['convert a string to int]" -- lacks the description of the conversion-failure use-case. Consequently, `boost::lexical_cast` and `boost::convert` treat that use-case as "exceptional".
|
|
|
|
The `i3` specification, on the other hand, is explicit with regard to the conversion-failure use-case. Consequently, the supplied fallback value is returned if the requested conversion fails.
|
|
|
|
That profoundly basic error detection might be sufficient for a variety of conversion deployments. For example:
|
|
|
|
[getting_started_example6]
|
|
|
|
Or even shorter, if we do not care logging:
|
|
|
|
[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 "raw" `boost::lexical_cast` deployment which achieves similar (excluding formatting) results with:
|
|
|
|
[getting_started_example8]
|
|
|
|
By design this is `boost::lexical_cast`'s only behavior. Straightforward and comprehensible. Unfortunately, it makes quite a few legitimate process\/program flows difficult and awkward to implement. ['Boost.Convert] offers new functionality, flexibility and convenience.
|
|
|
|
[endsect]
|
|
[endsect]
|