"string" --- 一般的な文字列操作
*******************************

**ソースコード:** Lib/string/__init__.py

======================================================================

参考:

  テキストシーケンス型 --- str

  文字列メソッド


文字列定数
==========

このモジュールで定義されている定数は以下の通りです:

string.ascii_letters

   後述の "ascii_lowercase" と "ascii_uppercase" を合わせたもの。この
   値はロケールに依存しません。

string.ascii_lowercase

   小文字 "'abcdefghijklmnopqrstuvwxyz'" 。この値はロケールに依存せず
   、固定です。

string.ascii_uppercase

   大文字 "'ABCDEFGHIJKLMNOPQRSTUVWXYZ'" 。この値はロケールに依存せず
   、固定です。

string.digits

   文字列 "'0123456789'" です。

string.hexdigits

   文字列 "'0123456789abcdefABCDEF'" です。

string.octdigits

   文字列 "'01234567'" です。

string.punctuation

   "C" ロケールにおいて、区切り文字 (punctuation characters) として扱
   われる ASCII 文字の文字列です: "!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~".

string.printable

   Python が表示可能とみなす ASCII 文字からなる文字列です。 "digits"、
   "ascii_letters"、"punctuation"、"whitespace" を組み合わせたものです
   。

   注釈:

     仕様上、"string.printable.isprintable()" は "False" を返します。
     特に、"string.printable" は POSIX の意味で表示可能な文字列ではあ
     りません (*LC_CTYPE* を参照)。

string.whitespace

   空白として扱われるすべての ASCII 文字を含む文字列です。 スペース、
   タブ、改行、復帰、改ページ、垂直タブが含まれます。


文字列の書式化のカスタマイズ
============================

組み込みの文字列クラスでは、**PEP 3101** で説明されている "format()"
メソッドを使って、複雑な変数の置換や値の書式化を行えます。 "string" モ
ジュールの "Formatter" クラスを使うと、組み込みの "format()" メソッド
と同じ実装を利用して、独自の文字列の書式化処理を作成、カスタマイズでき
ます。

class string.Formatter

   "Formatter" クラスは、以下のメソッドを持ちます:

   format(format_string, /, *args, **kwargs)

      主要な API メソッドです。書式文字列と、任意の位置引数およびキー
      ワード引数のセットを取ります。これは、"vformat()" を呼び出す単な
      るラッパーです。

      バージョン 3.7 で変更: 書式文字列は 位置専用 の引数となりました
      。

   vformat(format_string, args, kwargs)

      この関数はフォーマットの実際の仕事をします。この関数は、 "*args"
      および "**kwargs" シンタックスを使用して、辞書を個々の引数として
      unpack してから再度 pack するのではなく、引数としてあらかじめ用
      意した辞書を渡したい場合のために、独立した関数として公開されます
      。 "vformat()" は、書式文字列を文字データと置換フィールドに分解
      する仕事をします。それは、以下に記述する様々なメソッドを呼び出し
      ます。

   さらに、 "Formatter" ではサブクラスによって置き換えられることを意図
   した次のようないくつかのメソッドが定義されています。

   parse(format_string)

      format_stringを探査し、タプル、 (*literal_text*, *field_name*,
      *format_spec*, *conversion*) のイテラブルを返します。これは
      "vformat()" が文字列を文字としての文字データや置換フィールドに展
      開するために使用されます。

      タプルの各値は、概念的には文字列のリテラル部分と、それに続く 1
      つの置換フィールドを表します。 リテラル部分がない場合 (2 つの置
      換フィールドが連続する場合など)、*literal_text* は長さ 0 の文字
      列になります。 置換フィールドがない場合、*field_name*、
      *format_spec*、*conversion* の値は "None" になります。
      *field_name* の値は変更されず、番号のない位置フィールドへの自動
      的な番号付けは "vformat()" が行います。

   get_field(field_name, args, kwargs)

      指定された *field_name* を、書式化するオブジェクトに変換します。
      "parse()" が返す *field_name* の自動的な番号付けは、このメソッド
      が呼ばれる前に "vformat()" が行います。 タプル (obj, used_key)
      を返します。 デフォルトの実装は、"0[name]" や "label.title" など
      、**PEP 3101** で定義された形式の文字列を受け取ります。 *args*
      と *kwargs* は "vformat()" に渡されたものです。 戻り値の
      *used_key* は、"get_value()" の引数 *key* と同じ意味を持ちます。

   get_value(key, args, kwargs)

      指定したフィールドの値を取得します。 *key* 引数は整数または文字
      列です。 整数なら *args* 内の位置引数のインデックスを表し、文字
      列なら *kwargs* 内のキーワード引数の名前を表します。

      *args* 引数は、 "vformat()" への位置引数のリストに設定され、
      *kwargs* 引数は、キーワード引数の辞書に設定されます。

      複数の要素からなるフィールド名では、これらの関数は最初の要素につ
      いてだけ呼び出されます。 後続の要素は、通常の属性アクセスとイン
      デックス操作で処理されます。

      例えば、フィールド式 '0.name' では *key* 引数を 0 として
      "get_value()" を呼び出します。 "get_value()" が返った後、組み込
      み関数 "getattr()" を呼び出して "name" 属性を検索します。

      インデックスまたはキーワードが存在しないアイテムを参照した場合、
      "IndexError" または "KeyError" が送出されます。

   check_unused_args(used_args, args, kwargs)

      希望に応じて未使用の引数がないか確認する機能を実装します。この関
      数への引数は、書式指定文字列で実際に参照されるすべての引数のキー
      の set (位置引数の整数、名前付き引数の文字列) と、vformat に渡さ
      れる *args* と *kwargs* への参照です。使用されない引数の set は
      、これらのパラメータから計算されます。 "check_unused_args()" は
      、確認の結果が偽である場合に例外を送出するものとみなされます。

   format_field(value, format_spec)

      "format_field()" は組み込み関数 "format()" を呼び出すだけです。
      サブクラスでこのメソッドをオーバーライドできるように用意されてい
      ます。

   convert_field(value, conversion)

      ("get_field()" が返す) 値を ("parse()" メソッドが返すタプルの形
      式で) 与えられた変換タイプとして変換します。デフォルトバージョン
      は 's' (str), 'r' (repr), 'a' (ascii) 変換タイプを理解します。


書式文字列の構文
================

"str.format()" メソッドと "Formatter" クラスは、書式文字列に同じ構文を
使います (ただし "Formatter" のサブクラスでは独自の構文を定義できます)
。 この構文は フォーマット済み文字列リテラル や テンプレート文字列リテ
ラル の構文に関連しますが、機能はより限られており、特に補間で任意の式
を使うことはできません。

書式指定文字列は波括弧 "{}" に囲まれた "置換フィールド" を含みます。波
括弧に囲まれた部分以外は全て単純な文字として扱われ、変更を加えることな
く出力へコピーされます。波括弧を文字として扱う必要がある場合は、二重に
することでエスケープすることができます: "{{" および "}}" 。

置換フィールドの文法は以下です:

   replacement_field: "{" [field_name] ["!" conversion] [":" format_spec] "}"
   field_name:        arg_name ("." attribute_name | "[" element_index "]")*
   arg_name:          [identifier | digit+]
   attribute_name:    identifier
   element_index:     digit+ | index_string
   index_string:      <any source character except "]"> +
   conversion:        "r" | "s" | "a"
   format_spec:       format-spec:format_spec

もっと簡単にいうと、置換フィールドは *field_name* で始められます。これ
によって指定したオブジェクトの値が、置換フィールドの代わりに書式化され
出力に挿入されます。*field_name* の後に、感嘆符 "'!'" を挟んで
*conversion* フィールドを続けることができます。最後にコロン "':'" を挟
んで、 *format_spec* を書くことができます。これは、置換される値の非デ
フォルトの書式を指定します。

書式指定ミニ言語 節も参照して下さい。

*field_name* それ自身は、数かキーワードのいずれかである *arg_name* か
ら始まります。それが数である場合、位置引数を参照します。また、それがキ
ーワードである場合、指定されたキーワード引数を参照します。文字列に対し
て "str.isdecimal()" を呼び出した結果が真の場合、 *arg_name* は数とし
て扱われます。書式文字列中で数の arg_names が順に 0, 1, 2, ... である
場合、それらはすべて (いくつかではありません) 省略することができます。
そして数 0, 1, 2, ... は、自動的にその順で挿入されます。 *arg_name* は
引用符で区切られていないので、書式文字列内の任意の辞書キー (例えば文字
列 "'10'" や "':-]'" など) を指定することはできません。 *arg_name* の
後に任意の数のインデックス式または属性式を続けることができます。
"'.name'" 形式の式は "getattr()" を使用して指定された属性を選択します
。一方、 "'[index]'" 形式の式は "__getitem__()" を使用してインデックス
参照を行います。

バージョン 3.1 で変更: "str.format()" を使い、位置引数指定を省略するこ
とができます。 "'{} {}'.format(a, b)" は "'{0} {1}'.format(a, b)" と同
じになります。

バージョン 3.4 で変更: "Formatter" を使い、位置引数指定を省略すること
ができます。

簡単な書式指定文字列の例を挙げます:

   "First, thou shalt count to {0}"  # References first positional argument
   "Bring me a {}"                   # Implicitly references the first positional argument
   "From {} to {}"                   # Same as "From {0} to {1}"
   "My quest is {name}"              # References keyword argument 'name'
   "Weight in tons {0.weight}"       # 'weight' attribute of first positional arg
   "Units destroyed: {players[0]}"   # First element of keyword argument 'players'.

*conversion* フィールドは、書式化の前に型を強制変換します。 通常、値の
書式化はその値自身の "__format__()" メソッドが行います。 しかし場合に
よっては、その型が定義する書式化処理を使わず、文字列として書式化したい
ことがあります。 "__format__()" を呼び出す前に値を文字列に変換すると、
通常の書式化処理を回避できます。

現在 3つの変換フラグがサポートされています: 値に対して "str()" を呼ぶ
"'!s'" 、 "repr()" を呼ぶ "'!r'" 、 "ascii()" を呼ぶ "'!a'"。

いくつかの例です:

   "Harold's a clever {0!s}"        # Calls str() on the argument first
   "Bring out the holy {name!r}"    # Calls repr() on the argument first
   "More {!a}"                      # Calls ascii() on the argument first

*format_spec* フィールドは、フィールド幅、文字揃え、埋め文字、10 進数
の精度など、値の表示方法を指定します。 それぞれの値の型は、独自の「書
式指定ミニ言語」、つまり *format_spec* の解釈を定義できます。

ほとんどの組み込み型は、次のセクションに記載された共通の formatting
mini-language をサポートします。

*format_spec* フィールド内には入れ子になった置換フィールドを含めること
もできます。入れ子になった置換フィールドにはフィールド名、変換フラグ、
書式指定を含めることができますが、さらに入れ子の階層を含めることはでき
ません。 format_spec 中の置換フィールドは *format_spec* 文字列が解釈さ
れる前に置き換えられます。これにより、値の書式を動的に指定することがで
きます。

書式指定例 のいくつかの例も参照して下さい。


書式指定ミニ言語
----------------

「書式指定」は、書式文字列の置換フィールド内で個々の値の表示方法を定義
するために使います (書式文字列の構文、f-strings、t-strings を参照)。
組み込み関数 "format()" に直接渡すこともできます。 書式化できる各型は
、書式指定の解釈を独自に定義できます。

多くの組み込み型は、書式指定に関して以下のオプションを実装します。しか
しながら、いくつかの書式指定オプションは数値型でのみサポートされます。

一般的な取り決めとして、空の書式指定は、値に対して "str()" を呼び出し
たときと同じ結果を与えます。通常、空でない書式指定はその結果を変更しま
す。

一般的な書式指定子 (*standard format specifier*) の書式は以下です:

   format_spec:             [options][width_and_precision][type]
   options:                 [[fill]align][sign]["z"]["#"]["0"]
   fill:                    <any character>
   align:                   "<" | ">" | "=" | "^"
   sign:                    "+" | "-" | " "
   width_and_precision:     [width_with_grouping][precision_with_grouping]
   width_with_grouping:     [width][grouping]
   precision_with_grouping: "." [precision][grouping] | "." grouping
   width:                   digit+
   precision:               digit+
   grouping:                "," | "_"
   type:                    "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g"
                            | "G" | "n" | "o" | "s" | "x" | "X" | "%"

有効な *align* 値を指定する場合、その前に *fill* 文字を付けることがで
きます。 この文字には任意の文字を指定でき、省略された場合はデフォルト
の空白文字となります。 formatted string literal の中や "str.format()"
メソッドを使う場合はリテラルの波括弧 (""{"" と ""}"") を *fill* 文字と
して使えないことに注意してください。 ただし、波括弧を入れ子になった置
換フィールド内に挿入することはできます。 この制限は "format()" 関数に
は影響しません。

様々な align オプションの意味は以下のとおりです:

+-----------+------------------------------------------------------------+
| オプショ  | 意味                                                       |
| ン        |                                                            |
|===========|============================================================|
| "'<'"     | 利用可能なスペースにおいて、左詰めを強制します (ほとんどの |
|           | オブジェクト においてのデフォルト)。                       |
+-----------+------------------------------------------------------------+
| "'>'"     | 利用可能なスペース内で右詰めにします (数値のデフォルトです |
|           | )。                                                        |
+-----------+------------------------------------------------------------+
| "'='"     | 埋め文字を、符号があればその後、かつ数字の前に配置します。 |
|           | '+000000120' のような形式でフィールドを表示するために使い  |
|           | ます。 この配 置オプションは "complex" を除く数値型でのみ  |
|           | 有効です。 フィールド幅の直 前に '0' を指定すると、数値に  |
|           | はこの配置がデフォルトで使われます。                       |
+-----------+------------------------------------------------------------+
| "'^'"     | 利用可能なスペースにおいて、中央寄せを強制します。         |
+-----------+------------------------------------------------------------+

最小のフィールド幅が定義されない限り、フィールド幅はデータを表示するた
めに必要な幅と同じになることに注意して下さい。そのため、その場合には、
align オプションは意味を持ちません。

*sign* オプションは数値型に対してのみ有効であり、以下のうちのひとつと
なります:

+-----------+------------------------------------------------------------+
| オプショ  | 意味                                                       |
| ン        |                                                            |
|===========|============================================================|
| "'+'"     | 正の数にも負の数にも符号を付けます。                       |
+-----------+------------------------------------------------------------+
| "'-'"     | 負の数にだけ符号を付けます (デフォルトの動作です)。        |
+-----------+------------------------------------------------------------+
| 空白      | 正の数の先頭には空白を、負の数にはマイナス符号を付けます。 |
+-----------+------------------------------------------------------------+

"'z'" オプションは、書式で指定した精度に丸めた後、浮動小数点数の負のゼ
ロを正のゼロに変換します。 このオプションは浮動小数点数の表現型でのみ
有効です。

バージョン 3.11 で変更: "'z'" オプションが追加されました (**PEP 682**
も参照)。

"'#'" オプションは、変換に「別形式」を使用します。別形式は、異なる型に
対して違った風に定義されます。このオプションは、整数、浮動小数点数、複
素数でのみ有効です。整数に対して2進法、8進法、または16進法の出力が使用
される場合、このオプションは出力される値にそれぞれ "'0b'", "'0o'",
"'0x'", "'0X'" 接頭辞を加えます。浮動小数点数、複素数については、別形
式では、小数点文字の後に数字がなくても変換結果には常に小数点文字が含ま
れます。通常は、数字が続く場合にのみ小数点文字がこれらの変換結果に現わ
れます。さらに、"'g'" と "'G'" の変換については、最後の 0 は結果から取
り除かれません。

*width* は、接頭辞、区切り文字、そのほかの書式化のための文字も含めた、
フィールド全体の最小幅を定義する 10 進整数です。 指定しなければ、フィ
ールド幅は内容によって決まります。

配置を明示的に指定せずに *width* フィールドの前にゼロ ("'0'") を置くと
、"complex" を除く数値型では符号を考慮してゼロで埋めます。 これは
*fill* 文字を "'0'"、*alignment* の種類を "'='" にするのと同じです。

バージョン 3.10 で変更: *width* フィールドに "'0'" を前置することは、
文字列に対するデフォルトの整列に影響を与えなくなりました。

*precision* は、表現型 "'f'" または "'F'" の場合小数点以下、表現型
"'g'" または "'G'" の場合は小数点以上と以下が何桁で表示されるべきかを
示す10進整数です。文字列の表現型の場合は最大フィールド幅、言い換えると
フィールドの内容から何文字が使用されるかを示します。*precision* は整数
の表現型には使用できません。

*width* フィールドの後の *grouping* オプションは整数部の桁区切り文字を
、*precision* フィールドの後のものは小数部の桁区切り文字を指定します。
次のいずれかを指定できます:

+-----------+------------------------------------------------------------+
| オプショ  | 意味                                                       |
| ン        |                                                            |
|===========|============================================================|
| "','"     | 整数の表現型 "'d'" と、"'n'" を除く浮動小数点数の表現型で  |
|           | は、3 桁ごと にカンマを挿入します。 そのほかの表現型では、 |
|           | このオプションを使えませ ん。                              |
+-----------+------------------------------------------------------------+
| "'_'"     | 整数の表現型 "'d'" と、"'n'" を除く浮動小数点数の表現型で  |
|           | は、3 桁ごと にアンダースコアを挿入します。 整数の表現型   |
|           | "'b'"、"'o'"、"'x'"、"'X'" では、4 桁ごとにアンダースコア  |
|           | を挿入します。 そのほかの表現型では、こ のオプションを使え |
|           | ません。                                                   |
+-----------+------------------------------------------------------------+

ロケールに応じた区切り文字を使うには、代わりに "'n'" の 浮動小数点数の
表現型 または 整数の表現型 を使ってください。

バージョン 3.1 で変更: "','" オプションが追加されました (**PEP 378**
も参照)。

バージョン 3.6 で変更: "'_'" オプションが追加されました (**PEP 515**
も参照)。

バージョン 3.14 で変更: 小数部で *grouping* オプションを使えるようにな
りました。

最後に、*type* は、データがどのように表現されるかを決定します。

利用可能な文字列の表現型は以下です:

   +-----------+------------------------------------------------------------+
   | 型        | 意味                                                       |
   |===========|============================================================|
   | "'s'"     | 文字列表記です。 文字列のデフォルトの表現型であり、省略で  |
   |           | きます。                                                   |
   +-----------+------------------------------------------------------------+
   | None      | "'s'" と同じです。                                         |
   +-----------+------------------------------------------------------------+

利用可能な整数の表現型は以下です:

   +-----------+------------------------------------------------------------+
   | 型        | 意味                                                       |
   |===========|============================================================|
   | "'b'"     | 2進数。出力される数値は2を基数とします。                   |
   +-----------+------------------------------------------------------------+
   | "'c'"     | 文字。数値を対応する Unicode 文字に変換します。            |
   +-----------+------------------------------------------------------------+
   | "'d'"     | 10進数。出力される数値は10を基数とします。                 |
   +-----------+------------------------------------------------------------+
   | "'o'"     | 8進数。出力される数値は8を基数とします。                   |
   +-----------+------------------------------------------------------------+
   | "'x'"     | 16進数。出力される数値は16を基数とします。 10進で9を超える |
   |           | 数字には 小文字が使われます。                              |
   +-----------+------------------------------------------------------------+
   | "'X'"     | 16進数。出力される数値は16を基数とします。10進で9を超える  |
   |           | 数字には大 文字が使われます。"'#'" が指定された場合、接頭  |
   |           | 辞 "'0x'" も大文字 "'0X'" になります                       |
   +-----------+------------------------------------------------------------+
   | "'n'"     | 数値表記です。 現在のロケール設定に従って適切な桁区切り文  |
   |           | 字を挿入す る点を除き、"'d'" と同じです。 デフォルトのロケ |
   |           | ールはシステムのロケ ールではないことに注意してください。  |
   |           | 用途によっては、"'n'" を使う前 に "locale.setlocale()" で  |
   |           | "LC_NUMERIC" を設定するとよいでしょう。                    |
   +-----------+------------------------------------------------------------+
   | None      | "'d'" と同じです。                                         |
   +-----------+------------------------------------------------------------+

これらの表現型に加えて、整数は ("'n'" と "None" を除く) 以下の浮動小数
点数の表現型で書式指定できます。 そうすることで整数は書式変換される前
に "float()" を使って浮動小数点数に変換されます。

利用可能な "float" と "Decimal" の表現型は以下です:

   +-----------+------------------------------------------------------------+
   | 型        | 意味                                                       |
   |===========|============================================================|
   | "'e'"     | 科学的表記です。 精度 "p" を指定すると、係数と指数を文字   |
   |           | 'e' で区切 る科学的表記で数値を書式化します。 係数は小数点 |
   |           | の前に 1 桁、後に "p" 桁を持ち、有効桁数は計 "p + 1" 桁で  |
   |           | す。 精度を指定しなければ、 "float" では小数点以下 "6" 桁  |
   |           | を使い、"Decimal" では係数の全桁を表示 します。 "p=0" の場 |
   |           | 合、"#" オプションを使わない限り小数点を省略しま す。      |
   |           | "float" では指数は常に 2 桁以上になり、値がゼロなら指数も  |
   |           | ゼロになり ます。                                          |
   +-----------+------------------------------------------------------------+
   | "'E'"     | 指数表記です。大文字の 'E' を使うことを除いては、 "'e'" と |
   |           | 同じです 。                                                |
   +-----------+------------------------------------------------------------+
   | "'f'"     | 固定小数点表記です。 精度 "p" を指定すると、小数点以下がち |
   |           | ょうど "p" 桁の 10 進数として数値を書式化します。 精度を指 |
   |           | 定しなければ、 "float" では小数点以下 "6" 桁を使い、       |
   |           | "Decimal" では係数の全桁を表示 するのに十分な精度を使いま  |
   |           | す。 "p=0" の場合、"#" オプションを使わな い限り小数点を省 |
   |           | 略します。                                                 |
   +-----------+------------------------------------------------------------+
   | "'F'"     | 固定小数点数表記です。"nan" が "NAN" に、"inf" が "INF" に |
   |           | 変換され ることを除き "'f'" と同じです。                   |
   +-----------+------------------------------------------------------------+
   | "'g'"     | 汎用表記です。与えられた精度 "p >= 1" に対して、この表記で |
   |           | は数値を 有効桁数 "p" に丸めた上で、数値の大きさに応じて固 |
   |           | 定小数点表記または 科学的表記で表します。精度 "0" は精度   |
   |           | "1" と同じものと取り扱われま す。  正確なルールは次の通り  |
   |           | です: 書式 "'e'" 型および精度 "p-1" 桁で数値 をフォーマッ  |
   |           | トした結果、指数部が "exp" になったと仮定します。 この と  |
   |           | き "m <= exp < p" ならば、数値は書式 "'f'" 型および精度    |
   |           | "p-1-exp" 桁でフォーマットされます。 ただし "m" は浮動小数 |
   |           | 点数では -4 であり 、  "Decimals" に対しては -6 です。 そ  |
   |           | れ以外の場合、数値は書式 "'e'" 型および精度 "p-1" 桁でフォ |
   |           | ーマットされます。 どちらの場合も 、"'#'" オプションが使わ |
   |           | れていなければ、仮数部の有効でない末尾のゼ ロを取り除き、  |
   |           | 小数点以下に桁が残らなければ小数点も取り除きます。  精度が |
   |           | 指定されていない場合、"float" には有効桁数 "6" 桁を使用し  |
   |           | ます 。 "Decimal" では、元の値の係数の各桁から結果の係数を |
   |           | 構成します。 絶対値が "1e-6" より小さい値や、最下位桁が十  |
   |           | の位以上にある値には科 学的表記を使用し、それ以外には固定  |
   |           | 小数点表記を使用します。  正と負の無限大と 0 および NaN は |
   |           | 精度に関係なくそれぞれ "inf", "-inf", "0", "-0" および     |
   |           | "nan" となります。                                         |
   +-----------+------------------------------------------------------------+
   | "'G'"     | 汎用フォーマットです。数値が大きくなったとき、 "'E'" に切  |
   |           | り替わるこ とを除き、 "'g'" と同じです。無限大と NaN の表  |
   |           | 示も大文字になります 。                                    |
   +-----------+------------------------------------------------------------+
   | "'n'"     | 数値表記です。 現在のロケール設定に従って数値の整数部に適  |
   |           | 切な桁区切 り文字を挿入する点を除き、"'g'" と同じです。 デ |
   |           | フォルトのロケールは システムのロケールではないことに注意  |
   |           | してください。 用途によっては、 "'n'" を使う前に           |
   |           | "locale.setlocale()" で "LC_NUMERIC" を設定すると よいでし |
   |           | ょう。                                                     |
   +-----------+------------------------------------------------------------+
   | "'%'"     | パーセンテージです。数値は 100 倍され、固定小数点数フォー  |
   |           | マット ("'f'") でパーセント記号付きで表示されます。        |
   +-----------+------------------------------------------------------------+
   | None      | "float" では "'g'" とほぼ同じですが、固定小数点表記で書式  |
   |           | 化する場合 には常に小数点以下が少なくとも 1 桁あり、"exp   |
   |           | >= p - 1" のとき科学 的表記に切り替わります。 精度を指定し |
   |           | なければ、与えられた値を忠実に 表すのに必要な精度を使いま  |
   |           | す。  "Decimal" に対しては、現在の decimal コンテキストに  |
   |           | おける "context.capitals" の値に応じて、 "'g'" か "'G'" の |
   |           | どちらかと同じに なります。  全体として、他の書式修正指定  |
   |           | によって変更された "str()" の出力に一致 するような結果にな |
   |           | ります。                                                   |
   +-----------+------------------------------------------------------------+

The result should be correctly rounded to a given precision "p" of
digits after the decimal point.  The rounding mode for "float" matches
that of the "round()" builtin.  For "Decimal", the rounding mode of
the current context will be used.

"complex" で使える表現型は "float" と同じです ("'%'" は使えません)。
複素数の実部と虚部はそれぞれ、指定した表現型に従って浮動小数点数として
書式化します。 実部と虚部の間には必須の虚部の符号を置き、虚部の末尾に
"j" を付けます。 表現型を省略すると、結果は "str()" の出力に一致します
(実部がゼロでない複素数は丸括弧でも囲まれます) が、ほかの書式修正指定
によって変更されることがあります。


書式指定例
----------

この節では、 "str.format()" 構文の例を紹介し、さらに従来の "%"-書式と
比較します。

多くの場合、この構文は従来の "%" 書式化に似ていますが、"{}" を追加し、
"%" の代わりに ":" を使います。 例えば "'%03.2f'" は "'{:03.2f}'" に書
き換えられます。

以下の例で示すように、新構文はさらに新たに様々なオプションもサポートし
ています。

位置引数を使ったアクセス:

   >>> '{0}, {1}, {2}'.format('a', 'b', 'c')
   'a, b, c'
   >>> '{}, {}, {}'.format('a', 'b', 'c')  # 3.1+ only
   'a, b, c'
   >>> '{2}, {1}, {0}'.format('a', 'b', 'c')
   'c, b, a'
   >>> '{2}, {1}, {0}'.format(*'abc')      # unpacking argument sequence
   'c, b, a'
   >>> '{0}{1}{0}'.format('abra', 'cad')   # arguments' indices can be repeated
   'abracadabra'

名前を使ったアクセス:

   >>> 'Coordinates: {latitude}, {longitude}'.format(latitude='37.24N', longitude='-115.81W')
   'Coordinates: 37.24N, -115.81W'
   >>> coord = {'latitude': '37.24N', 'longitude': '-115.81W'}
   >>> 'Coordinates: {latitude}, {longitude}'.format(**coord)
   'Coordinates: 37.24N, -115.81W'

引数の属性へのアクセス:

   >>> c = 3-5j
   >>> ('The complex number {0} is formed from the real part {0.real} '
   ...  'and the imaginary part {0.imag}.').format(c)
   'The complex number (3-5j) is formed from the real part 3.0 and the imaginary part -5.0.'
   >>> class Point:
   ...     def __init__(self, x, y):
   ...         self.x, self.y = x, y
   ...     def __str__(self):
   ...         return 'Point({self.x}, {self.y})'.format(self=self)
   ...
   >>> str(Point(4, 2))
   'Point(4, 2)'

引数の要素へのアクセス:

   >>> coord = (3, 5)
   >>> 'X: {0[0]};  Y: {0[1]}'.format(coord)
   'X: 3;  Y: 5'

"%s" と "%r" の置き換え:

   >>> "repr() shows quotes: {!r}; str() doesn't: {!s}".format('test1', 'test2')
   "repr() shows quotes: 'test1'; str() doesn't: test2"

テキストの幅を指定した整列:

   >>> '{:<30}'.format('left aligned')
   'left aligned                  '
   >>> '{:>30}'.format('right aligned')
   '                 right aligned'
   >>> '{:^30}'.format('centered')
   '           centered           '
   >>> '{:*^30}'.format('centered')  # use '*' as a fill char
   '***********centered***********'

"%+f" と "%-f", "% f" の置換、そして符号の指定:

   >>> '{:+f}; {:+f}'.format(3.14, -3.14)  # show it always
   '+3.140000; -3.140000'
   >>> '{: f}; {: f}'.format(3.14, -3.14)  # show a space for positive numbers
   ' 3.140000; -3.140000'
   >>> '{:-f}; {:-f}'.format(3.14, -3.14)  # show only the minus -- same as '{:f}; {:f}'
   '3.140000; -3.140000'

"%x" と "%o" の置換、そして値に対する異なる底の変換:

   >>> # format also supports binary numbers
   >>> "int: {0:d};  hex: {0:x};  oct: {0:o};  bin: {0:b}".format(42)
   'int: 42;  hex: 2a;  oct: 52;  bin: 101010'
   >>> # with 0x, 0o, or 0b as prefix:
   >>> "int: {0:d};  hex: {0:#x};  oct: {0:#o};  bin: {0:#b}".format(42)
   'int: 42;  hex: 0x2a;  oct: 0o52;  bin: 0b101010'

カンマやアンダースコアを桁区切り文字として使う例です。

   >>> '{:,}'.format(1234567890)
   '1,234,567,890'
   >>> '{:_}'.format(1234567890)
   '1_234_567_890'
   >>> '{:_b}'.format(1234567890)
   '100_1001_1001_0110_0000_0010_1101_0010'
   >>> '{:_x}'.format(1234567890)
   '4996_02d2'
   >>> '{:_}'.format(123456789.123456789)
   '123_456_789.12345679'
   >>> '{:.,}'.format(123456789.123456789)
   '123456789.123,456,79'
   >>> '{:,._}'.format(123456789.123456789)
   '123,456,789.123_456_79'

パーセントを表示する:

   >>> points = 19
   >>> total = 22
   >>> 'Correct answers: {:.2%}'.format(points/total)
   'Correct answers: 86.36%'

型特有の書式指定を使う:

   >>> import datetime as dt
   >>> d = dt.datetime(2010, 7, 4, 12, 15, 58)
   >>> '{:%Y-%m-%d %H:%M:%S}'.format(d)
   '2010-07-04 12:15:58'

引数をネストする、さらに複雑な例:

   >>> for align, text in zip('<^>', ['left', 'center', 'right']):
   ...     '{0:{fill}{align}16}'.format(text, fill=align, align=align)
   ...
   'left<<<<<<<<<<<<'
   '^^^^^center^^^^^'
   '>>>>>>>>>>>right'
   >>>
   >>> octets = [192, 168, 0, 1]
   >>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets)
   'C0A80001'
   >>> int(_, 16)
   3232235521
   >>>
   >>> width = 5
   >>> for num in range(5,12):
   ...     for base in 'dXob':
   ...         print('{0:{width}{base}}'.format(num, base=base, width=width), end=' ')
   ...     print()
   ...
       5     5     5   101
       6     6     6   110
       7     7     7   111
       8     8    10  1000
       9     9    11  1001
      10     A    12  1010
      11     B    13  1011


テンプレート文字列 ($ 文字列)
=============================

注釈:

  ここで説明する機能は、Python 2.4 で導入された正規表現に基づく簡単な
  テンプレート処理です。 "str.format()"、フォーマット済み文字列リテラ
  ル、テンプレート文字列リテラル より前からあります。Python 3.14 で導
  入されたテンプレート文字列リテラル (t 文字列) とは無関係です。 t 文
  字列は、"string.templatelib" モジュールの
  "string.templatelib.Template" オブジェクトに評価されます。

テンプレート文字列では **PEP 292** で解説されている単純な文字列置換が
できます。 テンプレート文字列の主な使い道は国際化 (i18n) です。という
のは、その国際化の文脈において、より簡潔な文法と機能を持つテンプレート
文字列を使うと、 Python にある他の組み込みの文字列フォーマット機能より
も翻訳がしやすいからです。 テンプレート文字列の上に構築された国際化の
ためのライプラリの例として、 flufl.i18n を調べてみてください。

テンプレート文字列は "$" に基づいた置換をサポートしていて、次の規則が
使われています:

* "$$" はエスケープ文字です; "$" 一つに置換されます。

* "$identifier" は、マッピングのキー ""identifier"" に対応する置換プレ
  ースホルダーを指定します。 デフォルトでは ""identifier"" に使えるの
  は、大文字・小文字を区別しない ASCII の英数字とアンダースコアからな
  る文字列で、先頭はアンダースコアまたは ASCII の英字でなければなりま
  せん。 "$" の後で最初に現れる識別子に使えない文字が、プレースホルダ
  ー指定の終わりを示します。

* "${identifier}" は "$identifier" と同じです。プレースホルダ名の後ろ
  に識別子として使える文字列が続いていて、それをプレースホルダ名の一部
  として扱いたくない場合、例えば ""${noun}ification"" のような場合に必
  要な書き方です。

上記以外の書き方で文字列中に "$" を使うと "ValueError" を送出します。

"string" モジュールは、これらの規則を実装する "Template" クラスを提供
します。 "Template" のメソッドは次のとおりです:

class string.Template(template)

   コンストラクタはテンプレート文字列になる引数を一つだけ取ります。

   substitute(mapping={}, /, **kwds)

      テンプレート置換を行い、新たな文字列を生成して返します。
      *mapping* はテンプレート中のプレースホルダに対応するキーを持つよ
      うな任意の辞書類似オブジェクトです。辞書を指定する代わりに、キー
      ワード引数も指定でき、その場合にはキーワードをプレースホルダ名に
      対応させます。*mapping* と *kwds* の両方が指定され、内容が重複し
      た場合には、*kwds* に指定したプレースホルダを優先します。

   safe_substitute(mapping={}, /, **kwds)

      "substitute()" と同じですが、プレースホルダに対応するものを
      *mapping* や *kwds* から見つけられなかった場合に、 "KeyError" 例
      外を送出する代わりにもとのプレースホルダがそのまま入ります。また
      、 "substitute()" とは違い、規則外の書き方で "$" を使った場合で
      も、 "ValueError" を送出せず単に "$" を返します。

      その他の例外も発生し得る一方で、このメソッドが「安全 (safe) 」と
      呼ばれているのは、置換操作は常に、例外を送出する代わりに利用可能
      な文字列を返そうとするからです。別の見方をすれば、
      "safe_substitute()" は区切り間違いによるぶら下がり (dangling
      delimiter) や波括弧の非対応、 Python の識別子として無効なプレー
      スホルダ名を含むような不正なテンプレートを何も警告せずに無視する
      ため、安全とはいえないのです。

   is_valid()

      テンプレートに、"substitute()" が "ValueError" を送出する原因と
      なる無効なプレースホルダーがある場合、"False" を返します。

      Added in version 3.11.

   get_identifiers()

      テンプレート内の有効な識別子のリストを、その識別子が最初に現れる
      順番で返します。不正な識別子は無視されます。

      Added in version 3.11.

   "Template" のインスタンスは、次のような public な属性を提供していま
   す:

   template

      コンストラクタの引数 *template* に渡されたオブジェクトです。通常
      、この値を変更すべきではありませんが、読み出し専用アクセスを強制
      しているわけではありません。

Templateの使い方の例を以下に示します:

   >>> from string import Template
   >>> s = Template('$who likes $what')
   >>> s.substitute(who='tim', what='kung pao')
   'tim likes kung pao'
   >>> d = dict(who='tim')
   >>> Template('Give $who $100').substitute(d)
   Traceback (most recent call last):
   ...
   ValueError: Invalid placeholder in string: line 1, col 11
   >>> Template('$who likes $what').substitute(d)
   Traceback (most recent call last):
   ...
   KeyError: 'what'
   >>> Template('$who likes $what').safe_substitute(d)
   'tim likes $what'

さらに進んだ使い方: "Template" のサブクラスを派生して、プレースホルダ
の書式、区切り文字、テンプレート文字列の解釈に使われている正規表現全体
をカスタマイズできます。こうした作業には、以下のクラス属性をオーバライ
ドします:

* *delimiter* -- プレースホルダーの開始を示すリテラル文字列です。 デフ
  ォルト値は "$" です。 実装は必要に応じてこの文字列に "re.escape()"
  を適用するので、正規表現として指定しては *なりません* 。 クラスの作
  成後に区切り文字を変更することはできません。 別の区切り文字を使うに
  は、サブクラスのクラス名前空間で設定する必要があります。

* *idpattern* -- これは波括弧なしのプレースホルダーを記述する正規表現
  です。デフォルト値は正規表現 "(?a:[_a-z][_a-z0-9]*)" です。
  *idpattern* が与えられており、かつ *braceidpattern* が "None" の場合
  、このパターンは波括弧付きのプレースホルダーにも適用されます。

  注釈:

    *flags* のデフォルトは "re.IGNORECASE" なので、 "[a-z]" というパタ
    ーンはいくつかの非 ASCII 文字に適合できます。 そのため、ここではロ
    ーカルの "a" フラグを使っています。

  バージョン 3.7 で変更: *braceidpattern* を使用すると、中括弧の内側と
  外側で使用する別々のパターンを定義できます。

* *braceidpattern* -- これは *idpattern* に似ていますが、波括弧付きプ
  レースホルダーのパターンを記述します。デフォルトは "None" で、
  *idpattern* が適用されます (すなわち、波括弧の内側と外側の両方に同じ
  パターンが使われます) 。 *braceidpattern* を使うと、波括弧付きと波括
  弧なしのプレースホルダーにそれぞれ異なるパターンを定義することができ
  ます。

  Added in version 3.7.

* *flags* -- 置換箇所を認識する正規表現のコンパイル時に適用するフラグ
  です。 デフォルト値は "re.IGNORECASE" です。 "re.VERBOSE" は常に追加
  されるため、独自の *idpattern* は verbose モードの正規表現の規則に従
  う必要があります。

  Added in version 3.2.

代わりに、クラス属性 *pattern* をオーバーライドして正規表現のパターン
全体を指定することもできます。 この場合の値は、4 つの名前付きキャプチ
ャグループを持つ正規表現のパターン文字列、またはコンパイル済みの正規表
現オブジェクトでなければなりません。 各キャプチャグループは、上記の規
則と無効なプレースホルダーの規則に対応します:

* *escaped* -- このグループはエスケープシーケンス、すなわちデフォルト
  パターンにおける "$$" に対応します。

* *named* -- このグループは波括弧でくくらないプレースホルダ名に対応し
  ます; キャプチャグループに区切り文字を含めてはなりません。

* *braced* -- このグループは波括弧で囲んだプレースホルダー名に対応しま
  す。 キャプチャグループには区切り文字も波括弧も含めてはなりません。

* *invalid* -- このグループはそのほかの区切り文字のパターン (通常は区
  切り文字一つ) に対応し、正規表現の末尾に出現しなければなりません。

このクラスのメソッドは、これらの名前付きグループに1つもマッチすること
なくパターンがテンプレートにマッチした場合、 "ValueError" を送出します
。


ヘルパー関数
============

string.capwords(s, sep=None)

   "str.split()" を使って引数を単語に分割し、 "str.capitalize()" を使
   ってそれぞれの単語の先頭の文字を大文字に変換し、 "str.join()" を使
   ってつなぎ合わせます。オプションの第2引数 *sep* が与えられないか
   "None" の場合、この置換処理は文字列中の連続する空白文字をスペース一
   つに置き換え、先頭と末尾の空白を削除します、それ以外の場合には
   *sep* は split と join に使われます。
