フォーマット(formatting)とは、定数文字列内のさまざまな場所を計算された値で置き換えることにより、文字列を構築することを意味します。この定数文字列は他の値がどのようにプリントされるか、およびどこに表示するかを制御します。これはフォーマット文字列(format string)と呼ばれます。
表示されるメッセージを計算するためにフォーマットが便利なことがしばしばあります。実際に関数messageとerrorは、ここで説明する機能と同じフォーマットを提供します。これらの関数とformat-messageの違いはフォーマットされた結果を使用する方法だけです。
この関数はstringのすべてのフォーマット仕様を、対応するobjectsを復号化したものと置換したものと等しい文字列をリターンする。引数objectsはフォーマットされる計算値。
(もしあれば)string内のフォーマット仕様以外の文字はテキストプロパティを含めて出力に直接コピーされる。フォーマット仕様のすべてのテキストプロパティは引数objectsを表現する生成された文字列にコピーされる。
出力される文字列は新規に割り当てられる必要はない。たとえばxが文字列"foo"なら(eq x (format
x))と(eq x (format "%s" x))はいずれもtとなるだろう。
この関数はformatと同様に機能するが、string内のすべてのグレイブアクセント(`)とアポストロフィー(')をtext-quoting-styleの各値に応じて変換する点が異なる。
フォーマット内のグレイブアクセントとアポストロフィーはマッチするcurved quotesに変換される("Missing
`%s'"は"Missing ‘foo’"という結果になる)この変換の影響と回避についてはテキストのクォートスタイルを参照のこと。
フォーマット仕様(format
specification)は‘%’で始まる文字シーケンスです。したがってstring内に‘%d’があるとformatはそれを、フォーマットされる値の1つ(引数objectsのうちの1つ)にたいするプリント表現で置き換えます。たとえば:
(format "The value of fill-column is %d." fill-column)
⇒ "The value of fill-column is 72."
formatは文字‘%’をフォーマット仕様と解釈するので、決して最初の引数に不定な文字列(arbitrary
string)を渡すべきではありません。これは特に何らかのLispコードが生成した文字列の場合に当てはまります。その文字列が決して文字‘%’を含まないと確信できないならば、以下で説明するように最初の引数に"%s"を渡して、その不定な文字列を2番目の引数として渡します:
(format "%s" arbitrary-string)
ある種のフォーマット仕様は特定の型の値を要求します。その要求に適合しない値を与えた場合にはエラーがシグナルされます。
以下は有効なフォーマット仕様のテーブルです:
フォーマット仕様を、クォートなしのオブジェクトのプリント表現で置き換える(つまりprin1ではなくprincを使用して置き換える。出力関数を参照されたい)。したがって文字列は‘"’文字なしの文字列内容だけが表示され、シンボルは‘\’文字なしで表される。
オブジェクトが文字列なら文字列のプロパティは出力にコピーされる。‘%s’のテキストプロパティ自身もコピーされるが、オブジェクトのテキストプロパティが優先される。
フォーマット仕様を、クォートありのオブジェクトのプリント表現で置き換える(つまりprin1を使用して変換する。出力関数を参照されたい)。したがって文字列は‘"’文字で囲まれ、必要となる特別文字の前に‘\’文字が表示される。
フォーマット仕様を整数の8進表現に置き換える。負の整数はプラットフォーム依存の方法でフォーマットされる。オブジェクトは浮動小数点数(小数部分を切り捨てて整数にフォーマット)でもよい。
フォーマット仕様を10進表現の符号つき整数で置き換える。オブジェクトは浮動小数点数(小数部分を切り捨てて整数にフォーマット)でもよい。
フォーマット仕様を16進表現の整数で置き換える。負の整数はプラットフォーム依存の方法でフォーマットされる。‘%x’なら小文字、‘%X’なら大文字が使用される。オブジェクトは小数部分を切り捨てて整数にフォーマットされた浮動小数点数でもよい。
フォーマット仕様を与えられた値の文字で置き換える。
フォーマット仕様を浮動小数点数の指数表現で置き換える。
フォーマット仕様を浮動小数点数にたいする10進小数表記で置き換える。
指数表記か小数点表記のいずれかを使用してフォーマット仕様を浮動小数点数にたいする表記に置き換える。指数が−4未満または精度(デフォルトは6)以上なら指数表記を使用する。デフォルトでは結果の小数部の末尾の0は削除されて、小数点が現れるのは後に数字が続く場合のみ。
フォーマット仕様を1つの‘%’で置き換える。このフォーマット仕様は唯一のフォームが素の‘%%’であり値を使用しないという点で特殊。たとえば(format
"%% %d" 30)は"% 30"をリターンする。
他のフォーマット文字は‘Invalid format operation’エラーとなります。
以下は典型的なtext-quoting-styleのセッティングを想定した場合の例です:
(format "The octal value of %d is %o,
and the hex value is %x." 18 18 18)
⇒ "The octal value of 18 is 22,
and the hex value is 12."
(format-message
"The name of this buffer is ‘%s’." (buffer-name))
⇒ "The name of this buffer is ‘strings-ja.texi’."
(format-message
"The buffer object prints as `%s'." (current-buffer))
⇒ "The buffer object prints as ‘strings-ja.texi’."
フォーマット仕様はデフォルトではobjectsから連続して値を引き当てます。つまりstring内の1番目のフォーマット仕様は1番目の値、2番目のフォーマット仕様は2番目の値、...を使用します。余分なフォーマット仕様(対応する値がない場合)にはエラーとなります。フォーマットされる値が余分にある場合には無視されます。
フォーマット仕様はフィールド番号(field number)をもつことができます。これは最初の‘%’の直後に10進数字、その後にドル記号‘$’が続きます。これにより次の引数ではなく与えられた番号の引数をフォーマット仕様に変換させることができます。フィールド番号は1から始まります。フォーマットのフォーマット仕様が番号を含むことも含まないことも可能ですが、両方を含むことはできません。ただし例外は‘%%’であり、これは番号付きのフォーマット仕様と混交できます。
(format "%2$s, %3$s, %%, %1$s" "x" "y" "z")
⇒ "y, z, %, x"
‘%’とすべてのフィールド番号の後にフラグ文字(flag characters)を配置できます。
フラグ‘+’は非負の数の前にプラス符号を挿入するので、数には常に符号がつきます。フラグとしてスペースを指定すると、非負の数の前に1つのスペースが挿入されます(それ以外は非負の数は最初の数字から開始される)。これらのフラグは非負の数と負数にたいして確実に同じ列数を使用させるために有用です。これらは‘%d’、‘%e’、‘%f’、‘%g’以外では無視され、両方が指定された場合は‘+’が優先されます。
フラグ‘#’は代替形式(alternate form)を指定します。これは使用するフォーマットに依存します。‘%o’にたいしては結果を‘0’で開始させます。‘%x’と‘%X’にたいしては非0の結果のプレフィクスは‘0x’または‘0X’になります。‘%e’、‘%f’にたいしての‘#’フラグは、小数部が0のときにも小数点が含まれることを意味します。‘%g’にたいしては常に小数点が含まれるとともに、それ以外なら削除される小数点の後の末尾のすべての0も強制的に残されます。
フラグ‘0’はスペースの代わりに文字‘0’でパディングします。このフラグは‘%s’、‘%S’、‘%c’のような非数値のフォーマット仕様文字では無視されます。これらのフォーマット仕様文字で‘0’フラグを指定できますが、それでもスペースでパディングされます。
フラグ‘-’はフィールド幅指定子により挿入されるすべてのパディングに作用して、もしパディングが指定された場合には左側ではなく右側にパディングされます。‘-’と‘0’の両方が指定されると‘0’フラグは無視されます。
(format "%06d is padded on the left with zeros" 123)
⇒ "000123 is padded on the left with zeros"
(format "'%-6d' is padded on the right" 123)
⇒ "'123 ' is padded on the right"
(format "The word '%-7s' actually has %d letters in it."
"foo" (length "foo"))
⇒ "The word 'foo ' actually has 3 letters in it."
フォーマット仕様はフィールド幅(width)をもつことができます。これはすべてのフィールド番号とフラグの後にある10進の数字です。オブジェクトのプリント表現がこのフィールド幅より少ない文字を含む場合には、formatはパディングによりフィールド幅に拡張します。フォーマット仕様‘%%’ではフィールド幅の指定は無視されます。フィールド幅指定子により行なわれるパディングは、通常は左側に挿入されるスペースで構成されます:
(format "%5d is padded on the left with spaces" 123)
⇒ " 123 is padded on the left with spaces"
フィールド幅が小さすぎる場合でもformatはオブジェクトのプリント表現を切り詰めません。したがって情報を失う危険を犯すことなく、フィールドの最小幅を指定することができます。以下の2つの例では‘%7s’は最小幅に7を指定します。1番目の例では‘%7s’に挿入される文字列は3文字だけなので、4つのブランクスペースによりパディングされます。2番目の例では文字列"specification"は13文字ですが切り詰めはされません。
(format "The word '%7s' has %d letters in it."
"foo" (length "foo"))
⇒ "The word ' foo' has 3 letters in it."
(format "The word '%7s' has %d letters in it."
"specification" (length "specification"))
⇒ "The word 'specification' has 13 letters in it."
すべてのフォーマット仕様文字にはフィールド番号、フラグ、フィールド幅の後にオプションで精度(precision)を指定できます。精度は小数点‘.’と、その後に桁文字列(digit-string)を指定します。浮動小数点数のフォーマット仕様(‘%e’と‘%f’)では、精度は表示する小数点以下の桁数を指定します。0なら小数点も省略されます。%gの精度が0か未指定なら1として扱われます。‘%s’と‘%S’では精度として与えられた幅に文字列が切り詰められるので、‘%.3s’ではobjectの表現の最初の3文字だけが表示されます。その他の仕様文字では、printfファミリーのローカルライブラリーが生成する精度の効果が表れます。
‘%s’と‘%S’にたいしては、文字列を精度で指定された幅に切り詰めます。したがって‘%.3s’では、objectにたいするプリント表現の最初の3文字だけが表示されます。他のフォーマット仕様文字にたいしては、精度の効果はローカルライブラリーのprintf関数ファミリーが生成する効果となります。
フォーマット済みの値のコピーを取得するために後でreadを使用する予定なら、readが値を再構築する仕様を使用してください。この逆手順で数値をフォーマットするには‘%s’と‘%S’、整数だけなら‘%d’、非負の整数なら‘#x%x’と‘#o%o’も使用できます。その他のフォーマットでは問題があるかもしれません。たとえば‘%d’と‘%g’はNaNを誤って処理したり精度や型を失うかもしれず、‘#x%x’と‘#o%o’は負の整数を誤って処理するかもしれません。入力関数を参照してください。
このセクションでは仕様文字の固定セットを受け取る関数を説明します。次のセクションでは‘%a’や‘%z’のようなカスタム仕様文字を受け取ることができる関数format-specを説明します。