System.SysUtils.Format
Delphi
function Format(const Format: string; const Args: array of const): string;
const AFormatSettings: TFormatSettings): string;
C++
extern DELPHI_PACKAGE System::UnicodeString __fastcall Format(const System::UnicodeString Format, const System::TVarRec *Args, const System::NativeInt Args_High)/* overload */;
プロパティ
| 種類 | 可視性 | ソース | ユニット | 親 |
|---|---|---|---|---|
| function | public | System.SysUtils.pas System.SysUtils.hpp |
System.SysUtils | System.SysUtils |
説明
書式文字列と引数の配列から、組み立てられた書式付き文字列を返します。
Format 関数は、オープン（型なし）配列にある一連の引数を整形します。
Format は書式文字列です。書式文字列の詳細については、本トピックで説明されている「書式文字列」を参照してください。
Args は、引数の配列で、Format での書式指定子が適用されます。C++ の場合、Args_High は、Args の最後の要素のインデックスを指定します（エレメント数 - 1）。
Format は、Args 内の引数に書式文字列 Format を適用した結果を返します。
2 つの構文形式は、Format によって指定されます。Format の第 1 の形式は、グローバル変数に含まれているローカライズ情報を使用するため、スレッド セーフではありません。 Format の第 2 の形式は、AFormatSettings パラメータに含まれているローカライズ情報を参照し、スレッドに対応しています。 Format のスレッド セーフ形式を呼び出す前に、AFormatSettings にローカライズ情報を入れる必要があります。 AFormatSettings にデフォルトのローカル値セットを入れるには、TFormatSettings.Create を呼び出します。
書式文字列
書式文字列は、汎用目的の整形ルーチンに必要な書式を指定します。文字列整形ルーチンに渡される書式文字列には、2 つのタイプのオブジェクト -- リテラル文字列と書式指定子 -- が含まれています。リテラル文字列は、結果文字列となる語にコピーされる語です。書式指定子は、引数リストから引数を取得し、書式設定をそれぞれに適用します。
書式指定子には次に形式があります：
"%" [index ":"] ["-"] [width] ["." prec] type
書式指定子は % 文字で始まります。パーセント文字 % の後、次の要素が以下の順できます：
- （任意）引数 0 オフセット インデックス指定子（つまり、最初の項目のインデックスが 0）、
[index ":"]。 - （任意）左揃えインジケータ、
["-"]。 - （任意）幅指定子、
[width]。 - （任意）精度指定子、
["." prec]。 - 変換型文字、
type。
次の表は、型に対する利用可能な値の概要です：
| 値 | 意味 |
|---|---|
|
|
10 進数です。 引数は整数値でなければなりません。 値は 10 進数の文字列に変換されます。 書式文字列に精度指定子が含まれている場合は、結果の文字列に少なくとも指定された桁数がなければならないことを示しています。値の桁数が指定より少ない場合は、結果の文字列の左側がゼロで埋められます。 |
|
|
符号なし10進数。 |
|
|
科学表記。 引数は浮動小数点値でなければなりません。 値は "-d.ddd...E+ddd" という形式の文字列に変換されます。 負の数値の場合、結果の文字列はマイナス記号で始まります。 小数点の前は必ず 1 桁です。 結果の文字列の総桁数（小数点の前の 1 桁も含む）は、書式文字列の精度指定子で指定します。精度指定子がない場合は、デフォルト精度の 15 と見なされます。 結果の文字列に含まれる指数文字 "E" の後ろには、常に、プラス記号かマイナス記号と、少なくとも 3桁の数字が続きます。 |
|
|
固定 引数は浮動小数点値でなければなりません。 値は "-ddd.ddd..." という形式の文字列に変換されます。 負の数値の場合、結果の文字列はマイナス記号で始まります。 小数点より後ろの桁数は、書式文字列の精度指定子で指定します。精度指定子がない場合は、デフォルトの 10 進 2 桁と見なされます。 |
|
|
汎用。引数は浮動小数点値でなければなりません。 値は、固定形式または科学表記形式を使用して、できるだけ短い 10 進数の文字列に変換されます。 結果の文字列の有効桁数は、書式文字列の精度指定子で指定します。精度指定子がない場合は、デフォルト精度の 15 と見なされます。 末尾のゼロは結果の文字列から削除され、小数点は必要な場合にのみ表示されます。 値の小数点より左の桁数が指定された精度以下で、その値が 0.00001 以上の場合、結果の文字列には固定小数点形式が使われます。 それ以外の場合、結果の文字列には科学表記形式が使われます。 |
|
|
数値。引数は浮動小数点値でなければなりません。 値は "-d,ddd,ddd.ddd..." という形式の文字列に変換されます。 |
|
|
通貨。引数は浮動小数点値でなければなりません。 値は、通貨の額を表す文字列に変換されます。変換は、グローバル変数の CurrencyString、CurrencyFormat、NegCurrFormat、ThousandSeparator、DecimalSeparator、CurrencyDecimals か、TFormatSettings データ構造体の相当するもので、制御されます。書式文字列に精度指定子が含まれている場合、それは CurrencyDecimals グローバル変数や その TFormatSettings 相当によって上書きされます。 |
|
|
ポインタ。 引数はポインタ値でなければなりません。 値は、8 文字の文字列に変換され、ポインタの値を 16 進数で表します（x64 環境では、値は 16 文字の文字列に変換されます）。 |
|
|
文字列型 引数は、文字、文字列、または PChar 値でなければなりません。 文字列または文字が、書式指定子の代わりに挿入されます。 書式文字列に精度指定子がある場合は、その指定子で結果の文字列の最大長が指定されます。 引数がこの最大長より長い文字列であれば、その文字列は切り詰められます。 |
|
|
16 進数。 引数は整数値でなければなりません。 値は 16 進数の文字列に変換されます。 書式文字列に精度指定子が含まれている場合は、結果の文字列に少なくとも指定された桁数がなければならないことを示しています。値の桁数が指定より少ない場合は、結果の文字列の左側がゼロで埋められます。 |
変換文字は、小文字だけでなく大文字で指定される場合もあります。両者とも、同じ結果となります。
文字 % を表すには（つまり、書式指定子の開始ではなく、リテラルの % を表示するには）、%% を使用します。例：
Writeln(Format('%d%%', [100])); // displays '100%'
すべての浮動小数点形式について、小数点や桁区切り文字として使用される実際の文字は、グローバル変数の DecimalSeparator および ThousandSeparator、またはTFormatSettings の相当するものから取得されます。
インデックス、幅、精度の指定子は、10進数文字列（たとえば、"%10d"）を使用して直接指定することも、アスタリスク文字（たとえば、"%*.*f"）を使用して間接的に指定することも可能です。アスタリスクを使用する場合、引数リスト内の次の引数が、実際に使用される値となります。幅は整数値、精度は符号なし整数値である点に注意してください。たとえば、
Format ('%*.*f', [8, 2, 123.456]);
これは、次と同じ意味です。
Format ('%8.2f', [123.456]);
同様に C++ でも：
TVarRec args[3] = {8,2,123.456};
Format ("%*.*f", args, 2);
これは、次と同じ意味です。
TVarRec args[1] = {123.456};
Format ("%8.2f", args, 0);
幅指定子は、変換のフィールド幅の下限を設定します。 結果の文字列がフィールドの最小幅より短い場合、フィールド幅は空白によって引き伸ばされます。デフォルトでは、値の前に空白を追加することで結果を右揃えにしますが、書式指定子に左揃え指示（幅指定子の前の "-" エンダッシュ文字）が含まれている場合、結果は、値の後に空白を追加して左揃えとなります。
インデックス指定子は、現在の引数リスト インデックスを指定された値に設定します。引数リスト内の最初の引数のインデックスは 0 です。インデックス指定子を使用すると、同じ引数を何度も整形することができます。たとえば、"Format('%d %d %0:d %1:d', [10, 20])" は文字列 '10 20 10 20' を生成します。
可変フォーマット
Clang コンパイラが Format() の可変バージョンをサポートし、ARRAYOFCONST と可変構文が利用可能になりました。
クラシック コンパイラと Clang コンパイラ：
Format ("Hello int=%d float=%f, str=%s",
ARRAYOFCONST((10, 2.3L, String("str"))));
Clang コンパイラ：
Format ("Hello int=%d float=%f, str=%s",
10, 2.3L, String("str"));
Format により、パラメータへのインデックス付けが可能になった点に注目してください。これにより、パラメータにアクセスする整形文字列を、渡された順とは異なる順で使用したり、1 つのパラメータに複数回アクセスすることができます。
クラシック コンパイラと Clang コンパイラ：
Format ("%1:d %1:u %2:u", ARRAYOFCONST((myint, myuint)));
Clang コンパイラ：
Format ("%1:d %1:u %2:u", myint, myuint);