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.

Chapter 19. Boost.Lexical_Cast 1.0

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at

Table of Contents

Strings to numbers conversion
Numbers to strings conversion
Converting to string without dynamic memory allocation
Converting part of the string
Generic programming (Boost.Fusion)
Generic programming (Boost.Variant)
Frequently Asked Questions
Tests description
GNU C++ version 6.1.1 20160511
GNU C++ version 4.8.5
Clang version 3.6.0 (tags/RELEASE_360/final)

Sometimes a value must be converted to a literal text form, such as an int represented as a std::string, or vice-versa, when a std::string is interpreted as an int. Such examples are common when converting between data types internal to a program and representation external to a program, such as windows and configuration files.

The standard C and C++ libraries offer a number of facilities for performing such conversions. However, they vary with their ease of use, extensibility, and safety.

For instance, there are a number of limitations with the family of standard C functions typified by atoi:

  • Conversion is supported in one direction only: from text to internal data type. Converting the other way using the C library requires either the inconvenience and compromised safety of the sprintf function, or the loss of portability associated with non-standard functions such as itoa.
  • The range of types supported is only a subset of the built-in numeric types, namely int, long, and double.
  • The range of types cannot be extended in a uniform manner. For instance, conversion from string representation to complex or rational.

The standard C functions typified by strtol have the same basic limitations, but offer finer control over the conversion process. However, for the common case such control is often either not required or not used. The scanf family of functions offer even greater control, but also lack safety and ease of use.

The standard C++ library offers stringstream for the kind of in-core formatting being discussed. It offers a great deal of control over the formatting and conversion of I/O to and from arbitrary types through text. However, for simple conversions direct use of stringstream can be either clumsy (with the introduction of extra local variables and the loss of infix-expression convenience) or obscure (where stringstream objects are created as temporary objects in an expression). Facets provide a comprehensive concept and facility for controlling textual representation, but their perceived complexity and high entry level requires an extreme degree of involvement for simple conversions, and excludes all but a few programmers.

The lexical_cast function template offers a convenient and consistent form for supporting common conversions to and from arbitrary types when they are represented as text. The simplification it offers is in expression-level convenience for such conversions. For more involved conversions, such as where precision or formatting need tighter control than is offered by the default behavior of lexical_cast, the conventional std::stringstream approach is recommended. Where the conversions are numeric to numeric, boost::numeric_cast may offer more reasonable behavior than lexical_cast.

For a good discussion of the options and issues involved in string-based formatting, including comparison of stringstream, lexical_cast, and others, see Herb Sutter's article, The String Formatters of Manor Farm. Also, take a look at the Performance section.