std::to_chars

 

C++

コンパイラサポート

フリースタンディングとホスト

言語

標準ライブラリ

標準ライブラリヘッダー

名前付き要件

機能テストマクロ (C++20)

言語サポートライブラリ

コンセプトライブラリ (C++20)

診断ライブラリ

メモリ管理ライブラリ

メタプログラミングライブラリ (C++11)

汎用ユーティリティライブラリ

コンテナライブラリ

イテレータライブラリ

Rangesライブラリ (C++20)

アルゴリズムライブラリ

文字列ライブラリ

テキスト処理ライブラリ

数値ライブラリ

日付と時刻ライブラリ

入出力ライブラリ

ファイルシステムライブラリ (C++17)

並行サポートライブラリ (C++11)

実行制御ライブラリ (C++26)

Technical specifications (技術仕様)

シンボルインデックス

外部ライブラリ

 

テキスト処理ライブラリ

ローカライズライブラリ

正規表現ライブラリ (C++11)

フォーマットライブラリ (C++20)

ヌル終端シーケンスユーティリティ

バイト文字列

マルチバイト文字列

ワイド文字列

プリミティブな数値変換

to_chars (C++17) to_chars_result (C++17) from_chars (C++17) from_chars_result (C++17) chars_format (C++17)

テキストエンコーディング識別

text_encoding (C++26)

 

ヘッダー <charconv> で定義
std::to_chars_result     to_chars( char* first, char* last,               /* integer-type */ value, int base = 10 );	(1)	(C++17以降) (C++23 以降 constexpr)
std::to_chars_result     to_chars( char*, char*, bool, int = 10 ) = delete;	(2)	(C++17以降)
std::to_chars_result     to_chars( char* first, char* last, /* floating-point-type */ value );	(3)	(C++17以降)
std::to_chars_result     to_chars( char* first, char* last, /* floating-point-type */ value,               std::chars_format fmt );	(4)	(C++17以降)
std::to_chars_result     to_chars( char* first, char* last, /* floating-point-type */ value,               std::chars_format fmt, int precision );	(5)	(C++17以降)

value を、範囲 [first, last) に文字を順次書き込むことで文字列に変換します。ここで、[first, last) は 有効な範囲 である必要があります。

1) 整数フォーマッタ: value は、指定された base の桁の文字列に変換されます (冗長な先行ゼロはなし)。10..35 (両端を含む) の範囲の数字は小文字の a..z として表現されます。value が負の場合、表現はマイナス記号で始まります。ライブラリは、すべての cv-unqualified(C++23 以降) 符号付きおよび符号なし整数型、およびパラメーター value の型としての char 型のオーバーロードを提供します。

2) bool のオーバーロードは削除されます。std::to_chars は、型 bool の引数を拒否します。なぜなら、許可された場合、結果は "0"/"1" になり、"false"/"true" にはならないためです。

3) value は、デフォルトの ("C") ロケールにおける std::printf のように文字列に変換されます。変換指定子は f または e (同点の場合は f が優先される) であり、最短表現の要件に従って選択されます。文字列表現は、小数点 (存在する場合) の前に少なくとも1桁の数字があり、対応する std::from_chars 関数を使用して表現を解析すると value を正確に復元できる最小の文字数で構成されます。そのような表現が複数ある場合、value との差が最小のものが選択され、残りの同点は std::round_to_nearest に従って丸め処理を使用して解決されます。ライブラリは、パラメーター value の型として、すべての cv-unqualified 標準(C++23 まで) 浮動小数点型のオーバーロードを提供します。

4) (3) と同じですが、仮想 printf に指定される変換は、fmt が std::chars_format::fixed の場合は f、fmt が std::chars_format::scientific の場合は e、fmt が std::chars_format::hex の場合は a (ただし、結果に先行 "0x" はなし)、fmt が chars_format::general の場合は g となります。ライブラリは、パラメーター value の型として、すべての cv-unqualified 標準(C++23 まで) 浮動小数点型のオーバーロードを提供します。

5) (4) と同じですが、精度が最短表現要件ではなくパラメーター precision によって指定されます。ライブラリは、パラメーター value の型として、すべての cv-unqualified 標準(C++23 まで) 浮動小数点型のオーバーロードを提供します。

パラメーター

first, last	-	書き込み先の文字範囲
value	-	文字列表現に変換する値
base	-	使用する整数基数: 2 から 36 (両端を含む) の値。
fmt	-	使用する浮動小数点書式設定。型 std::chars_format のビットマスク。
precision	-	使用する浮動小数点精度

戻り値

成功した場合、std::to_chars_result 型の値を返します。その際、ec は値初期化された std::errc と等しく、ptr は書き込まれた文字の終端の次を指すポインターです。文字列は NUL 終端されません。

エラーの場合、std::to_chars_result 型の値を返します。この値は、ec に std::errc::value_too_large を保持し、ptr に last の値のコピーを保持し、範囲 [first, last) の内容は未指定の状態になります。

例外

何もスローしません。

備考

C++ および C ライブラリの他の書式設定関数とは異なり、std::to_chars はロケールに依存せず、メモリ割り当てを行わず、例外をスローしません。他のライブラリ (例: std::sprintf) で使用される書式設定ポリシーのごく一部のみが提供されます。これは、テキストベースの交換 (例: JSON や XML) のような一般的な高スループットのコンテキストで役立つ、可能な限り最速の実装を可能にすることを意図しています。

std::from_chars が std::to_chars によって書式設定されたすべての浮動小数点値を正確に復元できるという保証は、両方の関数が同じ実装のものである場合にのみ提供されます。

bool 値を "0"/"1" として書式設定したい場合は、明示的に別の整数型にキャストする必要があります。

機能テストマクロ	値	規格	機能
__cpp_lib_to_chars	201611L	(C++17)	基本的な文字列変換 (std::to_chars, std::from_chars)
	202306L	(C++26)	<charconv> 関数の成功または失敗のテスト
__cpp_lib_constexpr_charconv	202207L	(C++23)	整数型に対する std::to_chars および std::from_chars オーバーロード (1) に constexpr 修飾子を追加

例

このコードを実行

#include <charconv>
#include <iomanip>
#include <iostream>
#include <string_view>
#include <system_error>
 
void show_to_chars(auto... format_args)
{
    const size_t buf_size = 10;
    char buf[buf_size]{};
    std::to_chars_result result = std::to_chars(buf, buf + buf_size, format_args...);
 
    if (result.ec != std::errc())
        std::cout << std::make_error_code(result.ec).message() << '\n';
    else
    {
        std::string_view str(buf, result.ptr - buf);
        std::cout << std::quoted(str) << '\n';
    }
}
 
int main()
{
    show_to_chars(42);
    show_to_chars(+3.14159F);
    show_to_chars(-3.14159, std::chars_format::fixed);
    show_to_chars(-3.14159, std::chars_format::scientific, 3);
    show_to_chars(3.1415926535, std::chars_format::fixed, 10);
}

実行結果の例

"42"
"3.14159"
"-3.14159"
"-3.142e+00"
Value too large for defined data type

欠陥報告

以下の動作変更を伴う欠陥報告が、以前に公開されたC++標準に遡って適用されました。

DR	適用対象	公開された動作	正しい動作
LWG 2955	C++17	この関数は <utility> にあり、std::error_code を使用していました	<charconv> に移動し、std::errc を使用するように変更されました
LWG 3266	C++17	bool 引数が受け入れられ、int に昇格していました	削除されたオーバーロードによって拒否されるようになりました
LWG 3373	C++17	std::to_chars_result が追加のメンバーを持つ可能性がある	追加のメンバーは許可されません

関連項目

to_chars_result (C++17)	std::to_chars の戻り値の型 (クラス)
from_chars (C++17)	文字シーケンスを整数値または浮動小数点数値に変換する (関数)
to_string (C++11)	整数値または浮動小数点値を string に変換する (function)
printffprintfsprintfsnprintf (C++11)	stdout、ファイルストリーム、またはバッファにフォーマットされた出力を書き込む (関数)
operator<<	書式付きデータを挿入する (std::basic_ostream<CharT,Traits>のpublicメンバ関数)