Synopsis

| Home | Libraries | People | FAQ | More

## Synopsis

Library features defined in boost/lexical_cast.hpp:

    namespace boost
    {
        class bad_lexical_cast;

        template<typename Target, typename Source>
          Target lexical_cast(const Source& arg);

        template <typename Target>
          Target lexical_cast(const AnyCharacterType* chars, std::size_t count);

        namespace conversion
        {
            template<typename Target, typename Source>
                bool try_lexical_convert(const Source& arg, Target& result);

            template <typename AnyCharacterType, typename Target>
                bool try_lexical_convert(const AnyCharacterType* chars, std::size_t count, Target& result);

        } // namespace conversion
    } // namespace boost

### lexical_cast

    template<typename Target, typename Source>
      Target lexical_cast(const Source& arg);

Returns the result of streaming arg into a standard library string-based stream and then out as a Target object. Where Target is either `std::string` or `std::wstring`, stream extraction takes the whole content of the string, including spaces, rather than relying on the default `operator>>` behavior. If the conversion is unsuccessful, a `bad_lexical_cast` exception is thrown.

    template <typename Target>
      Target lexical_cast(const AnyCharacterType* chars, std::size_t count);

Takes an array of `count` characters as input parameter and streams them out as a Target object. If the conversion is unsuccessful, a `bad_lexical_cast` exception is thrown. This call may be useful for processing nonzero terminated array of characters or processing just some part of character array.

The requirements on the argument and result types for both functions are:

- Source is OutputStreamable, meaning that an `operator<<` is defined that takes a `std::ostream` or `std::wostream` object on the left hand side and an instance of the argument type on the right.
- Target is InputStreamable, meaning that an `operator>>` is defined that takes a `std::istream` or `std::wistream` object on the left hand side and an instance of the result type on the right.
- Target is CopyConstructible [20.1.3].
- Target is DefaultConstructible, meaning that it is possible to default-initialize an object of that type [8.5, 20.1.4].

The character type of the underlying stream is assumed to be `char` unless either the `Source` or the `Target` requires wide-character streaming, in which case the underlying stream uses `wchar_t`. Following types also can use `char16_t` or `char32_t` for wide-character streaming:

- Single character: `char16_t`, `char32_t`
- Arrays of characters: `char16_t *`, `char32_t *`, `const char16_t *`, `const char32_t *`
- Strings: `std::basic_string`, `boost::containers::basic_string`
- `boost::iterator_range<WideCharPtr>`, where `WideCharPtr` is a pointer to wide-character or pointer to const wide-character
- `boost::array<CharT, N>` and `std::array<CharT, N>`, `boost::array<const CharT, N>` and `std::array<const CharT, N>`

| Important

Many compilers and runtime libraries fail to make conversions using new Unicode characters. Make sure that the following code compiles and outputs nonzero values, before using new types:

    std::cout
        << boost::lexical_cast<std::u32string>(1.0).size()
        << "  "
        << boost::lexical_cast<std::u16string>(1.0).size();

Where a higher degree of control is required over conversions, `std::stringstream` and `std::wstringstream` offer a more appropriate path. Where non-stream-based conversions are required, `lexical_cast` is the wrong tool for the job and is not special-cased for such scenarios.

### bad_lexical_cast

    class bad_lexical_cast : public std::bad_cast
    {
    public:
        ... // same member function interface as std::exception
    };

Exception used to indicate runtime lexical_cast failure.

### try_lexical_convert

`boost::lexical_cast` remains the main interface for lexical conversions. It must be used by default in most cases. However some developers wish to make their own conversion functions, reusing all the optimizations of the `boost::lexical_cast`. That's where the `boost::conversion::try_lexical_convert` function steps in.

`try_lexical_convert` returns `true` if conversion succeeded, otherwise returns `false`. If conversion failed and `false` was returned, state of `result` output variable is undefined.

Actually, `boost::lexical_cast` is implemented using `try_lexical_convert`:

    template <typename Target, typename Source>
    inline Target lexical_cast(const Source &arg)
    {
        Target result;

        if (!conversion::try_lexical_convert(arg, result))
            throw bad_lexical_cast();

        return result;
    }

`try_lexical_convert` relaxes the CopyConstructible and DefaultConstructible requirements for `Target` type. Following requirements for `Target` and `Source` remain:

- Source must be OutputStreamable, meaning that an `operator<<` is defined that takes a `std::ostream` or `std::wostream` object on the left hand side and an instance of the argument type on the right.
- Target must be InputStreamable, meaning that an `operator>>` is defined that takes a `std::istream` or `std::wistream` object on the left hand side and an instance of the result type on the right.