..
    ====================================================================
    StringIO and cStringIO -- Work with text buffers using file-like API
    ====================================================================

======================================================================
StringIO と cStringIO -- ファイルのような API でテキストバッファを扱う
======================================================================

.. module:: StringIO
    :synopsis: ファイルのような API でテキストバッファを扱う

.. module:: cStringIO
    :synopsis: ファイルのような API でテキストバッファを扱う

..
    :Purpose: Work with text buffers using file-like API
    :Available In: StringIO: 1.4, cStringIO: 1.5

:目的: ファイルのような API でテキストバッファを扱う
:利用できるバージョン: StringIO: 1.4, cStringIO: 1.5

..
    :class:`StringIO` provides a convenient means of working with text in
    memory using the file API (read, write. etc.). There are two separate
    implementations. The :mod:`cStringIO` version is written in C for
    speed, while :mod:`StringIO` is written in Python for
    portability. Using :mod:`cStringIO` to build large strings can offer
    performance savings over some other string conctatenation techniques.

:class:`StringIO` はファイルのような API (read, write 等) を使用してメモリ内のテキストを扱う便利な機能を提供します。 :class:`StringIO` には2つの独立した実装があります。 :mod:`cStringIO` バージョンは速度を考慮して C 言語で実装されています。一方 :mod:`StringIO` は移植性を考慮して Python で実装されています。巨大な文字列を構成するために :mod:`cStringIO` を使用することは、他の文字列連結のテクニックよりも実行速度が速くなります。

..
    Example
    =======

サンプル
========

..
    Here are some pretty standard, simple, examples of using
    :class:`StringIO` buffers:

:class:`StringIO` バッファの標準的で簡単な使用例は次の通りです。

.. include:: stringio_examples.py
    :literal:
    :start-after: #end_pymotw_header

..
    This example uses :func:`read()`, but the :func:`readline()` and
    :func:`readlines()` methods are also available. The :class:`StringIO`
    class also provides a :func:`seek()` method so it is possible to jump
    around in a buffer while reading, which can be useful for rewinding if
    you are using some sort of look-ahead parsing algorithm.

この例では :func:`read()` を使用しますが、 :func:`readline()` や :func:`readlines()` メソッドも使用することができます。また :class:`StringIO` クラスは読み込みであるバッファの位置へジャンプできるように :func:`seek()` メソッドも提供します。 :func:`seek` は、ある種の先読み解析アルゴリズムを使用する場合、ファイル位置を巻き戻すために役に立ちます。

.. {{{cog
.. cog.out(run_script(cog.inFile, 'stringio_examples.py'))
.. }}}

::

	$ python stringio_examples.py
	This goes into the buffer. And so does this.
	
	Inital value for read buffer

.. {{{end}}}

..
    Real world applications of :mod:`StringIO` include a web application
    stack where various parts of the stack may add text to the response,
    or testing the output generated by parts of a program which typically
    write to a file.

:mod:`StringIO` を使用した実際のアプリケーションは、レスポンスに対してテキストを追加するようなスタックの様々な部分で使用する web アプリケーションスタック、又はあるファイルへの典型的な書き込みを行うプログラムの一部で生成された出力のテストに使用します。

..
    The application we are building at work includes a shell scripting
    interface in the form of several command line programs. Some of these
    programs are responsible for pulling data from the database and
    dumping it on the console (either to show the user, or so the text can
    serve as input to another command). The commands share a set of
    formatter plugins to produce a text representation of an object in a
    variety of ways (XML, bash syntax, human readable, etc.). Since the
    formatters normally write to standard output, testing the results
    would be a little tricky without the StringIO module. Using StringIO
    to intercept the output of the formatter gives us an easy way to
    collect the output in memory to compare against expected results.

我々がお仕事で開発しているアプリケーションは複数のコマンドラインプログラムからなるシェルスクリプトのインタフェースを含みます。あるシェルスクリプトプログラムでは、データベースからデータを取得して、そのデータをコンソールへ出力する(ユーザへ表示するか、そのテキストを他コマンドへの入力として渡すかのどちらかです)機能を提供します。そのコマンドは様々な方法(XML, bash 構文, 人間が読み易いフォーマット等)でオブジェクトのテキスト出力を生成するためにフォーマッタプラグインセットを共有します。そのフォーマッタは通常は標準出力に書き込むので、StringIO モジュールを使用せずにその出力結果をテストすることはちょっと扱いにくいです。そのフォーマッタの出力結果を途中で取得するために StringIO を使用することは、予想される結果を比較するためにメモリ内にその出力結果を集める簡単な方法になります。

..
    `StringIO <http://docs.python.org/lib/module-StringIO.html>`_
        Standard library documentation for this module.
    `The StringIO module ::: www.effbot.org <http://effbot.org/librarybook/stringio.htm>`_
        effbot's examples with StringIO
    `Efficient String Concatenation in Python <http://www.skymind.com/%7Eocrow/python_string/>`_
        Examines various methods of combining strings and their relative merits.

.. seealso::

    `StringIO <http://docs.python.org/lib/module-StringIO.html>`_
        本モジュールの標準ライブラリドキュメント

    `The StringIO module ::: www.effbot.org <http://effbot.org/librarybook/stringio.htm>`_
        StringIO に関する effbot のサンプル

    `Python における効率的な文字列連結 <http://www.skymind.com/%7Eocrow/python_string/>`_
        文字列を連結する様々な方法とその利点の調査