std.format

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

class FormatError: object.Error;

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

void doFormat(void delegate(dchar) putc, TypeInfo[] arguments, va_list argptr);

argptr の指す可変個引数リストおよびその型情報 arguments[] を解釈し、引数リストに埋め込まれた書式文字列に従って整形し、結果の文字列を一文字ずつ putc に送ります。

可変個引数は、先頭から順に使用されます。それぞれが、型ごとのデフォルトの 書式指定 に基づいて char の列へと書式化され、その文字が順に putc に渡されます。もし char[] や wchar[] や dchar[] の型を持つ引数があれば、それは 書式文字列 として解釈されます。書式文字列 で指定されたのと同数の引数が消費され、文字列中の書式指定に従った処理ののち、putcに渡されます。引数が足りない場合、FormatErrorが投げられます。 書式指定 で必要とされたよりも多くの引数がまだ残っている場合、全て無くなるまで、デフォルトの引数の書式化を繰り返します。

Params:

void delegate(dchar) putc	出力は一文字ずつこのdelegateへ送られます。
TypeInfo[] arguments	整形される引数それぞれについてのTypeInfoの配列です。
va_list argptr	可変個引数リストへのポインタです。

Throws:
引数と書式指定の不一致が見つかった場合、FormatError が送出されます。

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

書式指定 は '%' から始まり、以下の文法で定義されています：

FormatSpecification:
    '%%'
    '%' Flags Width Precision FormatChar




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'

Flags

'-'
結果をフィールド内で左寄せにします。 0 フラグを上書きします。

'+'
符号付きの正の数の前に + をつけます。 space フラグを上書きします。

'#'
書式化方法を切り替えます：

'o' に対しては：
８進数表示の最初の１文字が '0' になるように、必要なだけ精度を拡張します。引数と Precision の双方がゼロであっても、この動作が行われます。
'x' ('X') に対しては：
非ゼロならば、頭に 0x (0X) をつけます。
浮動小数点数の書式化の場合：
常に小数点を挿入します。
'g' ('G') に対しては：
末尾のゼロを除きません。

'0'
整数や、 NaNや無限大でない浮動小数点数の出力の際に、空白文字でなく 0 で先頭を埋めます。 Precision があったら無視します。

' '
正の数の前には '+' は出力しません。

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 は有効桁数を表し、デフォルトでは 1 です。小数点の後ろでは末尾のゼロは取り除かれ、小数部がゼロならば小数点は出力されません。

'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 myPrint(...)
{
    void putc(char c)
    {
	fputc(c, stdout);
    }

    std.format.doFormat(&putc, _arguments, _argptr);
}

...

int x = 27;
// 'The answer is 27:6' と表示
myPrint("The answer is %s:", x, 6);