| Home | Libraries | People | FAQ | More

## Introduction

Boost.Convert builds on the `boost::lexical_cast` experience and takes those type conversion/transformation-related ideas further

- to be applicable to a wider range of conversion-related deployment scenarios,
- to provide a more flexible, configurable and extendible type-conversion framework,
- to provide generic consistent behavior,
- to unify and to uniformly deploy various conversion facilities through one consistent interface.

Boost.Convert provides new and familiar conversion/transformation-related functionality such as:

- means to deploy types that do not meet the Default Constructibility requirement;
- four types of the conversion-failure detection:
  - as part of the same process flow -- basic and generic;
  - as a branched process flow -- exception-based and function-based;
- the choice of immediate or delayed exception-throwing and non-throwing conversion-failure processing;
- flexibility of conversion-failure processing via:
  - an exception thrown;
  - the fallback value returned;
  - the fallback function called;
- support for standard algorithms.

Boost.Convert consists of two components:

- the `boost::convert()` interface;
- an extendible collection of pluggable converters.

The `boost::convert()` interface

- advertises, provides and ensures certain consistent behavior;
- unifies and provides one consistent interface to various conversion facilities.

The collection of pluggable converters is independent of the `boost::convert()` API facade and is designed to be extendible and extended over time. Currently the following converters are provided:

- `boost::lexical_cast`-based,
- `printf/scanf`-based,
- `strtol`-inspired,
- `std::stringstream`-based,
- `boost::spirit`-based.

The converters provide new and familiar functionality and demonstrate how existing and independent conversion facilities might be incorporated in to the Boost.Convert framework. For example, the `std::stream`-based converter draws on the standard `std::streams` functionality and provides:

- string-to-type and type-to-string conversions;
- formatting support (`std::ios`-based precision, base, upper/lower-case, scientific, etc.);
- support for different `locale`s;
- `char` and `wchar_t` support.

The following code demonstrates conversion of an array of integers from their textual hexadecimal representation. It assigns -1 to those which fail to convert:

    std::array<char const*, 3> strs = {{ " 5", "0XF", "not an int" }};
    std::vector<int>           ints;
    boost::cnv::cstream         cnv;

    // Configure converter to read hexadecimal, skip (leading) white spaces.
    cnv(std::hex)(std::skipws);

    std::transform(strs.begin(), strs.end(), std::back_inserter(ints),
        boost::cnv::apply<int>(std::cref(cnv)).value_or(-1));

    BOOST_TEST(ints.size() == 3); // Number of values processed.
    BOOST_TEST(ints[0] ==  5);    // " 5"
    BOOST_TEST(ints[1] == 15);    // "0XF"
    BOOST_TEST(ints[2] == -1);    // "not an int"