Last Update:
How to Use The Newest C++ String Conversion Routines - std::from_chars
Table of Contents
With C++17 we get another facility to handle the conversion between text and numbers. Why should we care about the new routines?
Are they better in any way?
Before C++17
C++, before C++17, offered several options when it comes to string conversion:
sprintf
/snprintf
sscanf
atol
strtol
strstream
stringstream
to_string
stoi
and similar functions
And with C++17 you get another option: std::from_chars
! Wasn’t the old stuff good enough? Why do we need new methods?
In short: because from_chars
is low-level, and offers the best possible performance.
The new conversion routines are:
- non-throwing
- non-allocating
- no locale support
- memory safety
- error reporting gives additional information about the conversion outcome
The API might not be the most friendly to use, but it’s easy enough to wrap it into some facade.
A simple example:
const std::string str { "12345678901234" };
int value = 0;
std::from_chars(str.data(),str.data() + str.size(), value);
// error checking ommited...
The new functions are available in the following compilers:
- Visual Studio 2019 16.4 - full support, and early floating-point support from VS 2017 15.7
- GCC - 11.0 - full support, and since GCC 8.0 - integer support only
- Clang 7.0 - still in progress, only integer support
If you want to read more about existing conversion routines, new ones and also see some benchmarks you can see two great posts at @fluentcpp:
How to Convert a String to an int in C++ and How to *Efficiently* Convert a String to an int in C++ written by JFT.
The Series
This article is part of my series about C++17 Library Utilities. Here’s the list of the topics in the series:
- Refactoring with
std::optional
- Using
std::optional
- Error handling and
std::optional
- Everything You Need to Know About
std::variant
from C++17 - Everything You Need to Know About
std::any
from C++17 std::string_view
Performance and followup- C++17 string searchers and followup
- Conversion utilities: on
std::from_chars
- from a string to a number and onstd::to_chars
- from numbers into strings - How to get File Size in C++? and std:filesystem::file_size Advantages and Differences
- How To Iterate Through Directories
Resources about C++17 STL:
- C++17 In Detail by Bartek!
- C++17 - The Complete Guide by Nicolai Josuttis
- C++ Fundamentals Including C++ 17 by Kate Gregory
- Practical C++14 and C++17 Features - by Giovanni Dicanio
- C++17 STL Cookbook by Jacek Galowicz
Let’s have a look at the API now.
Converting From Characters to Numbers: from_chars
std::from_chars
is a set of overloaded functions: for integral types and floating point types.
For integral types we have the following functions:
std::from_chars_result from_chars(const char* first,
const char* last,
TYPE &value,
int base = 10);
Where TYPE
expands to all available signed and unsigned integer types and char
.
base
can be a number ranging from 2 to 36.
Then there’s the floating point version:
std::from_chars_result from_chars(const char* first,
const char* last,
FLOAT_TYPE& value,
std::chars_format fmt = std::chars_format::general);
FLOAT_TYPE
expands to float
, double
or long double
.
chars_format
is an enum with the following values: scientific
,
fixed
, hex
and general
(which is a composition of fixed
and scientific
).
The return value in all of those functions (for integers and floats) is from_chars_result
:
struct from_chars_result {
const char* ptr;
std::errc ec;
};
from_chars_result
holds valuable information about the conversion process.
Here’s the summary:
Return Condition | State of from_chars_result |
---|---|
Success | ptr points at the first character not matching the pattern, or has the value equal to last if all characters match and ec is value-initialized. |
Invalid conversion | ptr equals first and ec equals std::errc::invalid_argument . value is unmodified. |
Out of range | The number it too large to fit into the value type. ec equals std::errc::result_out_of_range and ptr points at the first character not matching the pattern. value is unmodified. |
The new routines are very low level, so you might be wondering why is that. Titus Winters added a great summary in comments:
The intent of those APIs is *not* for people to use them directly, but to build more interesting/useful things on top of them. These are primitives, and we (the committee) believe they have to be in the standard because there isn’t an efficient way to do these operations without calling back out to nul-terminated C routines
Examples
Here are two examples of how to convert a string into a number using from_chars
, to int
andfloat
.
Integral types
#include <charconv> // from_char, to_char
#include <string>
#include <iostream>
int main() {
const std::string str { "12345678901234" };
int value = 0;
const auto res = std::from_chars(str.data(),
str.data() + str.size(),
value);
if (res.ec == std::errc())
{
std::cout << "value: " << value
<< ", distance: " << res.ptr - str.data() << '\n';
}
else if (res.ec == std::errc::invalid_argument)
{
std::cout << "invalid argument!\n";
}
else if (res.ec == std::errc::result_out_of_range)
{
std::cout << "out of range! res.ptr distance: "
<< res.ptr - str.data() << '\n';
}
}
The example is straightforward, it passes a string str
into from_chars
and then displays the result with additional information if possible.
Run the code below and change the str
value to see the output:
Does “12345678901234” fit into the number? Or you see some errors from the conversion API?
Floating Point
To get the floating point test, we can replace the top lines of the previous example with:
// works with MSVC only and GCC 11
const std::string str { "16.78" };
double value = 0;
const auto format = std::chars_format::general;
const auto res = std::from_chars(str.data(),
str.data() + str.size(),
value,
format);
Here’s the example output that we can get:
str value |
format value |
output |
---|---|---|
1.01 |
fixed |
value: 1.01, distance 4 |
-67.90000 |
fixed |
value: -67.9, distance: 9 |
20.9 |
scientific |
invalid argument!, res.ptr distance: 0 |
20.9e+0 |
scientific |
value: 20.9, distance: 7 |
-20.9e+1 |
scientific |
value: -209, distance: 8 |
F.F |
hex |
value: 15.9375, distance: 3 |
-10.1 |
hex |
value: -16.0625, distance: 5 |
The general
format is a combination of fixed
and scientific
so it handles regular floating point string with the additional support for e+num
syntax.
Performance
I did some benchmarks, and the new routines are blazing fast!
Some numbers:
- On GCC it’s around 4.5x faster than
stoi
, 2.2x faster thanatoi
and almost 50x faster thanistringstream
. - On Clang it’s around 3.5x faster than
stoi
, 2.7x faster thanatoi
and 60x faster thanistringstream
! - MSVC performs around 3x faster than
stoi
, ~2x faster thanatoi
and almost 50x faster thanistringstream
You can find the results in my book on C++17: “C++17 in Detail”.
Summary
If you want to convert text into a number and you don’t need any extra stuff like locale support then std::from_chars
might be the best choice. It offers great performance, and what’s more, you’ll get a lot of information about the conversion process (for example how much characters were scanned).
The routines might be especially handy with parsing JSON files, 3d textual model representation (like OBJ file formats), etc.
Your Turn
- Have you played with the new conversion routines?
- What do you usually use to convert text into numbers?
I've prepared a valuable bonus if you're interested in Modern C++!
Learn all major features of recent C++ Standards!
Check it out here:
Similar Articles:
- How to Convert Numbers into Text with std::to_chars in C++17
- How To Detect Function Overloads in C++17/20, std::from_chars Example
- How to Boost Performance with Intel Parallel STL and C++17 Parallel Algorithms
- Let's Talk About String Operations in C++17
- Speeding Up string_view String Split Implementation