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

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

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

"string" モジュールには便利な定数やクラスが数多く入っています。また、
現在は文字列のメソッドとして利用できる、すでに撤廃された古い関数も入っ
ています。さらに、 Python の組み込み文字列クラスは シーケンス型 ---
str, unicode, list, tuple, bytearray, buffer, xrange 節に記載のシーケ
ンス型のメソッドと、 文字列メソッド 節に記載の文字列メソッドもサポート
します。出力の書式指定には、テンプレート文字列、または、 文字列フォー
マット操作 に記載の "%" 演算子を使用して下さい。正規表現に関する文字列
操作の関数は "re" を参照してください。


7.1.1. 文字列定数
=================

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

string.ascii_letters

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

string.ascii_lowercase

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

string.ascii_uppercase

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

string.digits

   文字列 "'0123456789'" です。

string.hexdigits

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

string.letters

   後述の "lowercase" と "uppercase" を合わせた文字列です。具体的な値
   はロケールに依存しており、 "locale.setlocale()" が呼ばれたときに更
   新されます。

string.lowercase

   小文字として扱われる文字全てを含む文字列です。ほとんどのシステムで
   は文字列 "'abcdefghijklmnopqrstuvwxyz'" です。具体的な値はロケール
   に依存しており、 "locale.setlocale()" が呼ばれたときに更新されます
   。

string.octdigits

   文字列 "'01234567'" です。

string.punctuation

   "C" ロケールにおいて、句読点として扱われる ASCII 文字の文字列です。

string.printable

   印刷可能な文字で構成される文字列です。 "digits", "letters",
   "punctuation" および "whitespace" を組み合わせたものです。

string.uppercase

   大文字として扱われる文字全てを含む文字列です。ほとんどのシステムで
   は "'ABCDEFGHIJKLMNOPQRSTUVWXYZ'" です。具体的な値はロケールに依存
   しており、 "locale.setlocale()" が呼ばれたときに更新されます。

string.whitespace

   空白 (whitespace) として扱われる文字全てを含む文字列です。ほとんど
   のシステムでは、これはスペース (space)、タブ (tab)、改行 (linefeed)
   、復帰 (return)、改頁 (formfeed)、垂直タブ (vertical tab) です。


7.1.2. カスタムの文字列書式化
=============================

バージョン 2.6 で追加.

組み込みの str 、および、 unicode クラスは、 **PEP 3101** に記載される
"str.format()" メソッドによる、複雑な変数置換と値の書式指定を提供しま
す。 "string" モジュールの "Formatter" クラスは組み込みの "format()"
メソッドと同じ実装で、文字列の書式指定の作成とカスタマイズを可能にしま
す。

class string.Formatter

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

   format(format_string, *args, **kwargs)

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

   vformat(format_string, args, kwargs)

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

   付け加えると、 "Formatter" はサブクラスで置き換えるためのいくつかの
   メソッドを定義します:

   parse(format_string)

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

      タプルの値は、概念的に文字としての文字データと、それに続く単一の
      置換フィールドを表現します。文字としての文字データが無い場合は (
      ふたつの置換フィールドが連続した場合などに起き得ます) 、
      *literal_text* は長さが 0 の文字列となります。置換フィールドが無
      い場合は、 *field_name*, *format_spec* および *conversion* が
      "None" となります。

   get_field(field_name, args, kwargs)

      引数として与えた "parse()" (上記参照) により返される
      *field_name* を書式指定対象オブジェクトに変換します。返り値はタ
      プル、 (obj, used_key) です。デフォルトでは **PEP 3101** に規定
      される "0[name]" や "label.title" のような形式の文字列を引数とし
      てとります。 *args* と *kwargs* は "vformat()" に渡されます。返
      り値 *used_key* は、 "get_value()" の *key* 引数と同じ意味を持ち
      ます。

   get_value(key, args, kwargs)

      与えられたフィールドの値を取り出します。 *key* 引数は整数でも文
      字列でも構いません。整数の場合は、ポジション引数 *args* のインデ
      ックス番号を示します。文字列の場合は、名前付きの引数 *kwargs* を
      意味します。

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

      複合したフィールド名に対しては、これらの関数はフィールド名の最初
      の要素に対してのみ呼び出されます ; あとに続く要素は通常の属性、
      および、インデックス処理へと渡されます。

      つまり、例えば、フィールドが '0.name' と表現されるとき、
      "get_value()" は、 *key* 引数が 0 として呼び出されます。属性
      "name" は、組み込みの "getattr()" 関数が呼び出され、
      "get_value()" が返されたのちに検索されます。

      もし、インデックス、もしくは、キーワードが存在しないアイテムを参
      照したら、 "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) 変換タイプを理解します。


7.1.3. 書式指定文字列の文法
===========================

"str.format()" メソッドと、 "Formatter" クラスは、文字列の書式指定に同
じ文法を共有します (しかしながら、 "Formatter" サブクラスの場合、それ
自身の書式指定文法を定義することが可能です) 。

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

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

      replacement_field ::= "{" [field_name] ["!" conversion] [":" format_spec] "}"
      field_name        ::= arg_name ("." attribute_name | "[" element_index "]")*
      arg_name          ::= [identifier | integer]
      attribute_name    ::= identifier
      element_index     ::= integer | index_string
      index_string      ::= <any source character except "]"> +
      conversion        ::= "r" | "s"
      format_spec       ::= <described in the next section>

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

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

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

バージョン 2.7 で変更: The positional argument specifiers can be
omitted for "str.format()" and "unicode.format()", so "'{} {}'" is
equivalent to "'{0} {1}'", "u'{} {}'" is equivalent to "u'{0} {1}'".

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

   "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__()" の呼び
出し前に値を文字列に変換すると、通常の書式変換の処理は飛ばされます。

現時点では、二種類の変換フラグがサポートされています: 値に対して
"str()" を呼び出す "'!s'" と、 "repr()" を呼び出す "'!r'" です。

いくつかの例です:

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

*format_spec* フィールドは、フィールド幅、文字揃え、埋め方、精度などの
、値を表現する仕様を含みます。それぞれの値の型は、 "formatting mini-
language" 、または、 *format_spec* の実装で定義されます。

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

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

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


7.1.3.1. 書式指定ミニ言語仕様
-----------------------------

書式指定 ("Format specifications") は書式指定文字列の個々の値を表現す
る方法を指定するための、置換フィールドで使用されます (書式指定文字列の
文法 を参照下さい) 。それらは、組み込み関数の "format()" 関数に直接渡
されます。それぞれの書式指定可能な型について、書式指定がどのように解釈
されるかが規定されます。

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

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

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

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

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

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

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

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

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

   +-----------+------------------------------------------------------------+
   | オプショ  | 意味                                                       |
   | ン        |                                                            |
   +===========+============================================================+
   | "'+'"     | 符号の使用を、正数、負数の両方に対して指定します。         |
   +-----------+------------------------------------------------------------+
   | "'-'"     | 符号の使用を、負数に対してのみ指定します (デフォルトの挙動 |
   |           | です)。                                                    |
   +-----------+------------------------------------------------------------+
   | 空白      | 空白を正数の前に付け、負号を負数の前に使用することを指定し |
   |           | ます。                                                     |
   +-----------+------------------------------------------------------------+

"'#'" オプションは、整数、かつ、2進数、8進数、16進数の出力に対してのみ
有効です。指定されれば、出力は、 "'0b'", "'0o'", もしくは "'0x'", のプ
リフィックスが付与されます。

"','" オプションは、千の位のセパレータにカンマを使うことを合図します。
ロケール依存のセパレータには、代わりに "'n'" の整数表現形式を使ってく
ださい。

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

*width* は10進数の整数で、最小のフィールド幅を規程します。もし指定され
なければ、フィールド幅は内容により規程されます。

alignment が明示的に与えられない場合、 *width* フィールドにゼロ
("'0'") 文字を前置することは、数値型のための符号を意識した 0 パディン
グを可能にします。これは *fill* 文字に "'0'" を指定して、 *alignment*
タイプに "'='" を指定したことと等価です。

*precision* は10進数で、 "'f'" および "'F'" 、あるいは、 "'g'" および
"'G'" で指定される浮動小数点数の、小数点以下に続く桁数を指定します。非
数型に対しては、最大フィールド幅を規程します。言い換えると、フィールド
の内容から、何文字使用するかを規程します。 *precision* は整数型に対し
ては、許されません。

最後に、 *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を越える |
   |           | 数字には 大文字が使われます。                              |
   +-----------+------------------------------------------------------------+
   | "'n'"     | 数値。現在のロケールに従い、区切り文字を挿入することを除け |
   |           | ば、 "'d'" と同じです。                                    |
   +-----------+------------------------------------------------------------+
   | None      | "'d'" と同じです。                                         |
   +-----------+------------------------------------------------------------+

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

利用可能な浮動小数点数と10進数の表現型は以下です:

   +-----------+------------------------------------------------------------+
   | 型        | 意味                                                       |
   +===========+============================================================+
   | "'e'"     | 指数表記です。指数を示す 'e' を使って数値を表示します。デ  |
   |           | フォルトの 精度は "6" です。                               |
   +-----------+------------------------------------------------------------+
   | "'E'"     | 指数表記です。大文字の 'E' を使うことを除いては、 "'e'" と |
   |           | 同じです 。                                                |
   +-----------+------------------------------------------------------------+
   | "'f'"     | 固定小数点数表記です。数値を固定小数点数として表示します。 |
   |           | デフォル トの精度は "6" です。                             |
   +-----------+------------------------------------------------------------+
   | "'F'"     | Fixed point notation. Same as "'f'".                       |
   +-----------+------------------------------------------------------------+
   | "'g'"     | 汎用フォーマットです。精度を "p >= 1" の数値で与えた場合、 |
   |           | 数値を有 効桁 "p" で丸め、桁に応じて固定小数点か指数表記で |
   |           | 表示します。  精度のルールは以下のように決まっています: 書 |
   |           | 式指定の結果が "'e'" 型 で "p-1" の精度の場合、指数は      |
   |           | "exp" になると仮定します。そうすると 、 "-4 <= exp < p" の |
   |           | とき数値は表現型 "'f'" で精度 "p-1-exp" に書式 変換されま  |
   |           | す。それ以外の場合、数値は "'e'" 型で精度 "p-1" に書式指   |
   |           | 定されます。この両方の場合で重要でない、連続した 0 は取り  |
   |           | 除かれます , そして残った桁が無い場合小数点は取り除かれま  |
   |           | す。  正と負の無限大と 0 および NaN は精度に関係なくそれぞ |
   |           | れ "inf", "-inf", "0", "-0" および "nan" となります。  "0" |
   |           | の精度は "1" の精度と同等に扱われます。デフォルトの精度は  |
   |           | "6" です。                                                 |
   +-----------+------------------------------------------------------------+
   | "'G'"     | 汎用フォーマットです。数値が大きくなったとき、 "'E'" に切  |
   |           | り替わるこ とを除き、 "'g'" と同じです。無限大と NaN の表  |
   |           | 示も大文字になります 。                                    |
   +-----------+------------------------------------------------------------+
   | "'n'"     | 数値です。現在のロケールに合わせて、数値分割文字が挿入され |
   |           | ることを 除き、 "'g'" と同じです。                         |
   +-----------+------------------------------------------------------------+
   | "'%'"     | パーセンテージです。数値は 100 倍され、固定小数点数フォー  |
   |           | マット ("'f'") でパーセント記号付きで表示されます。        |
   +-----------+------------------------------------------------------------+
   | None      | "'g'" と同じです。                                         |
   +-----------+------------------------------------------------------------+


7.1.3.2. 書式指定例
-------------------

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

多くの場合、"{}" を加え "%" の代わりに ":" を使うことで新構文は古い
"%"-書式に類似した書式になります。例えば、 "'%03.2f'" は "'{:03.2f}'"
に翻訳できます。

The new format syntax also supports new and different options, shown
in the following examples.

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

   >>> '{0}, {1}, {2}'.format('a', 'b', 'c')
   'a, b, c'
   >>> '{}, {}, {}'.format('a', 'b', 'c')  # 2.7+ 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(object):
   ...     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'

パーセントを表示する:

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

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

   >>> import datetime
   >>> d = datetime.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),
   ...     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


7.1.4. テンプレート文字列
=========================

バージョン 2.4 で追加.

テンプレート (template) を使うと、 **PEP 292** で解説されているように
より簡潔に文字列置換 (string substitution) を行えるようになります。通
常の "%" ベースの置換に代わって、テンプレートでは以下のような規則に従
った "$" ベースの置換をサポートしています:

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

* "$identifier" は置換プレースホルダの指定で、 ""identifier"" という
  キ ーへの対応付けに相当します。デフォルトは、 ""identifier"" の部分
  には Python の識別子が書かれていなければなりません。 "$" の後に識別
  子に使 えない文字が出現すると、そこでプレースホルダ名の指定が終わり
  ます。

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

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

"string" モジュールでは、上記のような規則を実装した "Template" クラス
を提供しています。 "Template" のメソッドを以下に示します:

class string.Template(template)

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

   substitute(mapping[, **kws])

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

   safe_substitute(mapping[, **kws])

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

      While other exceptions may still occur, this method is called
      "safe" because it always tries to return a usable string instead
      of raising an exception.  In another sense, "safe_substitute()"
      may be anything other than safe, since it will silently ignore
      malformed templates containing dangling delimiters, unmatched
      braces, or placeholders that are not valid Python identifiers.

   "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-z][_a-z0-9]*" という正規表現です。

他にも、クラス属性 *pattern* をオーバライドして、正規表現パターン全体
を指定できます。オーバライドを行う場合、 *pattern* の値は 4 つの名前つ
きキャプチャグループ (capturing group) を持った正規表現オブジェクトで
なければなりません。これらのキャプチャグループは、上で説明した規則と、
無効なプレースホルダに対する規則に対応しています:

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

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

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

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


7.1.5. 文字列操作関数
=====================

以下の関数は文字列または Unicode オブジェクトを操作できます。これらの
関数は文字列型のメソッドにはありません。

string.capwords(s[, sep])

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

string.maketrans(from, to)

   "translate()" に渡すのに適した変換テーブルを返します。このテーブル
   は、 *from* 内の各文字を *to* の同じ位置にある文字に対応付けます;
   *from* と *to* は同じ長さでなければなりません。

   注釈: "lowercase" と "uppercase" から取り出した文字列を引数に使っ
     てはな りません; ロケールによっては、これらは同じ長さになりません
     。大文 字小文字の変換には、常に "str.lower()" または
     "str.upper()" を使 ってください。


7.1.6. 撤廃された文字列関数
===========================

以下の一連の関数は、文字列型や Unicode 型のオブジェクトのメソッドとし
ても定義されています; 詳しくは、それらの 文字列メソッド の項を参照して
ください。ここに挙げた関数は Python 3.0 で削除されることはないはずです
が、撤廃された関数とみなして下さい。このモジュールで定義されている関数
は以下の通りです:

string.atof(s)

   バージョン 2.0 で非推奨: 組み込み関数 "float()" を使ってください。

   文字列を浮動小数点型の数値に変換します。文字列は Python における標
   準的なの浮動小数点リテラルの文法に従っていなければなりません。先頭
   に符号 ("+" または "-")が付くのは構いません。この関数に文字列を渡し
   た場合は、組み込み関数 "float()" と同じように振舞います。

   注釈: 文字列を渡した場合、根底にある C ライブラリによって NaN や
     Infinity を返す場合があります。こうした値を返させるのがどんな文字
     列の集合であるかは、全て C ライブラリに依存しており、ライブラリに
     よって異なると知られています。

string.atoi(s[, base])

   バージョン 2.0 で非推奨: 組み込み関数 "int()" を使ってください。

   文字列 *s* を、 *base* を基数とする整数に変換します。文字列は 1 桁
   またはそれ以上の数字からなっていなければなりません。先頭に符号 ("+"
   または "-") が付くのは構いません。 *base* のデフォルト値は 10 です
   。 *base* が 0 の場合、 (符号を剥ぎ取った後の) 文字列の先頭にある文
   字列に従ってデフォルトの基数を決定します。 "0x" か "0X" なら 16 、
   "0" なら 8 、その他の場合は 10 が基数になります。 *base* が 16 の場
   合、先頭の "0x" や "0X" が付いていても受け付けますが、必須ではあり
   ません。文字列を渡す場合、この関数は組み込み関数 "int()" と同じよう
   に振舞います。 (数値リテラルをより柔軟に解釈したい場合には、組み込
   み関数 "eval()" を使ってください。)

string.atol(s[, base])

   バージョン 2.0 で非推奨: 組み込み関数 "long()" を使ってください。

   文字列 *s* を、 *base* を基数とする長整数に変換します。文字列は 1
   桁またはそれ以上の数字からなっていなければなりません。先頭に符号
   ("+" または "-") が付くのは構いません。 *base* は "atoi()" と同じ意
   味です。基数が 0 の場合を除き、文字列末尾に "l" や "L" を付けてはな
   りません。 *base* を指定しないか、 10 を指定して文字列を渡した場合
   には、この関数は組み込み関数 "long()" と同じように振舞います。

string.capitalize(word)

   先頭文字だけ大文字にした *word* のコピーを返します。

string.expandtabs(s[, tabsize])

   現在のカラムと指定タブ幅に従って文字列中のタブを展開し、一つまたは
   それ以上のスペースに置き換えます。文字列中に改行が出現するたびにカ
   ラム番号は 0 にリセットされます。この関数は、他の非表示文字やエスケ
   ープシーケンスを解釈しません。タブ幅のデフォルトは 8 です。

string.find(s, sub[, start[, end]])

   "s[start:end]" の中で、部分文字列 *sub* が完全な形で入っている場所
   のうち、最初のものを *s* のインデクスで返します。見つからなかった場
   合は "-1" を返します。 *start* と *end* のデフォルト値、および、負
   の値を指定した場合の解釈は文字列のスライスと同じです。

string.rfind(s, sub[, start[, end]])

   "find()" と同じですが、最後に見つかったもののインデックスを返します
   。

string.index(s, sub[, start[, end]])

   "find()" と同じですが、部分文字列が見つからなかったときに
   "ValueError" を送出します。

string.rindex(s, sub[, start[, end]])

   "rfind()" と同じですが、部分文字列が見つからなかったときに
   "ValueError" 送出します。

string.count(s, sub[, start[, end]])

   "s[start:end]" における、部分文字列 *sub* の (重複しない) 出現回数
   を返します。 *start* と *end* のデフォルト値、および、負の値を指定
   した場合の解釈は文字列のスライスと同じです。

string.lower(s)

   *s* のコピーを大文字を小文字に変換して返します。

string.split(s[, sep[, maxsplit]])

   文字列 *s* 内の単語からなるリストを返します。オプションの第二引数
   *sep* を指定しないか、または "None" にした場合、空白文字 (スペース
   、タブ、改行、リターン、改頁) からなる任意の文字列で単語に区切りま
   す。 *sep* を "None" 以外の値に指定した場合、単語の分割に使う文字列
   の指定になります。戻り値のリストには、文字列中に分割文字列が重複せ
   ずに出現する回数より一つ多い要素が入るはずです。 *maxsplit* が与え
   られた場合には、最大でも *maxsplit* 回の分割しか行わず、リストの最
   後の要素は未分割の残りの文字列になります (従って、リスト中の要素数
   は最大でも "maxsplit+1" です)。 *maxsplit* の指定がないか "-1" の場
   合は、分割数は制限されません (可能な全ての分割を行います)。

   空文字列に対する分割を行った場合の挙動は *sep* の値に依存します。
   *sep* を指定しないか "None" にした場合、結果は空のリストになります
   。 *sep* に文字列を指定した場合、空文字列一つの入ったリストになりま
   す。

string.rsplit(s[, sep[, maxsplit]])

   *s* 中の単語からなるリストを *s* の末尾から検索して生成し返します。
   関数の返す語のリストは全ての点で "split()" の返すものと同じになりま
   す。ただし、オプションの第三引数 *maxsplit* をゼロでない値に指定し
   た場合には必ずしも同じにはなりません。 *maxsplit* が与えられた場合
   には、最大で *maxsplit* 個の分割を *右端から* 行います - 未分割の残
   りの文字列はリストの最初の要素として返されます (従って、リスト中の
   要素数は最大でも "maxsplit+1" です)。

   バージョン 2.4 で追加.

string.splitfields(s[, sep[, maxsplit]])

   この関数は "split()" と同じように振舞います。 (以前は "split()" は
   単一引数の場合にのみ使い、 "splitfields()" は引数 2 つの場合でのみ
   使っていました)。

string.join(words[, sep])

   単語のリストやタプルを間に *sep* を入れて連結します。 *sep* のデフ
   ォルト値はスペース文字 1 つです。 "string.join(string.split(s,
   sep), sep)" は常に *s* になります。

string.joinfields(words[, sep])

   この関数は "join()" と同じふるまいをします (以前は、 "join()" を使
   えるのは引数が 1 つの場合だけで、 "joinfields()" は引数 2 つの場合
   だけでした)。文字列オブジェクトには "joinfields()" メソッドがないの
   で注意してください。代わりに "join()" メソッドを使ってください。

string.lstrip(s[, chars])

   文字列の先頭から文字を取り除いたコピーを生成して返します。 *chars*
   を指定しない場合や "None" にした場合、先頭の空白を取り除きます。
   *chars* を "None" 以外の値にする場合、 *chars* は文字列でなければな
   りません。

   バージョン 2.2.3 で変更: *chars* パラメータを追加しました。初期の
   2.2 バージョンでは、 *chars* パラメータを渡せませんでした。

string.rstrip(s[, chars])

   文字列の末尾から文字を取り除いたコピーを生成して返します。 *chars*
   を指定しない場合や "None" にした場合、末尾の空白を取り除きます。
   *chars* を "None" 以外の値にする場合、 *chars* は文字列でなければな
   りません。

   バージョン 2.2.3 で変更: *chars* パラメータを追加しました。初期の
   2.2 バージョンでは、 *chars* パラメータを渡せませんでした。

string.strip(s[, chars])

   文字列の先頭と末尾から文字を取り除いたコピーを生成して返します。
   *chars* を指定しない場合や "None" にした場合、先頭と末尾の空白を取
   り除きます。 *chars* を "None" 以外に指定する場合、 *chars* は文字
   列でなければなりません。

   バージョン 2.2.3 で変更: *chars* パラメータを追加しました。初期の
   2.2 バージョンでは、 *chars* パラメータを渡せませんでした。

string.swapcase(s)

   *s* の大文字と小文字を入れ替えたものを返します。

string.translate(s, table[, deletechars])

   *s* の中から、 (もし指定されていれば) *deletechars* に入っている文
   字を削除し、 *table* を使って文字変換を行って返します。 *table* は
   256 文字からなる文字列で、各文字はそのインデクスを序数とする文字に
   対する変換先の文字の指定になります。もし、 *table* が "None" であれ
   ば、文字削除のみが行われます。

string.upper(s)

   *s* に含まれる小文字を大文字に置換して返します。

string.ljust(s, width[, fillchar])
string.rjust(s, width[, fillchar])
string.center(s, width[, fillchar])

   文字列を指定した文字幅のフィールド中でそれぞれ左寄せ、右寄せ、中央
   寄せします。これらの関数は指定幅になるまで文字列 *s* の左側、右側、
   および、両側のいずれかに *fillchar* （デフォルトでは空白）を追加し
   て、少なくとも *width* 文字からなる文字列にして返します。文字列を切
   り詰めることはありません。

string.zfill(s, width)

   数値を表現する文字列 *s* の左側に、指定の幅 *width* になるまでゼロ
   を付加します。符号付きの数字も正しく処理します。

string.replace(s, old, new[, maxreplace])

   *s* 内の部分文字列 *old* を全て *new* に置換したものを返します。
   *maxreplace* を指定した場合、最初に見つかった *maxreplace* 個分だけ
   置換します。
