<charconv> 関数

<charconv> ヘッダーには、次の非メンバー関数が含まれています。

非メンバー関数	説明
to_chars	整数値または浮動小数点値を char のシーケンスに変換します。
from_chars	char のシーケンスを整数値または浮動小数点値に変換します。

これらの変換関数は、パフォーマンスのためにチューニングされており、最短ラウンドトリップ動作もサポートしています。 最短のラウンドトリップ動作は、数値が文字に変換されるときに、その文字を浮動小数点型に変換するときに元の数値の復旧を可能にするために、十分な有効桁数のみが書き込まれることを意味します。

• char を数値に変換する場合、数値を null 値で終了する必要はありません。 同様に、数値を char に変換する場合、結果は null で終了されません。
• 変換関数はメモリを割り当てません。 常にバッファーを所有しています。
• 変換関数はスローしません。 変換が成功したかどうかを判断できる結果が返されます。
• 変換関数は、実行時の丸めモードでは区別されません。
• 変換関数はロケールに対応しません。 小数点は常に '.' として出力および解析され、コンマを使用するローカルでは "," として解析される必要があります。

to_chars

整数値または浮動小数点値を char のシーケンスに変換します。

value を範囲 [first, last) を入力して文字列に変換します。ここで、[first, last) は有効な範囲である必要があります。 to_chars_result 構造体 を返します。 to_char_result.ec によって示される変換が成功した場合、メンバー ptr は、書き込まれた文字の 1 つ後の最後のポインターになります。 それ以外の場合、to_char_result.ec に errc::value_too_large の値があり、to_char_result.ptr に last の値があり、範囲 [first, last) の内容は指定されていません。

to_chars が失敗する可能性がある唯一の方法は、結果を保持するために十分に大きくないバッファーを指定する場合です。

// integer to chars

to_chars_result to_chars(char* first, char* last, char value, int base = 10);
to_chars_result to_chars(char* first, char* last, signed char value, int base = 10);
to_chars_result to_chars(char* first, char* last, unsigned char value, int base = 10);
to_chars_result to_chars(char* first, char* last, short value, int base = 10);
to_chars_result to_chars(char* first, char* last, unsigned short value, int base = 10);
to_chars_result to_chars(char* first, char* last, int value, int base = 10);
to_chars_result to_chars(char* first, char* last, unsigned int value, int base = 10);
to_chars_result to_chars(char* first, char* last, long value, int base = 10);
to_chars_result to_chars(char* first, char* last, unsigned long value, int base = 10);
to_chars_result to_chars(char* first, char* last, long long value, int base = 10);
to_chars_result to_chars(char* first, char* last, unsigned long long value, int base = 10);
to_chars_result to_chars(char* first, char* last, bool value, int base = 10) = delete;

// floating-point to chars

to_chars_result to_chars(char* first, char* last, float value);
to_chars_result to_chars(char* first, char* last, double value);
to_chars_result to_chars(char* first, char* last, long double value);
to_chars_result to_chars(char* first, char* last, float value, chars_format fmt);
to_chars_result to_chars(char* first, char* last, double value, chars_format fmt);
to_chars_result to_chars(char* first, char* last, long double value, chars_format fmt);
to_chars_result to_chars(char* first, char* last, float value, chars_format fmt, int precision);
to_chars_result to_chars(char* first, char* last, double value, chars_format fmt, int precision);
to_chars_result to_chars(char* first, char* last, long double value, chars_format fmt, int precision);

パラメーター

first
塗りつぶすバッファーの先頭を指します。

last
埋めるバッファーの末尾の 1 文字をポイントします。

value
変換する値。 value が負の場合、表現は - で始まります。

base
整数変換の場合、value をchars に変換するときに使用するベース。 包括的に、2 と 36 の間でなければなりません。 先頭にゼロはありません。 10..35 (包含) の範囲の数字は、小文字 a..z として表されます。

fmt
浮動小数点変換の場合、使用する変換形式 (指数、固定、16 進数など) を指定するビットマスク。 詳細については chars_format を参照してください。

有効桁数 (precision)
浮動小数点変換の場合、変換された値の有効桁数。

戻り値

変換の結果を格納している to_chars_result。

解説

chars_format パラメーターを受け取る関数は、次のように、変換指定子が printf() を使用している場合と同様に決定します。変換指定子は、fmt が chars_format::fixed の場合、'f' であり、fmt が chars_format::scientific の場合は 'e' です。fmt が先頭の 0x なしで chars_format::hex の場合は 'a' です。fmt が chars_format::general の場合は 'g' です。 最短の固定表記を指定すると、値が非常に大きい場合や非常に小さい場合に、可能な限り短い表現になる可能性があります。出力が長い場合があります。

次の表では、fmt パラメーターと precision パラメーターの異なる組み合わせを指定した変換動作について説明します。 "最短ラウンドトリップ動作" という用語は、対応する from_chars 関数を使用してその表現を解析すると値が正確に回復される、必要な桁数の最も少ない数字を書き込むことを指します。

fmt と precision の組み合わせ	出力
どちらもオフ	固定小数点表記と指数表記のどちらか短い方。タイブレーカーとしては固定小数点表記が優先されます。 この動作は、fmt パラメーターを受け取るオーバーロードではシミュレートされません。
fmt	指定した形式の最短ラウンド トリップ動作 (最短の指数形式など)。
fmt および precision	最短のラウンドトリップ動作を行わずに、printf() スタイルに従って、指定された有効桁数を使用します。

例

#include <charconv>
#include <stdio.h>
#include <system_error>

template <typename T> void TestToChars(const T t)
{
    static_assert(std::is_floating_point_v<T>);
    constexpr bool IsFloat = std::is_same_v<T, float>;

    char buf[100]; // 100 is large enough for double and long double values because the longest possible outputs are "-1.23456735e-36" and "-1.2345678901234567e-100".
    constexpr size_t size = IsFloat ? 15 : 24;
    const std::to_chars_result res = std::to_chars(buf, buf + size, t);  // points to buffer area it can use. Must be char, not wchar_t, etc.

    if (res.ec == std::errc{}) // no error
    {
        // %.*s provides the exact number of characters to output because the output range, [buf, res.ptr), isn't null-terminated
        printf("success: %.*s\n", static_cast<int>(res.ptr - buf), buf);
    }
    else // probably std::errc::value_too_large
    {
        printf("Error: %d\n", static_cast<int>(res.ec));
    }
}

int main()
{
    TestToChars(123.34);
    return 0;
}

from_chars

char のシーケンスを整数値または浮動小数点値に変換します。

// char to an integer value

from_chars_result from_chars(const char* first, const char* last, char& value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, signed char& value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, unsigned char& value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, short& value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, unsigned short& value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, int& value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, unsigned int& value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, long& value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, unsigned long& value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, long long& value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, unsigned long long& value, int base = 10);

// char to a floating-point value

from_chars_result from_chars(const char* first, const char* last, float& value, chars_format fmt = chars_format::general);
from_chars_result from_chars(const char* first, const char* last, double& value, chars_format fmt = chars_format::general);
from_chars_result from_chars(const char* first, const char* last, long double& value, chars_format fmt = chars_format::general);

パラメーター

first
変換する文字のバッファーの先頭をポイントします。

last
変換する文字のバッファーの最後の要素の 1 つ後ろを指します。

value
変換が成功した場合、には変換の結果が格納されます。

base
整数変換の場合、変換時に使用するベース。 包括的に、2 と 36 の間でなければなりません。

fmt
浮動小数点変換の場合、変換される文字のシーケンスの形式。 詳細については chars_format を参照してください。

解説

from_chars() 関数は、数値パターンの文字列 [first, last) を分析します。ここで、[first, last) は有効な範囲である必要があります。

文字を解析する場合、空白は無視されません。 strtod() と異なり、たとえば、バッファーは有効な数値表現で始まる必要があります。

from_chars_result 構造体を返します。

数値パターンに一致する文字がない場合、value は変更なし、from_chars_result.ptr は first をポイントし、from_chars_result.ec は errc::invalid_argument です。

一部の文字だけが数値パターンに一致する場合、from_chars_result.ptr はパターンと一致しない最初の文字をポイントするか、すべての文字が一致する場合は last パラメーターの値を持っています。

解析された値が value の型で表される範囲内に含められない場合、value は変更されず、from_chars_result.ec は errc::result_out_of_range です。

それ以外の場合、value は丸め後に解析された値に設定され、from_chars_result.ec は errc{} と等しくなります。

例

#include <charconv>
#include <stdio.h>
#include <string_view>
#include <system_error>

double TestFromChars(const std::string_view sv)
{
    const char* const first = sv.data();
    const char* const last = first + sv.size();
    double dbl;

    const std::from_chars_result res = std::from_chars(first, last, dbl);

    if (res.ec == std::errc{}) // no error
    {
        printf("success: %g\n", dbl);
    }
    else
    {
        printf("Error: %d\n", static_cast<int>(res.ec));
    }

    return dbl;
}

int main()
{
    double dbl = TestFromChars("123.34");
    return 0;
}

要件

ヘッダー:<charconv>

名前空間: std

/std:c++17 以降が必要です。

関連項目

<charconv>
ラウンドトリップする最短の 10 進数文字列printf() 形式の指定子