
:mod:`string` --- 一般的な文字列操作
====================================

.. module:: string
   :synopsis: 一般的な文字列操作


.. index:: module: re

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


文字列定数
----------

このモジュールでは以下の定数を定義しています。


.. data:: ascii_letters

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


.. data:: ascii_lowercase

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


.. data:: ascii_uppercase

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


.. data:: digits

   文字列 ``'0123456789'`` です。


.. data:: hexdigits

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


.. data:: letters

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


.. data:: lowercase

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


.. data:: octdigits

   文字列 ``'01234567'`` です。


.. data:: punctuation

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


.. data:: printable

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


.. data:: uppercase

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


.. data:: whitespace

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


.. _new-string-formatting:

文字列の書式指定
-----------------

Python 2.6 から、組み込みの str 、および、 unicode クラスは、
:pep:`3101` に記載される :meth:`str.format` メソッドによる、複雑な変数
置換と値の書式指定を提供するようになりました。 :mod:`string` モジュー
ルの :class:`Formatter` クラスは組み込みの :meth:`format` メソッドと同
じ実装で、文字列の書式指定の作成とカスタマイズを可能にします。

.. class:: Formatter

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

   .. method:: format(format_string, *args, *kwargs)

      :meth:`format` は主たる API メソッドです。引数は、書式指定テンプ
      レート文字列、および、任意のポジション、キーワードをとります。
      :meth:`format` は、 :meth:`vformat` を呼び出すだけのラッパーです。

   .. method:: vformat(format_string, args, kwargs)

      この関数は、書式指定の操作を行います。 ``*args`` や ``**kwds``
      を使った書式で辞書をアンパックやリパックするのではなく、予め定義
      された辞書を引数として与えたいときなどでは、独立した関数として露
      出されます。 :meth:`vformat` は書式テンプレート文字列を、文字デー
      タや置換フィールドに展開します。この関数は、以下の様々なメソッド
      を呼び出します。

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

   .. method:: parse(format_string)

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

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

   .. method:: get_field(field_name, args, kwargs)

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

   .. method:: get_value(key, args, kwargs)

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

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

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

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

      もし、インデックス、もしくは、キーワードが存在しないアイテムを参
      照したら、 :exc:`IndexError` 、もしくは、 :exc:`KeyError` が送出
      されます。

   .. method:: check_unused_args(used_args, args, kwargs)

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

   .. method:: format_field(value, format_spec)

      :meth:`format_field` は単純に組み込みのグローバル関数
      :func:`format` を呼び出します。
      このメソッドは、サブクラスをオーバーライドするために提供されます。

   .. method:: convert_field(value, conversion)

      (:meth:`get_field` が返す) 値を、与えられた conversion 型に
      (:meth:`parse` がタプルを返すように) 変換します。デフォルトでは
      'r'(repr) と 's'(str) 変換型を解釈できます。


.. _formatstrings:

書式指定文字列の文法
--------------------

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

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

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

   .. productionlist:: sf
      replacement_field: "{" `field_name` ["!" `conversion`] [":" `format_spec`] "}"
      field_name: (`identifier` | `integer`) ("." `attribute_name` | "[" `element_index` "]")*
      attribute_name: `identifier`
      element_index: `integer`
      conversion: "r" | "s"
      format_spec: <described in the next section>

公式な用語はさておき、置換フィールドは *field_name* (ポジション引数と
しての数字でも構いません) 、あるいは、 (キーワード引数の) 識別子から始
まります。次いで、感嘆符 ``'!'`` を挟んでオプションの *conversion* フィー
ルドを書きます。最後にコロン ``':'`` を挟んで、 *format_spec* を書きま
す。

*field_name* は数字かキーワードで始まります。数字である場合、ポジショ
ン引数として扱われます。キーワードである場合、キーワード引数として扱わ
れます。これに他の数字やインデックスや属性表現が続いても構いません。
``'.name'`` 形式の表現の場合、 :func:`getattr` 使って属性が選択され、
``'[index]'`` 形式の表現の場合、 :func:`__getitem__` を使ってインデッ
クス検索されます。

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

   "First, thou shalt count to {0}" # 最初のポジション引数を参照します
   "My quest is {name}"             # キーワード引数 'name' を参照します
   "Weight in tons {0.weight}"      # 最初のポジション引数の属性 'weight' を参照します
   "Units destroyed: {players[0]}"  # キーワード引数 'players' の最初の要素を参照します

*conversion* フィールドにより書式変換前に型の強制変換が実施されます。
通常、値の書式変換は :meth:`__format__` によって実施されます。しかしな
がら、場合によっては、文字列として変換することを強制したり、書式指定の
定義をオーバーライドしたくなることもあります。 :meth:`__format__` の呼
び出し前に値を文字列に変換すると、通常の書式変換の処理は飛ばされます。

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

例::

   "Harold's a clever {0!s}"        # 引数に対して、最初に str() を呼び出します
   "Bring out the holy {name!r}"    # 引数に対して、最初に repr() を呼び出します

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

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

*format_spec* フィールドは入れ子になった置換フィールドを含むこともでき
ます。入れ子になった置換フィールドはフィールド名だけを含むことができま
す; 変換フラグや書式指定は不可です。 format_spec 中の置換フィールドは
*format_spec* 文字列が解釈される前に置き換えられます。これにより、値の
書式動的に指定することが可能になります。

例えば、置換フィールドの幅を他の値によって決めたいと思ったとします::

   "A man with two {0:{1}}".format("noses", 10)

この例では、最初に内側の置換フィールドが評価され、書式指定文字列は以下
のようになります::

   "A man with two {0:10}"

次に、外側の置換フィールドが評価され、以下となります::

   "noses     "

これが置き換えられ、文字列は以下となります::

   "A man with two noses     "

(追加のスペースはフィールド幅を10に指定したためであり、左寄せになって
いるのはデフォルトのアラインメントになるためです。)


.. _formatspec:

書式指定ミニ言語仕様 (Format Specification Mini-Language)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

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

一般的な変換は空の書式指定文字列 (``""``) が作る、値に対して
:func:`str` を呼び出したときと同じ値のものです。

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

.. productionlist:: sf
   format_spec: [[`fill`]`align`][`sign`][#][0][`width`][.`precision`][`type`]
   fill(詰め方): <'}'以外の文字>
   align(整列): "<" | ">" | "=" | "^"
   sign(符号): "+" | "-" | " "
   width(幅): `整数`
   precision(精度): `整数`
   type: "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "n" | "o" | "x" | "X" | "%"

*fill* は、 (フィールドの終わりを示す) '}' 以外のどんな文字でもかまいません。
fill 文字の有無は、 align オプションが続くことによって、示されます。
もし、 *format_spec* の二つめの文字が align オプションで無い場合は、
fill と align の両方のオプションが無いものと解釈されます。

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

   +------------+----------------------------------------------------------+
   | オプション | 意味                                                     |
   +============+==========================================================+
   | ``'<'``    | 利用可能なスペースにおいて、左詰めを強制します。         |
   |            | (デフォルト)                                             |
   +------------+----------------------------------------------------------+
   | ``'>'``    | 利用可能なスペースにおいて、右詰めを強制します。         |
   |            |                                                          |
   +------------+----------------------------------------------------------+
   | ``'='``    | 符号 (があれば) の後ろを埋めます。                       |
   |            | '+000000120' のような形で表示されます。                  |
   |            | このオプションは数値型に対してのみ有効です。             |
   +------------+----------------------------------------------------------+
   | ``'^'``    | 資料可能なスペースにおいて、中央寄せを強制します。       |
   |            |                                                          |
   +------------+----------------------------------------------------------+

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

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

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

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

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

もし *width* フィールドがゼロ (``'0'``) で始まる場合、ゼロ埋めとなります。
これは、 *alignment* 型が ``'='`` で、 *fill* 文字が ``'0'`` であることと等価です。

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

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

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

   +---------+----------------------------------------------------------+
   | 型      | 意味                                                     |
   +=========+==========================================================+
   | ``'b'`` | 2進数。出力される数値は2を基数とします。                 |
   +---------+----------------------------------------------------------+
   | ``'c'`` | 文字。数値を対応するユニコード文字に変換します。         |
   |         |                                                          |
   +---------+----------------------------------------------------------+
   | ``'d'`` | 10進数。出力される数値は10を基数とします。               |
   +---------+----------------------------------------------------------+
   | ``'o'`` | 8進数。出力される数値は8を基数とします。                 |
   +---------+----------------------------------------------------------+
   | ``'x'`` | 16進数。出力される数値は16を基数とします。               |
   |         | 10進で9を越える数字には小文字が使われます。              |
   +---------+----------------------------------------------------------+
   | ``'X'`` | 16進数。出力される数値は16を基数とします。               |
   |         | 10進で9を越える数字には大文字が使われます。              |
   +---------+----------------------------------------------------------+
   | ``'n'`` | 数値。現在のロケールに従い、区切り文字を挿入すること     |
   |         | を除けば、 ``'d'`` と同じです。                          |
   |         |                                                          |
   +---------+----------------------------------------------------------+
   | 空白    | ``'d'`` と同じです。                                     |
   +---------+----------------------------------------------------------+

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

   +---------+----------------------------------------------------------+
   | 型      | 意味                                                     |
   +=========+==========================================================+
   | ``'e'`` | 指数指定です。指数を示す 'e' を使って数値を表示します。  |
   |         |                                                          |
   +---------+----------------------------------------------------------+
   | ``'E'`` | 指数指定です。大文字の 'E' を使うことを除いては、        |
   |         | ``'e'`` と同じです。                                     |
   +---------+----------------------------------------------------------+
   | ``'f'`` | 固定小数点数です。数値を固定小数点数として表示します。   |
   |         |                                                          |
   +---------+----------------------------------------------------------+
   | ``'F'`` | 固定小数点数です。 ``'f'`` と同じです。                  |
   +---------+----------------------------------------------------------+
   | ``'g'`` | 標準フォーマットです。数値が大き過ぎない限り、数値を     |
   |         | 固定小数点数で表示し、そうで無い場合は、 ``'e'`` による  |
   |         | 指数表示に切り替えます。無限大、および、 NaN は、        |
   |         | ``inf``, ``-inf`` 、および、 ``nan`` となります。        |
   |         |                                                          |
   +---------+----------------------------------------------------------+
   | ``'G'`` | 標準フォーマットです。数値が大きくなったとき、 ``'E'``   |
   |         | に切り替わることを除き、 ``'g'`` と同じです。            |
   |         | 無限大と NaN の表示も大文字になります。                  |
   +---------+----------------------------------------------------------+
   | ``'n'`` | 数値です。現在のロケールに合わせて、数値分割文字が挿入   |
   |         | されることを除き、 ``'g'`` と同じです。                  |
   |         |                                                          |
   +---------+----------------------------------------------------------+
   | ``'%'`` | パーセンテージです。数値は 100 倍され、固定小数点数フォ  |
   |         | ーマット (``'f'``) でパーセント記号付きで表示されます。  |
   +---------+----------------------------------------------------------+
   | None    | ``'g'`` と同じです。                                     |
   +---------+----------------------------------------------------------+


テンプレート文字列
------------------

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

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

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

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

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

.. versionadded:: 2.4

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


.. class:: Template(template)

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


   .. method:: substitute(mapping[, **kws])

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


   .. method:: safe_substitute(mapping[, **kws])

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

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

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


.. attribute:: string.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 10
   >>> Template('$who likes $what').substitute(d)
   Traceback (most recent call last):
   [...]
   KeyError: 'what'
   >>> Template('$who likes $what').safe_substitute(d)
   'tim likes $what'

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

* *delimiter* -- プレースホルダの開始を示すリテラル文字列です。デフォ
   ルトの値は ``$`` です。実装系はこの文字列に対して必要に応じて
   :meth:`re.escape` を呼び出すので、正規表現を表すような文字列にして
   は *なりません* 。

* *idpattern* -- 波括弧でくくらない形式のプレースホルダの表記パターン
   を示す正規表現です (波括弧は自動的に適切な場所に追加されます)　。デ
   フォルトの値は ``[_a-z][_a-z0-9]*`` という正規表現です。

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

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

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

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

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


文字列操作関数
--------------

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


.. function:: capwords(s)

   :func:`split` を使って引数を単語に分割し、 :func:`capitalize` を使っ
   てそれぞれの単語の先頭の文字を大文字に変換し、 :func:`join` を使っ
   てつなぎ合わせます。この置換処理は文字列中の連続する空白文字をスペー
   ス一つに置き換え、先頭と末尾の空白を削除するので注意してください。


.. function:: maketrans(from, to)

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

   .. warning::

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


撤廃された文字列関数
--------------------

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


.. function:: atof(s)

   .. deprecated:: 2.0
      組み込み関数 :func:`float` を使ってください。

   .. index:: builtin: float

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

   .. note::

      .. index::
         single: NaN
         single: Infinity

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


.. function:: atoi(s[, base])

   .. deprecated:: 2.0
      組み込み関数 :func:`int` を使ってください。

   .. index:: builtin: eval

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


.. function:: atol(s[, base])

   .. deprecated:: 2.0
      組み込み関数 :func:`long` を使ってください。

   .. index:: builtin: long

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


.. function:: capitalize(word)

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


.. function:: expandtabs(s[, tabsize])

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


.. function:: find(s, sub[, start[,end]])

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


.. function:: rfind(s, sub[, start[, end]])

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


.. function:: index(s, sub[, start[, end]])

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


.. function:: rindex(s, sub[, start[, end]])

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


.. function:: count(s, sub[, start[, end]])

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


.. function:: lower(s)

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


.. function:: split(s[, sep[, maxsplit]])

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

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


.. function:: rsplit(s[, sep[, maxsplit]])

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

   .. versionadded:: 2.4


.. function:: splitfields(s[, sep[, maxsplit]])

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


.. function:: join(words[, sep])

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


.. function:: joinfields(words[, sep])

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


.. function:: lstrip(s[, chars])

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

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


.. function:: rstrip(s[, chars])

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

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


.. function:: strip(s[, chars])

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

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


.. function:: swapcase(s)

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


.. function:: translate(s, table[, deletechars])

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


.. function:: upper(s)

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


.. function:: ljust(s, width)
              rjust(s, width)
              center(s, width)

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


.. function:: zfill(s, width)

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


.. function:: replace(str, old, new[, maxreplace])

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