format (マクロ)
パッケージ： CURL.LANGUAGE.COMPILER

フォーマット文字列のコントロール下で、データを TextOutputStream または String にフォーマットします。

シグネチャ

{define-proc public {format out:#TextOutputStream = null, locale:#Locale = null, fmt:String, ...:any }:String }
out: データがフォーマットされる TextOutputStream。このパラメータが指定されていない (または null と指定されている) 場合、データは String にフォーマットされて返されます。
locale: 残余引数のフォーマッティングに使用する Locale。指定されていない場合は、{get-syntax-locale} が使用されます。
fmt: フォーマット文字列。このコントロール下でフォーマットが実行されなければなりません。
...: フォーマットされるデータ。

戻り値

out が指定されている場合は空の String、それ以外の場合はフォーマットされたデータを含む String。

説明

out が指定されている場合は、このマクロは残余引数 （...） をTextOutputStream out にフォーマットし、空の String を返します。

それ以外の場合は、このマクロは残余引数 （...） を新しい String にフォーマットし、その String を返します。

どちらの場合でも、フォーマット文字列 fmt がフォーマッティングをコントロールします。フォーマット文字列は標準の文字 （その文字自体にフォーマットされていることが必要） と、特殊なフォーマット指定子を含みます。各指定子は、パーセント記号 （%） で始まります。これにより、1 つ以上の残余引数 （...） が、特定のフォーマット指定子と実際の残余引数自体に基づいてフォーマットされます。

次に例を示します。

"The number Pi can be approximated to %f"

この例では、%f は、フォーマットする数値に対するフォーマット指定子です。フォーマット指定子で、Curl に対してアイテムをどのようにフォーマットするか指示します。アイテム自体は残余引数として指定します。

次に例を示します。

{format "The number Pi can be approximated to %f", 3.141592653589793238463}

{format "The absolute value of %d is %d", -3, {abs -3}}

フォーマットの指定子としてパーセント記号が使用されるため、fmt にリテラルのパーセント記号を含める場合は、パーセント記号の前にもう 1 つのパーセント記号を指定します。

次に例を示します。

{format "%s got 54%% of the vote", "Bill Clinton"}

指定可能なフォーマット指定子は、C プログラミング言語の printf で使用する指定子に似ています。

標準のフォーマット指定子の構文は次のようになります。

%[modifiers][width][.precision]key

説明：

modifiers は format の既定のオペレーションを変更します。



単一のフォーマット指定子内に複数の修飾子を指定でき、任意の順番でそれを表示できます。

width はオプションです。これは、フォーマットされた出力内の最少文字数を示します。width が指定されていない場合は、最少文字数は適用されません。width より多い文字数の値をフォーマットする場合、文字は切り詰められません。width より少ない文字数の文字列をフォーマットする場合、文字列はパディングされます。残余引数の 1 つが幅を決定する可変幅を使用することができます。可変幅を使用するには、width にアスタリスク文字 (*) を指定します。その後、フォーマットするアイテムの前の残余引数に幅を指定する int を配置します。

precision は、アイテムをフォーマットする精度を示します。precision は任意の意味を持つ次のフォーマット キーに対してのみ有効です。



precision の前にピリオドを含み、precision を指定しなかった場合は、値ゼロを取ります。可変精度を使用することは可能で、その場合は残余引数のどれかが幅を決定します。可変精度を使用するには、アスタリスク文字 （*） を precision に指定します。その後、フォーマットするアイテムの前で残余引数に、精度を指定する int を配置します。可変幅と可変精度の両方を使用する場合は、残余引数内で精度の前に幅を指定します。

key は、フォーマットするアイテムに関する情報を示します。key には次のいずれかを指定します。



既定では、フォーマット指定子と残余引数は、左から右の順番で処理されます。ただし、各フォーマット指定子について残余引数インデックスを指定できます。フォーマット指定子について残余引数インデックスを指定するには、フォーマット指定子 （パーセント記号 （%） を除く） を感嘆符 （!）で囲み、パーセント記号の直後に残余引数インデックスを配置します。

たとえば、次のフォーマット指定子があるとします。

%02d

これを 三番目の残余引数に適用する場合は、次のようにフォーマット指定子を変更します。

%3!02d!

順番が指定されている指定子と指定されていない指定子が同じフォーマットで混成している場合、文字列は許可されます。混成したフォーマットの文字列で、順番が指定されていない指定子は残余引数を順番に参照します。この場合、その前にある数値の指定子は関係ありません。

{format "%2!s! %s %s %1!s!", 1, 2} == "2 1 2 1"

しかし、混同してしまうので指定子を混同して使用することは推奨しません。

例

この例では、整数に対して実行可能ないくつかのフォーマッティング操作を示します。


例: 整数のフォーマット
{let i:int = 1234}
{let j:int = -1234}
{let k:int = 56}

{Table
    columns = 4,
    cell-border-width = 2pt,
    {text Signed Decimal Integer},
    {format "%d", i},
    {format "%d", j},
    {format "%d", k},

    {text ... with {monospace +} modifier (sign)},
    {format "%+d", i},
    {format "%+d", j},
    {format "%+d", k},

    {text ... with {italic width} set to 1},
    {format "%1d", i},
    {format "%1d", j},
    {format "%1d", k},

    {text ... with {italic width} set to 8},
    {format "%8d", i},
    {format "%8d", j},
    {format "%8d", k},

    {text ... and {monospace 0} modifier (leading zeros)},
    {format "%08d", i},
    {format "%08d", j},
    {format "%08d", k},

    {text Unsigned Decimal Integer},
    {format "%u", i},
    {text N/A},
    {format "%u", k},

    {text Unsigned Octal Integer},
    {format "%o", i},
    {text N/A},
    {format "%o", k},

    {text ... with {monospace #} modifier},
    {format "%#o", i},
    {text N/A},
    {format "%#o", k},

    {text Unsigned Hexadecimal Integer},
    {format "%x", i},
    {text N/A},
    {format "%x", k},

    {text ... with {monospace #} modifier},
    {format "%#x", i},
    {text N/A},
    {format "%#x", k},

    {text Unsigned Binary Integer},
    {format "%b", i},
    {text N/A},
    {format "%b", k},

    {text ... with {monospace #} modifier},
    {format "%#b", i},
    {text N/A},
    {format "%#b", k}
}

例

この例では、浮動小数点数に対して実行可能ないくつかのフォーマッティング操作を示します。


例: 浮動小数点数のフォーマット
{let i:double = 1357.6863}
{let j:double = 36.69}
{let k:double = -36.69}

{Table
    columns = 4,
    cell-border-width = 2pt,
    {text Standard Notation},
    {format "%f", i},
    {format "%f", j},
    {format "%f", k},

    {text ... with {monospace +} modifier (sign)},
    {format "%+f", i},
    {format "%+f", j},
    {format "%+f", k},

    {text ... with {italic width} set to 2},
    {format "%2f", i},
    {format "%2f", j},
    {format "%2f", k},

    {text ... with {italic width} set to 8},
    {format "%8f", i},
    {format "%8f", j},
    {format "%8f", k},

    {text ... with {italic precision} set to 2},
    {format "%.2f", i},
    {format "%.2f", j},
    {format "%.2f", k},

    {text ... and {monospace 0} modifier (leading zeros)},
    {format "%0.2f", i},
    {format "%0.2f", j},
    {format "%0.2f", k},

    {text ... with {italic precision} set to 8},
    {format "%.8f", i},
    {format "%.8f", j},
    {format "%.8f", k},

    {text Scientific Notation (e)},
    {format "%e", i},
    {format "%e", j},
    {format "%e", k},

    {text Scientific Notation (E)},
    {format "%E", i},
    {format "%E", j},
    {format "%E", k},

    {text Mixed Notation},
    {format "%g", i},
    {format "%g", j},
    {format "%g", k}
}

例

この例では、文字列に対して実行可能ないくつかのフォーマッティング操作を示します。


例: 文字列のフォーマット
{let s1:String = "Hello!"}
{let s2:String = "Hello World!"}
{let s3:String = "Hello World, here comes... Curl!"}

{Table columns=4, cell-border-width=2pt,
       {text String},
       {format "%s", s1},
       {format "%s", s2},
       {format "%s", s3},

       {text ... with {italic width} set to 4},
       {format "%4s", s1},
       {format "%4s", s2},
       {format "%4s", s3},

       {text ... with {italic width} set to 26},
       {format "%26s", s1},
       {format "%26s", s2},
       {format "%26s", s3},

       {text ... with {italic precision} set to 4},
       {format "%.4s", s1},
       {format "%.4s", s2},
       {format "%.4s", s3},

       {text ... with {italic precision} set to 26},
       {format "%.26s", s1},
       {format "%.26s", s2},
       {format "%.26s", s3}
}

例

この例では、可変 width と precision の使用方法を示します。


例: 幅と精度でフォーマット
|| Declare and initialize an int, a float, and a string
{let i:int = 12}
{let f:float = 56.789f}
{let s:String = "Hello World"}

|| Declare an initialize a variable that you can use for
|| the width and precision
{let v:int = 4}

|| Format and output the int, float, and string using a
|| variable width
{format "%0*d", v, i}
{br}{format "%*f", v, f}
{br}{format "%*s", v, s}

|| Change the value of the variable width and display
|| the int, float, and string
{set v = 8}
{format "%0*d", v, i}
{br}{format "%*f", v, f}
{br}{format "%*s", v, s}

|| Use variable precision
{format "%0.*d", v, i}
{br}{format "%.*f", v, f}
{br}{format "%.*s", v, s}

例

この例では、各フォーマット指定子について残余引数インデックスを指定する方法を示します。


例: フォーマット引数インデックスの指定
|| Output a string with two formatting characters:
||  - A string %s.
||  - A decimal number with a 2-digit width.
{format "The %s concerns how computers deal with the year %02d", "Y2K problem", 0}

|| Output the same string; this time specifying the
|| rest arguments.
{format "The %1!s! concerns how computers deal with the year %2!02d!", "Y2K problem", 0}

|| And finally, mix things up a bit.
{format "The %2!s! concerns how computers deal with the year %1!02d!", 0, "Y2K problem"}

注意事項

C/C++ プログラミング言語では、フォーマットするアイテムのサイズについて、printf フォーマット指定子も （Curl の指定子はこれから採用しています） size 指定 （h、l、L、または q） を持ちます。互換性の理由から、これらのコードも Curl のフォーマット指定子内で受け取り可能ですが、これらは完全に無視されます。

Curl は、C/C++ プログラミング言語で使用されている %n と %p フォーマット指定子はサポートしません。

また、Curl では、C/C++ プログラミング言語では不正使用とされている方法で %s が使用可能です。%s はたいてい、他のフォーマット指定子と意味的に同一であっても、一般的により高速のコードであり、特にフォーマット修飾子を使用しない場合にそれが顕著であることに注意してください。

format 式の出力には、フォーマット文字列自体またはフォーマットで生成されるすべての空白が含まれますが、format 式の出力を TextFlowBox 内に表示する場合は（アプレットなど）、空白は削除されます。