std.format

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

class FormatError: object.Error;

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

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

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

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

Params:

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

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

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

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

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 は有効桁数を表し、デフォルトでは 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 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);

struct StringWriter(Char);

文字列へのWriterインターフェイスを実装しています。 StringWriter!(char) や StringWriter!(wchar) や StringWriter!(dchar) のように文字型でインスタンス化して使います。どの型でインスタンス化しても StringWriter はどの文字種も受け付けます。ただし、インスタンス化の際に与えた文字種をもっとも効率的に処理できるようになっています。