std::to_chars

 

C++

言語

標準ライブラリヘッダ

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

名前付き要件

言語サポートライブラリ

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

診断ライブラリ

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

文字列ライブラリ

コンテナライブラリ

イテレータライブラリ

範囲ライブラリ (C++20)

アルゴリズムライブラリ

数値演算ライブラリ

ローカライゼーションライブラリ

入出力ライブラリ

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

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

アトミック操作ライブラリ (C++11)

スレッドサポートライブラリ (C++11)

技術仕様書

 

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

言語サポート 型サポート (基本型、RTTI、型特性) ライブラリの機能テストマクロ (C++20) 動的メモリ管理 プログラムユーティリティ エラー処理 コルーチンサポート (C++20) 可変長引数関数 launder (C++17) initializer_list (C++11) source_location (C++20) 三方比較 (C++20) three_way_comparablethree_way_comparable_with (C++20)(C++20) strong_ordering (C++20) weak_ordering (C++20) partial_ordering (C++20) common_comparison_category (C++20) compare_three_way_result (C++20) compare_three_way (C++20) strong_order (C++20) weak_order (C++20) partial_order (C++20) compare_strong_order_fallback (C++20) compare_weak_order_fallback (C++20) compare_partial_order_fallback (C++20) is_eqis_neqis_ltis_lteqis_gtis_gteq (C++20)(C++20)(C++20)(C++20)(C++20)(C++20)

汎用ユーティリティ 日付と時間 関数オブジェクト 書式化ライブラリ (C++20) bitset hash (C++11) integer_sequence (C++14) 関係演算子 (C++20で非推奨) rel_ops::operator!=rel_ops::operator>rel_ops::operator<=rel_ops::operator>= 整数比較関数 cmp_equalcmp_not_equalcmp_lesscmp_greatercmp_less_thancmp_greater_than (C++20)(C++20)(C++20)(C++20)(C++20)(C++20) in_range (C++20) スワップと型操作 swap ranges::swap (C++20) exchange (C++14) declval (C++11) forward (C++11) move (C++11) move_if_noexcept (C++11) as_const (C++17) 一般的な語彙の型 pair tuple (C++11) apply (C++17) make_from_tuple (C++17) optional (C++17) any (C++17) variant (C++17) 初等文字列変換 to_chars (C++17) from_chars (C++17) chars_format (C++17)

 

ヘッダ <charconv> で定義
std::to_chars_result to_chars(char* first, char* last,                               /*see below*/ value, int base = 10);	(1)	(C++17以上)
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, float       value); std::to_chars_result to_chars(char* first, char* last, double      value); std::to_chars_result to_chars(char* first, char* last, long double value);	(3)	(C++17以上)
std::to_chars_result to_chars(char* first, char* last, float       value,                               std::chars_format fmt); std::to_chars_result to_chars(char* first, char* last, double      value,                               std::chars_format fmt); std::to_chars_result to_chars(char* first, char* last, long double value,                               std::chars_format fmt);	(4)	(C++17以上)
std::to_chars_result to_chars(char* first, char* last, float       value,                               std::chars_format fmt, int precision); std::to_chars_result to_chars(char* first, char* last, double      value,                               std::chars_format fmt, int precision); std::to_chars_result to_chars(char* first, char* last, long double value,                               std::chars_format fmt, int precision);	(5)	(C++17以上)
struct to_chars_result {     char* ptr;     std::errc ec; };	(6)	(C++17以上)

範囲 [first, last) を連続的に埋めることによって、 value を文字列に変換します。 [first, last) は有効な範囲であることが要求されます

1) 整数のフォーマッタ。 value は base 進数の数字の文字列に変換されます (先頭の冗長なゼロは付きません)。 範囲 10..35 (両端を含む) の数字は小文字 a..z で表現されます。 値がゼロより小さい場合、表現はマイナス記号で開始されます。 ライブラリは、引数 value の型として、すべての符号付きおよび符号なし整数型および char 型に対するオーバーロードを提供します。

2) bool に対するオーバーロードは削除されています。 結果が "false"/"true" でなく "0"/"1" となることによる混乱を避けるため、 bool 型の引数は拒否されます。

3) 値は、デフォルトのロケール ("C") において std::printf によって行われたかのように、文字列に変換されます。 変換指定子は f または e であり、最も短い表現のための要件 (基数点 (もしあれば) より前に少なくとも1桁あり、対応する std::from_chars 関数を用いて表現を解析したときに値を正確に復元できるような、最小の文字数) に従って選択されます (引き分けの場合は f が優先されます)。 そのような表現が複数ある場合は、 value との差が最も小さいものが選ばれ、あらゆる残りの引き分けは std::round_to_nearest に従った丸めを用いて解決されます。

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 です。

5) (4) と同じですが、最も短い表現の要件ではなく引数 precision によって精度が指定されます。

6) 戻り値の型 (下の戻り値を参照してください)。 std::to_chars_result は基底クラスや、 ptr、 ec および暗黙に宣言された特別なメンバ関数以外のメンバを持っていません。

引数

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

戻り値

成功した場合は、 ec が値初期化された std::errc と等しく、 ptr が書き込まれた最後の文字の次を指すポインタであるような、 to_chars_result 型の値を返します。 文字列はヌル終端されないことに注意してください。

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

operator==(std::to_chars_result)

friend bool operator==( const to_chars_result&, const to_chars_result& ) = default;		(C++20以上)

両方の引数の ptr および ec がそれぞれ等しいかどうか調べます。

この関数は通常の無修飾または修飾付きの名前探索に対しては可視ではなく、 std::to_chars_result が引数の関連クラスであるときの実引数依存の名前探索によってのみ発見されます。

例外

(なし)

ノート

C++ および C のライブラリの他のフォーマット関数と異なり、 std::to_chars はロケール非依存であり、確保を行わず、例外を投げません。 他のライブラリ (std::sprintf など) によって使用されるフォーマットポリシーの小さなサブセットのみが提供されます。 これは、テキストベースのやりとり (JSON や XML) などの、一般的な高スループットの文脈において便利な、可能な最も高速な実装を可能とすることが意図されています。

to_chars によってフォーマットされたすべての浮動小数点値が std::from_chars で正確に復元できるという保証は、両方の関数が同じ処理系による場合にのみ提供されます。

bool 値を "0"/"1" としてフォーマットしたい場合は、他の整数型に明示的にキャストする必要があります。

例

Run this code

#include <iostream>
#include <charconv>
#include <system_error>
#include <string_view>
#include <array>
 
int main()
{
    std::array<char, 10> str;
 
    if(auto [p, ec] = std::to_chars(str.data(), str.data() + str.size(), 42);
       ec == std::errc())
        std::cout << std::string_view(str.data(), p - str.data());
}

出力:

42

欠陥報告

以下の動作変更欠陥報告は以前に発行された C++ 標準に遡って適用されました。

DR	適用先	発行時の動作	正しい動作
LWG 2955	C++17	this function was in <utility> and used std::error_code	moved to <charconv> and uses std::errc
LWG 3266	C++17	bool argument was accepted and promoted to int	rejected by a deleted overload
LWG 3373	C++17	to_chars_result might have additional members	additional members are disallowed

関連項目

from_chars (C++17)	文字シーケンスを整数値または浮動小数点値に変換します (関数)
to_string (C++11)	整数または浮動小数点値を string に変換します (関数)
printffprintfsprintfsnprintf (C++11)	stdout、ファイルストリームまたはバッファに書式付き出力を行います (関数)
operator<<	書式付きデータを挿入します (std::basic_ostream<CharT,Traits>のパブリックメンバ関数)