Difference between revisions of "cpp/string/basic string/to string"

Latest revision as of 12:29, 16 May 2024

Defined in header `<string>`
std::string to_string( int value );	(1)	(since C++11)
std::string to_string( long value );	(2)	(since C++11)
std::string to_string( long long value );	(3)	(since C++11)
std::string to_string( unsigned value );	(4)	(since C++11)
std::string to_string( unsigned long value );	(5)	(since C++11)
std::string to_string( unsigned long long value );	(6)	(since C++11)
std::string to_string( float value );	(7)	(since C++11)
std::string to_string( double value );	(8)	(since C++11)
std::string to_string( long double value );	(9)	(since C++11)

Converts a numeric value to std::string.

Let buf be an internal to the conversion functions buffer, sufficiently large to contain the result of conversion.

1) Converts a signed integer to a string as if by std::sprintf(buf, "%d", value).

2) Converts a signed integer to a string as if by std::sprintf(buf, "%ld", value).

3) Converts a signed integer to a string as if by std::sprintf(buf, "%lld", value).

4) Converts an unsigned integer to a string as if by std::sprintf(buf, "%u", value).

5) Converts an unsigned integer to a string as if by std::sprintf(buf, "%lu", value).

6) Converts an unsigned integer to a string as if by std::sprintf(buf, "%llu", value).

7,8) Converts a floating point value to a string as if by std::sprintf(buf, "%f", value).

9) Converts a floating point value to a string as if by std::sprintf(buf, "%Lf", value).

(until C++26)

1-9) Converts a numeric value to a string as if by std::format("{}", value).

(since C++26)

std::to_string relies on the current C locale for formatting purposes, and therefore concurrent calls to std::to_string from multiple threads may result in partial serialization of calls.
- The results of overloads for integer types do not rely on the current C locale, and thus implementations generally avoid access to the current C locale in these overloads for both correctness and performance. However, such avoidance is not guaranteed by the standard.

(until C++26)

C++17 provides std::to_chars as a higher-performance locale-independent alternative.

Feature-test macro	Value	Std	Feature
`__cpp_lib_to_string`	202306L	(C++26)	Redefining `std::to_string` in terms of std::format

[edit] Example

Run this code

#include <cstdio>
#include <format>
#include <initializer_list>
#include <iostream>
#include <string>
 
#if __cpp_lib_to_string >= 202306L
constexpr auto revision() { return " (post C++26)"; }
#else
constexpr auto revision() { return " (pre C++26)"; }
#endif
 
int main()
{
    for (const double f : {1.23456789555555, 23.43, 1e-9, 1e40, 1e-40, 123456789.0})
    {
        std::cout << "to_string:\t" << std::to_string(f) << revision() << '\n';
 
        // Before C++26, the output of std::to_string matches std::printf.
        std::printf("printf:\t\t%f\n", f);
 
        // As of C++26, the output of std::to_string matches std::format.
        std::cout << std::format("format:\t\t{}\n", f);
 
        std::cout << "std::cout:\t" << f << "\n\n";
    }
}

Possible output:

to_string:      1.234568 (pre C++26)
printf:         1.234568
format:         1.23456789555555
std::cout:      1.23457
 
to_string:      23.430000 (pre C++26)
printf:         23.430000
format:         23.43
std::cout:      23.43
 
to_string:      0.000000 (pre C++26)
printf:         0.000000
format:         1e-09
std::cout:      1e-09
 
to_string:      10000000000000000303786028427003666890752.000000 (pre C++26)
printf:         10000000000000000303786028427003666890752.000000
format:         1e+40
std::cout:      1e+40
 
to_string:      0.000000 (pre C++26)
printf:         0.000000
format:         1e-40
std::cout:      1e-40
 
to_string:      123456789.000000 (pre C++26)
printf:         123456789.000000
format:         123456789
std::cout:      1.23457e+08

[edit] See also

to_wstring (C++11)	converts an integral or floating-point value to `wstring` (function) [edit]
stoulstoull (C++11)(C++11)	converts a string to an unsigned integer (function) [edit]
stoistolstoll (C++11)(C++11)(C++11)	converts a string to a signed integer (function) [edit]
stofstodstold (C++11)(C++11)(C++11)	converts a string to a floating point value (function) [edit]
to_chars (C++17)	converts an integer or floating-point value to a character sequence (function) [edit]

@@ Line 1: / Line 1: @@
 {{cpp/title|to_string}}
-{{cpp/string/basic_string/sidebar}}
+{{cpp/string/basic_string/navbar}}
-{{ddcl list begin}}
+{{dcl begin}}
-{{ddcl list header | string}}
+{{dcl header|string}}
-{{ddcl list item | num=1 | notes={{mark since c++11}} |
+{{dcl|num=1|since=c++11|
 std::string to_string( int value );
 }}
-{{ddcl list item | num=2 | notes={{mark since c++11}} |
+{{dcl|num=2|since=c++11|
 std::string to_string( long value );
 }}
-{{ddcl list item | num=3 | notes={{mark since c++11}} |
+{{dcl|num=3|since=c++11|
 std::string to_string( long long value );
 }}
-{{ddcl list item | num=4 | notes={{mark since c++11}} |
+{{dcl|num=4|since=c++11|
 std::string to_string( unsigned value );
 }}
-{{ddcl list item | num=5 | notes={{mark since c++11}} |
+{{dcl|num=5|since=c++11|
 std::string to_string( unsigned long value );
 }}
-{{ddcl list item | num=6 | notes={{mark since c++11}} |
+{{dcl|num=6|since=c++11|
 std::string to_string( unsigned long long value );
 }}
-{{ddcl list item | num=7 | notes={{mark since c++11}} |
+{{dcl|num=7|since=c++11|
 std::string to_string( float value );
 }}
-{{ddcl list item | num=8 | notes={{mark since c++11}} |
+{{dcl|num=8|since=c++11|
 std::string to_string( double value );
 }}
-{{ddcl list item | num=9 | notes={{mark since c++11}} |
+{{dcl|num=9|since=c++11|
 std::string to_string( long double value );
 }}
-{{ddcl list end}}
+{{dcl end}}
--3) Converts a signed decimal integer to a string in the style ''[-]dddd''. At least one digit is written.
+Converts a numeric value to {{lc|std::string}}.
--6) Converts a unsigned decimal integer to a string in the style ''dddd''. At least one digit is written.
+{{rrev multi|until1=c++26
+|rev1=
+Let {{tti|buf}} be an internal to the conversion functions buffer, sufficiently large to contain the result of conversion.
--9) Converts a floating point value to a string in the style ''ddd.ddd''. At least {{cpp|6}} digits are written after the decimal point character.
+@1@ Converts a signed integer to a string as if by {{c|std::sprintf(buf, "%d", value)}}.
+@2@ Converts a signed integer to a string as if by {{c|std::sprintf(buf, "%ld", value)}}.
+@3@ Converts a signed integer to a string as if by {{c|std::sprintf(buf, "%lld", value)}}.
+@4@ Converts an unsigned integer to a string as if by {{c|std::sprintf(buf, "%u", value)}}.
+@5@ Converts an unsigned integer to a string as if by {{c|std::sprintf(buf, "%lu", value)}}.
+@6@ Converts an unsigned integer to a string as if by {{c|std::sprintf(buf, "%llu", value)}}.
+@7,8@ Converts a floating point value to a string as if by {{c|std::sprintf(buf, "%f", value)}}.
+@9@ Converts a floating point value to a string as if by {{c|std::sprintf(buf, "%Lf", value)}}.
+|rev2=
+@1-9@ Converts a numeric value to a string as if by {{c|std::format("{}", value)}}.
+}}
 ===Parameters===
-{{param list begin}}
+{{par begin}}
-{{param list item | value | a numeric value to convert}}
+{{par|value|a numeric value to convert}}
-{{param list end}}
+{{par end}}
 ===Return value===
-a string holding the converted value
+A string holding the converted value.
+===Exceptions===
+May throw {{lc|std::bad_alloc}} from the {{lc|std::string}} constructor.
+===Notes===
+* With floating point types {{tt|std::to_string}} may yield unexpected results as the number of significant digits in the returned string can be zero, see the example.
+* The return value may differ significantly from what {{tt|std::cout}} prints by default, see the example.
+{{rrev|until=c++26|
+* {{tt|std::to_string}} relies on the current C locale for formatting purposes, and therefore concurrent calls to {{tt|std::to_string}} from multiple threads may result in partial serialization of calls.
+** The results of overloads for integer types do not rely on the current C locale, and thus implementations generally avoid access to the current C locale in these overloads for both correctness and performance. However, such avoidance is not guaranteed by the standard.
+}}
+C++17 provides {{ltt|cpp/utility/to_chars|std::to_chars}} as a higher-performance locale-independent alternative.
+{{feature test macro|__cpp_lib_to_string|Redefining {{tt|std::to_string}} in terms of {{lc|std::format}}|std=C++26|value=202306L}}
 ===Example===
-{{example cpp|
+{{example
- | code=
+|code=
-double f = 23.43;
+#include <cstdio>
-std::string f_str = std::to_string(f);
+#include <format>
- | output=
+#include <initializer_list>
+#include <iostream>
+#include <string>
+#if __cpp_lib_to_string >= 202306L
+constexpr auto revision() { return " (post C++26)"; }
+#else
+constexpr auto revision() { return " (pre C++26)"; }
+#endif
+int main()
+{
+    for (const double f : {1.23456789555555, 23.43, 1e-9, 1e40, 1e-40, 123456789.0})
+    {
+        std::cout << "to_string:\t" << std::to_string(f) << revision() << '\n';
+        // Before C++26, the output of std::to_string matches std::printf.
+        std::printf("printf:\t\t%f\n", f);
+        // As of C++26, the output of std::to_string matches std::format.
+        std::cout << std::format("format:\t\t{}\n", f);
+        std::cout << "std::cout:\t" << f << "\n\n";
+    }
+}
+|p=true
+|output=
+to_string:      1.234568 (pre C++26)
+printf:         1.234568
+format:         1.23456789555555
+std::cout:      1.23457
+to_string:      23.430000 (pre C++26)
+printf:         23.430000
+format:         23.43
+std::cout:      23.43
+to_string:      0.000000 (pre C++26)
+printf:         0.000000
+format:         1e-09
+std::cout:      1e-09
+to_string:      10000000000000000303786028427003666890752.000000 (pre C++26)
+printf:         10000000000000000303786028427003666890752.000000
+format:         1e+40
+std::cout:      1e+40
+to_string:      0.000000 (pre C++26)
+printf:         0.000000
+format:         1e-40
+std::cout:      1e-40
+to_string:      123456789.000000 (pre C++26)
+printf:         123456789.000000
+format:         123456789
+std::cout:      1.23457e+08
 }}
 ===See also===
-{{dcl list begin}}
+{{dsc begin}}
-{{dcl list template | cpp/string/basic_string/dcl list to_wstring}}
+{{dsc inc|cpp/string/basic_string/dsc to_wstring}}
-{{dcl list end}}
+{{dsc inc|cpp/string/basic_string/dsc stoul}}
+{{dsc inc|cpp/string/basic_string/dsc stol}}
+{{dsc inc|cpp/string/basic_string/dsc stof}}
+{{dsc inc|cpp/utility/dsc to_chars}}
+{{dsc end}}
+{{langlinks|de|es|fr|it|ja|pt|ru|zh}}

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Execution support library (C++26)
Technical specifications
Symbols index
External libraries

Null-terminated strings
Byte strings
Multibyte strings
Wide strings
Classes
basic_string
basic_string_view (C++17)
char_traits

cppreference.com

Namespaces

Variants

Views

Actions

Difference between revisions of "cpp/string/basic string/to string"

Latest revision as of 12:29, 16 May 2024

Contents

[edit] Parameters

[edit] Return value

[edit] Exceptions

[edit] Notes

[edit] Example

[edit] See also

Navigation

Toolbox