std.format

Authors:
Walter Bright, Andrei Alexandrescu

このモジュールは、文字列や入出力の書式化を支える機能を実装しています。 C99の vsprintf() に似ている面があります。

class FormatError: object.Error;

書式と対応する引数の型があっていないことを示します。

void formattedWrite(Writer, Char, A...)(Writer w, in Char[] fmt, A args);

可変個引数リスト args を、書式文字列 fmt に従って整形し、結果を w に送ります。出力のエンコーディングは Char と同じになります。 Writer 型は std.range.isOutputRange!(Writer, Char) を満たす必要があります。

可変個引数は、先頭から順に使用されます。POSIXの位置指定構文も使用可能です。それぞれの引数が、書式指定に基づいて文字の列へと書式化され、その文字が順に w に渡されます。書式文字列で指定されたのとピッタリ同数の引数が消費されます。引数が足りない場合は、FormatError 例外となります。書式文字列で必要とされたよりも多くの引数がまだ残っている場合、一つでも書式化出力済みであれば、残りは無視されます。

Parameters:

w	出力はこのWriterに送られます。典型的なWriterの例としては、 std.range.Appender!string や std.stdio.BlockingTextWriter など
fmt	書式指定文字列
args	可変個引数リスト

Throws:
引数と書式指定の不一致が見つかった場合、FormatError を投げます。

Format String:
書式文字列 は、途中に 書式指定 を挟む文字の列です。通常の文字は、対応するUTF-8のコード列への変換のあと、単純に出力にコピーされます。

書式指定 は以下の文法で定義されています：

FormatString:
    FormatStringItem*
FormatStringItem:
    '%%'
    '%' Position Flags Width Precision FormatChar
    '%(' FormatString '%)'
    OtherCharacterExceptPercent
Position:
    empty
    Integer '$'
Flags:
    empty
    '-' Flags
    '+' Flags
    '#' Flags
    '0' Flags
    ' ' Flags
Width:
    empty
    Integer
    '*'
Precision:
    empty
    '.'
    '.' Integer
    '.*'
Integer:
    Digit
    Digit Integer
Digit:
    '0'|'1'|'2'|'3'|'4'|'5'|'6'|'7'|'8'|'9'
FormatChar:
    's'|'b'|'d'|'o'|'x'|'X'|'e'|'E'|'f'|'F'|'g'|'G'|'a'|'A'

書式化の方法に影響するフラグ
フラグ	影響する型	意味
'-'	数値	結果を左寄せする。 0 フラグを上書きする
'+'	数値	正の値の頭に + をつける。space フラグを上書きする
'#'	整数 ('o')	八進表現の先頭に'0'が入るように精度を増やす。引数と精度の双方が0であっても増やす。
'#'	整数 ('x', 'X')	ゼロでなければ、結果の先頭に 0x (0X) をつける
'#'	浮動小数点数	常に小数点と末尾のゼロをつける
'#'	数値 ('0')	Use leading zeros to pad rather than spaces (except for the floating point values nan and infinity). Ignore if there's a Precision.
' '	整数 ('d')	正の数の先頭にスペースを入れる

Width

フィールドの最小幅を指定します。 * を指定した場合、次の引数（int型でなければなりません）が、幅として使用されます。負の数を指定した場合、- が Flags に指定された場合と同等に振る舞います。

Precision

数値変換の精度を与えます。 * を指定した場合、次の引数（int型でなければなりません）が、幅として使用されます。負の数を指定した場合、Precision を指定しなかったのと同じことになります。

FormatChar

's'

対応する引数は、その型に適した方法で書式化されます：

bool: 'true' か 'false' になります。
整数型: %d 形式です。
浮動小数点数: %g 形式です。
文字列型: UTF-8に変換された文字列が結果となります。 Precision 文字を越えた分は捨てられます。（※原文：A Precision specifies the maximum number of characters to use in the result. 意味とりちがえてるかも…）
Object から派生したクラス: インスタンスの .toString() メソッドが返す文字列です。 Precision 文字を越えた分は捨てられます。（※原文：A Precision specifies the maximum number of characters to use in the result. 意味とりちがえてるかも…）
文字列以外の静的/動的配列: 結果は、s_kをk番目の要素をデフォルトの書式化したものとすると、 [s₀, s₁, ...] となります。

'b','d','o','x','X'

対応する引数は整数型でなくてはなりません。引数が符号付きの型で FormatChar が d ならば、符号のついた文字列へと変換されます。そうでなければ、符号無しの数として処理されます。bool 型の引数は '1' か '0' になります。二進表記には b、八進には o, 十進には d、十六進には x か X を指定します。 x は小文字、X は大文字を使います。 Precision, で指定したよりも実際の文字数が少なかった場合、必要なだけ頭に0がつきます。Precision が 0 で数値も 0 の場合は、数字は出力されません。

'e','E'

浮動小数点数を、小数点の前に一桁、後に Precision 桁、'e'もしくは'E'、 ±、最低二桁の指数部、という形で書式化します：d.dddddde±dd. Precision が指定されていない場合、小数点のあとには六桁出力されます。 Precision が 0 ならば、小数点は出力されません。

'f','F'

浮動小数点数を、十進記法で書式化します。 Precision は、小数点の下に出力する桁数を指定します。デフォルトは 6 です。小数点の前には少なくとも一桁は出力されます。 Precision が 0 ならば、小数点は出力されません。

'g','G'

g に対しては e または f、G に対しては E または F で浮動小数点数を書式化します。 e 方式で出力した場合の指数部が -5 より大きく Precision より小さくなるならば、f 方式が使用されます。 Precision は有効桁数を表し、デフォルトでは 6 です。小数点の後ろでは末尾のゼロは取り除かれ、小数部がゼロならば小数点は出力されません。

'a','A'

浮動小数点数は、十六進の指数表記 0xh.hhhhhhp±d へと書式化されます。小数点の前には丁度一桁、後ろには Precision 桁の数字が並びます。 Precision がゼロの時は、小数点は出力されません。 Precision が指定されていないときは、仮数部を表現するのに必要十分な桁まで出力されます。指数部（h.hhhhhh*2^±d のように2の累乗を表す）は、できるだけ少ない文字数で、十進で表記されます。 0 に対する指数部は 0 です。十六進の数値と、x、pは、 FormatChar が大文字の 'A' ならばあわせて大文字になります。

浮動小数点数のNaN値は、FormatChar が小文字ならば nan、大文字ならば NAN と出力されます。浮動小数点数の無限大値は、FormatChar が小文字ならば inf ないしは infinity、大文字ならば INF ないしは INFINITY と出力されます。

Example:

import std.c.stdio;
import std.format;

void main()
{
    auto writer = appender!string();
    formattedWrite(writer, "%s is the ultimate %s.", 42, "answer");
    assert(writer.data == "42 is the ultimate answer.");
    // Clear the writer
    writer = appender!string();
    formattedWrite(writer, "Date: %2$s %1$s", "October", 5);
    assert(writer.data == "Date: 5 October");
}

一つの書式指定文字列の中に、位置指定とそうでないスタイルを混在させることができます（POSIXではこれは未定義です）。位置指定無し引数のための内部カウンタは、使用済みの最大の位置指定の次の引数を指すように値が追跡されます。

uint formattedRead(R, Char, S...)(ref R r, const(Char)[] fmt, S args);

入力レンジ r から値を読み込み、 fmt に従って変換し、args に書き込みます。

Example:

string s = "hello!124:34.5";
string a;
int b;
double c;
formattedRead(s, "%s!%s:%s", &a, &b, &c);
assert(a == "hello" && b == 124 && c == 34.5);

struct FormatSpec(Char);

個々の書式指定のコンパイル済みバージョンです。 printf との互換性があります。

int width;: 最小幅。デフォルトは 0
int precision;: 精度。意味は型に依って変わります。浮動小数点数では、表示する桁数を意味します。
int DYNAMIC;: 幅と精度のための特殊な値。DYNAMIC な幅や精度は、'*' を指定したときに設定され、可変個引数を通して実行時に指定されることを意味します。
int UNSPECIFIED;: 精度のための特殊な値。特に値が指定されていないことを表します。
char spec;: 実際の書式指定子。デフォルトは 's'
ubyte index;: 位置指定引数のインデックス。1 から ubyte.max が入ります。(0 は使用されていないことを意味します)
bool flDash;: 書式指定に '-' が含まれていたことを意味します。(printf 互換)
bool flZero;: 書式指定に '0' が含まれていたことを意味します。(printf 互換)
bool flSpace;: 書式指定に ' ' が含まれていたことを意味します。(printf 互換)
bool flPlus;: 書式指定に '+' が含まれていたことを意味します。(printf 互換)
bool flHash;: 書式指定に '#' が含まれていたことを意味します。(printf 互換)
const(Char)[] nested;: "%(" で始まり "%)" で終わる複合指定の場合に設定されます。nested には、この二つの括弧の中に含まれていた文字列が入ります。
const(Char)[] trailing;: trailing には残りの書式指定文字列が入ります。
this(in Char[] fmt);: 書式指定文字列 fmt を受け取り、解析します。文字列は '%' の直後の文字から始まると仮定されます。文字列は書式指定の終わったすぐ後まで進みます。