\section{\module{array} ---
         効率のよい数値アレイ}

\declaremodule{builtin}{array}
\modulesynopsis{一様な型を持つ数値からなる効率のよいアレイ。}


このモジュールでは、基本的な値 (文字、整数、浮動小数点数) のアレイ
(array、配列) を効率よく表現できるオブジェクト型を定義しています。
アレイ\index{arrays}はシーケンス (sequence) 型であり、中に入れる
オブジェクトの型に制限があることを除けば、リストとまったく同じように振
る舞います。オブジェクト生成時に一文字の\dfn{型コード} を用いて型を指
定します。次の型コードが定義されています:

\begin{tableiv}{c|l|l|c}{code}{型コード}{C の型}{Python の型}
{最小サイズ (バイト単位)}
  \lineiv{'c'}{char}          {文字(str型)}           {1}
  \lineiv{'b'}{signed char}   {int型}                 {1}
  \lineiv{'B'}{unsigned char} {int型}                 {1}
  \lineiv{'u'}{Py_UNICODE}    {Unicode文字(unicode型)}{2}
  \lineiv{'h'}{signed short}  {int型}                 {2}
  \lineiv{'H'}{unsigned short}{int型}                 {2}
  \lineiv{'i'}{signed int}    {int型}                 {2}
  \lineiv{'I'}{unsigned int}  {long型}                {2}
  \lineiv{'l'}{signed long}   {int型}                 {4}
  \lineiv{'L'}{unsigned long} {long型}                {4}
  \lineiv{'f'}{float}         {float型}               {4}
  \lineiv{'d'}{double}        {float型}               {8}
\end{tableiv}

値の実際の表現はマシンアーキテクチャ (厳密に言うとCの実装) によって決
まります。値の実際のサイズは\member{itemsize} 属性から得られます。
Python の通常の整数型では C の unsigned (long) 整数の最大範囲を表せな
いため、\code{'L'}と\code{'I'} で表現されている要素に入る値は Python
では長整数として表されます。

このモジュールでは次の型を定義しています:

\begin{funcdesc}{array}{typecode\optional{, initializer}}
要素のデータ型が\var{typecode}に限定される新しいアレイを返します。
オプションの値\var{initializer}をわたすと初期値になりますが、
リスト、文字列または適当な型のイテレーション可能オブジェクトでなければ
なりません。

\versionchanged[以前はリストか文字列しか受け付けませんでした。]{2.4} 
リストか文字列を渡した場合、新たに作成されたアレイの\method{fromlist()}、
\method{fromstring()}あるいは\method{fromunicode()}メソッド (以下を参照
して下さい) に渡され、初期値としてアレイに追加されます。それ以外の場合
には、イテレーション可能オブジェクト \var{initializer} は新たに作成
されたオブジェクトの\method{extend()}メソッドに渡されます。
\end{funcdesc}

\begin{datadesc}{ArrayType}
\function{array}の別名です。撤廃されました。
\end{datadesc}


アレイオブジェクトでは、インデクス指定、スライス、連結および反復といっ
た、通常のシーケンスの演算をサポートしています。スライス代入を使うときは、
代入値は同じ型コードのアレイオブジェクトでなければなりません。
それ以外のオブジェクトを指定すると\exception{TypeError} を送出します。
アレイオブジェクトはバッファインタフェースを実装しており、
バッファオブジェクトをサポートしている場所ならどこでも利用できます。

次のデータ要素やメソッドもサポートされています:

\begin{memberdesc}[array]{typecode}
アレイを作るときに使う型コード文字です。
\end{memberdesc}

\begin{memberdesc}[array]{itemsize}
アレイの要素 1 つの内部表現に使われるバイト長です。
\end{memberdesc}


\begin{methoddesc}[array]{append}{x}
値\var{x} の新たな要素をアレイの末尾に追加します。
\end{methoddesc}

\begin{methoddesc}[array]{buffer_info}{}
アレイの内容を記憶するために使っているバッファの、現在のメモリアドレス
と要素数の入ったタプル\code{(\var{address}, \var{length})} を返します。
バイト単位で表したメモリバッファの大きさは
\code{\var{array}.buffer_info()[1] * \var{array}.itemsize}で計算できま
す。例えば\cfunction{ioctl()} 操作のような、メモリアドレスを必要とする
低レベルな (そして、本質的に危険な) I/Oインタフェースを使って作業する
場合に、ときどき便利です。アレイ自体が存在し、長さを変えるような演算を
適用しない限り、有効な値を返します。

\note{C や\Cpp{} で書いたコードからアレイオブジェクトを使う場合
(\method{buffer_info} の情報を使う意味のある唯一の方法です) は、
アレイオブジェクトでサポートしているバッファインタフェースを使う方が
より理にかなっています。このメソッドは後方互換性のために保守されており、
新しいコードでの使用は避けるべきです。バッファインタフェースの説明は
\citetitle[../api/newTypes.html]{Python/C APIリファレンスマニュアル}
にあります。}

\end{methoddesc}

\begin{methoddesc}[array]{byteswap}{}
アレイのすべての要素に対して「バイトスワップ」(リトルエンディアンとビッ
グエンディアンの変換) を行います。このメソッドは大きさが 1、2、4 およ
び 8 バイトの値にのみをサポートしています。他の型の値に使うと
\exception{RuntimeError} を送出します。異なるバイトオーダをもつ計算機
で書かれたファイルからデータを読み込むときに役に立ちます。
\end{methoddesc}

\begin{methoddesc}[array]{count}{x}
シーケンス中の\var{x} の出現回数を返します。
\end{methoddesc}

\begin{methoddesc}[array]{extend}{iterable}
\var{iterable} から要素を取り出し、アレイの末尾に要素を追加します。
\var{iterable} が別のアレイ型である場合、二つのアレイは\emph{全く}同
じ型コードをでなければなりません。それ以外の場合には
\exception{TypeError} を送出します。
\var{iterable} がアレイでない場合、アレイに値を追加できるような正しい
型の要素からなるイテレーション可能オブジェクトでなければなりません。
\versionchanged[以前は他のアレイ型しか引数に指定できませんでした。]{2.4}
\end{methoddesc}

\begin{methoddesc}[array]{fromfile}{f, n}
ファイルオブジェクト\var{f} から (マシン依存のデータ形式そのままで)
\var{n} 個の要素を読み出し、アレイの末尾に要素を追加します。
\var{n} 個の要素を読めなかったときは\exception{EOFError} を送出します
が、それまでに読み出せた値はアレイに追加されています。
\var{f} は本当の組み込みファイルオブジェクトでなければなりません。
\method{read()}メソッドをもつ他の型では動作しません。
\end{methoddesc}

\begin{methoddesc}[array]{fromlist}{list}
リストから要素を追加します。型に関するエラーが発生した場合にアレイが変
更されないことを除き、\samp{for x in \var{list}:\ a.append(x)}と同じです。
\end{methoddesc}

\begin{methoddesc}[array]{fromstring}{s}
文字列から要素を追加します。文字列は、 (ファイルから
\method{fromfile()} メソッドを使って値を読み込んだときのように)
マシン依存のデータ形式で表された値の配列として解釈されます。
\end{methoddesc}

\begin{methoddesc}[array]{fromunicode}{s}
指定した Unicode 文字列のデータを使ってアレイを拡張します。アレイの
型コードは \code{'u'} でなければなりません。それ以外の場合には、
\exception{ValueError} を送出します。他の型のアレイに Unicode 型のデータ
を追加するには、\samp{array.fromstring(ustr.decode(enc))} を使ってくだ
さい。
\end{methoddesc}

\begin{methoddesc}[array]{index}{x}
アレイ中で\var{x} が出現するインデクスのうち最小の値 \var{i} を返しま
す。
\end{methoddesc}

\begin{methoddesc}[array]{insert}{i, x}
アレイ中の位置\var{i} の前に値\var{x} をもつ新しい要素を挿入します。
\var{i} の値が負の場合、アレイの末尾からの相対位置として扱います。
\end{methoddesc}

\begin{methoddesc}[array]{pop}{\optional{i}}
アレイからインデクスが\var{i} の要素を取り除いて返します。
オプションの引数はデフォルトで\code{-1} になっていて、最後の要素を取り
除いて返すようになっています。
\end{methoddesc}

\begin{methoddesc}[array]{read}{f, n}
\deprecated {1.5.1}
  {\method{fromfile()}メソッドを使ってください。}
ファイルオブジェクト\var{f} から (マシン依存のデータ形式そのままで)
\var{n} 個の要素を読み出し、アレイの末尾に要素を追加します。
\var{n} 個の要素を読めなかったときは\exception{EOFError} を送出します
が、それまでに読み出せた値はアレイに追加されています。
\var{f} は本当の組み込みファイルオブジェクトでなければなりません。
\method{read()}メソッドをもつ他の型では動作しません。
\end{methoddesc}

\begin{methoddesc}[array]{remove}{x}
アレイ中の\var{x} のうち、最初に現れたものを取り除きます。
\end{methoddesc}

\begin{methoddesc}[array]{reverse}{}
アレイの要素の順番を逆にします。
\end{methoddesc}

\begin{methoddesc}[array]{tofile}{f}
アレイのすべての要素をファイルオブジェクト\var{f}に
(マシン依存のデータ形式そのままで)書き込みます。
\end{methoddesc}

\begin{methoddesc}[array]{tolist}{}
アレイを同じ要素を持つ普通のリストに変換します。
\end{methoddesc}

\begin{methoddesc}[array]{tostring}{}
アレイをマシン依存のデータアレイに変換し、文字列表現
(\method{tofile()} メソッドによってファイルに書き込まれるものと同じ
バイト列) を返します。
\end{methoddesc}

\begin{methoddesc}[array]{tounicode}{}
アレイを Unicode 文字列に変換します。アレイの型コードは \code{'u'} でなければ
なりません。それ以外の場合には \exception{ValueError} を送出します。
他の型のアレイから Unicode 文字列を得るには、
\samp{array.tostring().decode(enc)} を使ってください。
\end{methoddesc}

\begin{methoddesc}[array]{write}{f}
\deprecated {1.5.1}
  {\method{tofile()}メソッドを使ってください。}
ファイルオブジェクト\var{f}に、全ての要素を(マシン依存のデータ形式その
ままで)書き込みます。
\end{methoddesc}

アレイオブジェクトを表示したり文字列に変換したりすると、
\code{array(\var{typecode}, \var{initializer})} という形式で表現されま
す。アレイが空の場合、\var{initializer} の表示を省略します。アレイが
空でなければ、\var{typecode} が \code{'c'} の場合には文字列に、
それ以外の場合には数値のリストになります。
関数\function{array()} を\code{from array import array} で import して
いる限り、変換後の文字列に逆クォーテーション(\code{``})を用いると
元のアレイオブジェクトと同じデータ型と値を持つアレイに逆変換できること
が保証されています。文字列表現の例を以下に示します:

\begin{verbatim}
array('l')
array('c', 'hello world')
array('u', u'hello \textbackslash u2641')
array('l', [1, 2, 3, 4, 5])
array('d', [1.0, 2.0, 3.14])
\end{verbatim}


\begin{seealso}
  \seemodule{struct}
{異なる種類のバイナリデータのパックおよびアンパック。}
  \seemodule{xdrlib}
{遠隔手続き呼び出しシステムで使われる外部データ表現仕様 (External Data
Representation, XDR) のデータのパックおよびアンパック。}
  \seetitle[http://numpy.sourceforge.net/numdoc/HTML/numdoc.htm]
{The Numerical Python Manual}
{Numeric Python 拡張モジュール (NumPy) では、別の方法でシーケンス型を定義
しています。Numerical Python に関する詳しい情報は
\url{http://numpy.sourceforge.net/}を参照してください。
(NumPy マニュアルの PDF バージョンは
\url{http://numpy.sourceforge.net/numdoc/numdoc.pdf}で手に入ります。}

\end{seealso}
