Boost C++ Libraries of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.



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, 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.

The requirements on the argument and result types 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, char16_t or char32_t. Wide-character streaming is currently detected for:

  • Single character: wchar_t, char16_t, char32_t
  • Arrays of characters: wchar_t *, char16_t *, char32_t *, const wchar_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] 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:

    << 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.

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

Exception used to indicate runtime lexical_cast failure.