\chapter{抽象オブジェクトレイヤ (abstract objects layer) \label{abstract}}

この章で説明する関数は、Python オブジェクトとのやりとりを型や
(数値型全て、シーケンス型全てといった) 大まかなオブジェクト型の種類に
関係なく行います。関数を適用対象でないオブジェクトに対して
使った場合、 Python の例外が送出されることになります。

これらの関数は、\cfunction{PyList_New()}で作成された後に\code{NULL}以外の値を
設定されていないリストのような、適切に初期化されていないオブジェクトに対して
使うことはできません。

\section{オブジェクトプロトコル (object protocol) \label{object}}

\begin{cfuncdesc}{int}{PyObject_Print}{PyObject *o, FILE *fp, int flags}
オブジェクト \var{o} をファイル \var{fp} に出力します。
失敗すると\code{-1} を返します。
\var{flags} 引数は何らかの出力オプションを有効にする際に使います。
現在サポートされている唯一のオプションは\constant{Py_PRINT_RAW} です;
このオプションを指定すると、\function{repr()} の代わりに
\function{str()} を使ってオブジェクトを書き込みます。
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PyObject_HasAttrString}{PyObject *o, const char *attr_name}
\var{o} が属性 \var{attr_name} を持つときに \code{1} を、それ以外の
ときに \code{0} を返します。この関数は Python の式
  \samp{hasattr(\var{o}, \var{attr_name})} と同じです。
この関数は常に成功します。
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PyObject_GetAttrString}{PyObject *o,
                                                     const char *attr_name}
オブジェクト \var{o} から、名前 \var{attr_name} の属性を取得します。
成功すると属性値を返し失敗すると \NULL{} を返します。
この関数は Python の式 \samp{\var{o}.\var{attr_name}}
と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{int}{PyObject_HasAttr}{PyObject *o, PyObject *attr_name}
\var{o} が属性 \var{attr_name} を持つときに \code{1} を、それ以外の
ときに \code{0} を返します。この関数は Python の式
  \samp{hasattr(\var{o}, \var{attr_name})} と同じです。
この関数は常に成功します。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyObject_GetAttr}{PyObject *o,
                                               PyObject *attr_name}
オブジェクト \var{o} から、名前 \var{attr_name} の属性を取得します。
成功すると属性値を返し失敗すると \NULL{} を返します。
この関数は Python の式 \samp{\var{o}.\var{attr_name}}
と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{int}{PyObject_SetAttrString}{PyObject *o,
                                               const char *attr_name, PyObject *v}
オブジェクト \var{o} の\var{attr_name} という名の属性に、値
\var{v} を設定します。失敗すると \code{-1} を返します。
この関数は Python の式 \samp{\var{o}.\var{attr_name} = \var{v}}
と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{int}{PyObject_SetAttr}{PyObject *o,
                                         PyObject *attr_name, PyObject *v}
オブジェクト \var{o} の\var{attr_name} という名の属性に、値
\var{v} を設定します。失敗すると \code{-1} を返します。
この関数は Python の式 \samp{\var{o}.\var{attr_name} = \var{v}}
と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{int}{PyObject_DelAttrString}{PyObject *o, const char *attr_name}
オブジェクト \var{o} の\var{attr_name} という名の属性を削除します。
失敗すると \code{-1} を返します。
この関数は Python の文 \samp{del \var{o}.\var{attr_name}}
と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{int}{PyObject_DelAttr}{PyObject *o, PyObject *attr_name}
オブジェクト \var{o} の\var{attr_name} という名の属性を削除します。
失敗すると \code{-1} を返します。
この関数は Python の文 \samp{del \var{o}.\var{attr_name}}
と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyObject_RichCompare}{PyObject *o1,
                                                   PyObject *o2, int opid}
\var{o1} と \var{o2} を \var{opid} に指定した演算によって比較します。
\var{opid} は
  \constant{Py_LT},
  \constant{Py_LE},
  \constant{Py_EQ},
  \constant{Py_NE},
  \constant{Py_GT}, または
  \constant{Py_GE}, のいずれかでなければならず、それぞれ
  \code{<},
  \code{<=},
  \code{==},
  \code{!=},
  \code{>}, および
  \code{>=} に対応します。
この関数は Python の式 \samp{\var{o1} op \var{o2}} と同じで、
\code{op} が \var{opid} に対応する演算子です。
成功すると比較結果の値を返し失敗すると \NULL{} を返します。
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PyObject_RichCompareBool}{PyObject *o1,
                                                 PyObject *o2, int opid}
\var{o1} と \var{o2} を \var{opid} に指定した演算によって比較します。
\var{opid} は
  \constant{Py_LT},
  \constant{Py_LE},
  \constant{Py_EQ},
  \constant{Py_NE},
  \constant{Py_GT}, または
  \constant{Py_GE}, のいずれかでなければならず、それぞれ
  \code{<},
  \code{<=},
  \code{==},
  \code{!=},
  \code{>}, および
  \code{>=} に対応します。
比較結果が真ならば \code{1} を、偽ならば \code{0} を、
エラーが発生すると \code{-1} を返します。
この関数は Python の式 \samp{\var{o1} op \var{o2}} と同じで、
\code{op} が \var{opid} に対応する演算子です。
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PyObject_Cmp}{PyObject *o1, PyObject *o2, int *result}
\var{o1} と \var{o2} の値を比較します。このとき\var{o1} が比較ルーチンを
持っていればそれを使い、なければ \var{o2} のルーチンを使います。
比較結果は \var{result} に返されます。失敗すると \code{-1} を返します。
Python 文\bifuncindex{cmp} \samp{\var{result} = cmp(\var{o1}, \var{o2})}
と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{int}{PyObject_Compare}{PyObject *o1, PyObject *o2}
\var{o1} と \var{o2} の値を比較します。このとき\var{o1} が比較ルーチンを
持っていればそれを使い、なければ \var{o2} のルーチンを使います。
比較結果は \var{result} に返されます。失敗すると \code{-1} を返します。
Python 文\bifuncindex{cmp} \samp{\var{result} = cmp(\var{o1}, \var{o2})}
と同じです。成功すると比較結果を返します。エラーが生じた場合の
戻り値は未定義です; \cfunction{PyErr_Occurred()} を使ってエラー検出を
行って下さい。Python 式\bifuncindex{cmp} \samp{cmp(\var{o1},  \var{o2})}
と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyObject_Repr}{PyObject *o}
\var{o} の文字列表現を計算します。成功すると文字列表現を返し、
失敗すると \NULL{} を返します。Python 式\samp{repr(\var{o})}
と同じです。この関数は組み込み関数
\function{repr()}\bifuncindex{repr} や逆クオート表記の処理で
呼び出されます。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyObject_Str}{PyObject *o}
\var{o} の文字列表現を計算します。成功すると文字列表現を返し、
失敗すると \NULL{} を返します。Python 式\samp{str(\var{o})}
と同じです。この関数は組み込み関数
\function{str()}\bifuncindex{str} や\keyword{print} 文の処理で
呼び出されます。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyObject_Unicode}{PyObject *o}
\var{o} の Unicode 文字列表現を計算します。成功すると
Unicode 文字列表現を返し失敗すると \NULL{} を返します。
Python 式\samp{unicode(\var{o})} と同じです。この関数は組み込み関数
\function{unicode()}\bifuncindex{unicode} の処理で呼び出されます。
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PyObject_IsInstance}{PyObject *inst, PyObject *cls}
\var{inst} が \var{cls} のインスタンスか、 \var{cls} のサブクラスの
インスタンスの場合に \code{-1} を返し、そうでなければ \code{0} を
返します。エラーの時には \code{-1} を返し、例外をセットします。
\var{cls} がクラスオブジェクトではなく型オブジェクトの場合、
\cfunction{PyObject_IsInstance()} は \var{inst} が\var{cls} で
あるときに \code{1} を返します。\var{cls} をタプルで指定した場合、
\var{cls} に指定した全てのエントリについてチェックを行います。
少なくとも一つのエントリに対するチェックが \code{1} を返せば結果は
\code{1} になり、そうでなければ \code{0} になります。
\var{inst} がクラスインスタンスでなく、かつ \var{cls} が
型オブジェクトでもクラスオブジェクトでもタプルでもない場合、
\var{inst} には \member{__class__} 属性がなくてはなりません ---
この場合、\member{__class__} 属性の値と、\var{cls} の値の間の
クラス関係を、関数の戻り値を決定するのに使います。
  \versionadded{2.1}
  \versionchanged[二つ目の引数にタプルのサポートを追加しました。]{2.2}
\end{cfuncdesc}

サブクラスの決定はかなり正攻法で行いますが、クラスシステムの拡張を
実装する人たちに知っておいて欲しいちょっとした問題点があります。
\class{A} と \class{B} がクラスオブジェクトの場合、 \class{B} が
\class{A} のサブクラスとなるのは、\class{B} が \class{A} を
直接的あるいは間接的に継承 (inherit) している場合です。
両方がクラスオブジェクトでない場合、二つのオブジェクト間の
クラス関係を決めるには、より汎用の機構を使います。
\var{B} が \var{A} のサブクラスであるか調べたとき、\var{A} が
\var{B} と等しければ、\cfunction{PyObject_IsSubclass()} は真を返します。
\var{A} および \var{B} が異なるオブジェクトなら、\var{B} の
\member{__bases__} 属性から深さ優先探索 (depth-first search)で
\var{A} を探索します --- オブジェクトに\member{__bases__} があるだけで、
この決定法を適用する条件を満たしているとみなされます。

\begin{cfuncdesc}{int}{PyObject_IsSubclass}{PyObject *derived,
                                            PyObject *cls}
クラス \var{derived} が \var{cls} と同じクラスか、\var{cls} の導出
クラスの場合に \code{1} を返し、それ以外の場合には \code{0} を
返します。エラーが生じると \code{-1} を返します。 
\var{cls} をタプルで指定した場合、\var{cls} に指定した全てのエントリに
ついてチェックを行います。
少なくとも一つのエントリに対するチェックが \code{1} を返せば結果は
\code{1} になり、そうでなければ \code{0} になります。
\var{derived} または \var{cls} のいずれかが実際のクラスオブジェクト
(あるいはタプル) でない場合、上で述べた汎用アルゴリズムを使います。
  \versionadded{2.1}
  \versionchanged[以前の Python のバージョンは、二つ目の引数に
タプルをサポートしていませんでした]{2.3}
\end{cfuncdesc}


\begin{cfuncdesc}{int}{PyCallable_Check}{PyObject *o}
オブジェクト \var{o} が呼び出し可能オブジェクトかどうか調べます。
オブジェクトが呼び出し可能であるときに \code{1} を返し、
そうでないときには \code{0} を返します。
この関数呼び出しは常に成功します。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyObject_Call}{PyObject *callable_object,
                                            PyObject *args,
                                            PyObject *kw}
呼び出し可能な Python オブジェクト \var{callable_object} を
タプルで指定された引数 \var{args} および辞書で指定された名前つき
引数 (named argument) \var{kw} とともに呼び出します。名前つき引数を
必要としない場合、 \var{kw} を \NULL{} にしてもかまいません。
\var{args} は \NULL{} であってはなりません。引数が全く必要ない場合には
空のタプルを使ってください。
成功すると呼び出し結果として得られたオブジェクトを返し、
失敗すると \NULL{} を返します。
Python の式 \samp{apply(\var{callable_object}, \var{args}, \var{kw})}
あるいは \samp{\var{callable_object}(*\var{args}, **\var{kw})} と同じです。
  \bifuncindex{apply}
  \versionadded{2.2}
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyObject_CallObject}{PyObject *callable_object,
                                                  PyObject *args}
呼び出し可能な Python オブジェクト \var{callable_object} を
タプルで指定された引数 \var{args} とともに呼び出します。  引数を
必要としない場合、 \var{args} を \NULL{} にしてもかまいません。
成功すると呼び出し結果として得られたオブジェクトを返し、
失敗すると \NULL{} を返します。
Python の式 \samp{apply(\var{callable_object}, \var{args})} 
あるいは \samp{\var{callable_object}(*\var{args})} と同じです。
  \bifuncindex{apply}
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PyObject_CallFunction}{PyObject *callable,
                                                    char *format, \moreargs}
呼び出し可能な Python オブジェクト \var{callable_object} を
可変数個の C 引数とともに呼び出します。C 引数は
\cfunction{Py_BuildValue()} 形式のフォーマット文字列を使って記述します。
\var{format} は\NULL にしてもよく、与える引数がないことを表します。
成功すると呼び出し結果として得られたオブジェクトを返し、
失敗すると \NULL{} を返します。
Python の式 \samp{apply(\var{callable}, \var{args})} あるいは \samp{\var{callable}(*\var{args})} と同じです。
もしも、\ctype{PyObject *} args だけを引数に渡す場合は、\cfunction{PyObject_CallFunctionObjArgs}
がより速い方法であることを覚えておいてください。
  \bifuncindex{apply}
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyObject_CallMethod}{PyObject *o,
                                                  char *method, char *format,
                                                  \moreargs}
オブジェクト \var{o} の \var{method} という名前のメソッドを、
可変数個の C 引数とともに呼び出します。C 引数はタプルを生成するような
\cfunction{Py_BuildValue()} 形式のフォーマット文字列を使って記述します。
\var{format} は\NULL にしてもよく、与える引数がないことを表します。
成功すると呼び出し結果として得られたオブジェクトを返し、
失敗すると \NULL{} を返します。
Python の式 \samp{\var{o}.\var{method}(\var{args})} と同じです。
もしも、\ctype{PyObject *} args だけを引数に渡す場合は、\cfunction{PyObject_CallMethodObjArgs}
がより速い方法であることを覚えておいてください。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyObject_CallFunctionObjArgs}{PyObject *callable,
                                                           \moreargs,
                                                           \code{NULL}}

呼び出し可能な Python オブジェクト \var{callable_object} を
可変数個の \ctype{PyObject*} 引数とともに呼び出します。
引数列は末尾に \NULL がついた可変数個のパラメタとして与えます。
成功すると呼び出し結果として得られたオブジェクトを返し
失敗すると \NULL{} を返します。
  \versionadded{2.2}
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyObject_CallMethodObjArgs}{PyObject *o,
                                                         PyObject *name,
                                                         \moreargs,
                                                         \code{NULL}}
オブジェクト \var{o} のメソッドを呼び出します、メソッド名は
Python 文字列オブジェクト\var{name} で与えます。可変数個の
\ctype{PyObject*} 引数と共に呼び出されます.
引数列は末尾に \NULL がついた可変数個のパラメタとして与えます。
成功すると呼び出し結果として得られたオブジェクトを返し
失敗すると \NULL{} を返します。
  \versionadded{2.2}
\end{cfuncdesc}


\begin{cfuncdesc}{long}{PyObject_Hash}{PyObject *o}
オブジェクト \var{o} のハッシュ値を計算して返します。
失敗すると \code{-1} を返します。
Python の式 \samp{hash(\var{o})}\bifuncindex{hash} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{int}{PyObject_IsTrue}{PyObject *o}
\var{o} が真を表すとみなせる場合には \code{1} を、
そうでないときには \code{0} を返します。  
Python の式 \samp{not not \var{o}} と同じです。
失敗すると \code{-1} を返します。
\end{cfuncdesc}


\begin{cfuncdesc}{int}{PyObject_Not}{PyObject *o}
\var{o} が真を表すとみなせる場合には \code{0} を、
そうでないときには \code{1} を返します。  
Python の式 \samp{not \var{o}} と同じです。
失敗すると \code{-1} を返します。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyObject_Type}{PyObject *o}
\var{o} が \NULL でない場合、オブジェクト\var{o} のオブジェクト型に
相当する型オブジェクトを返します。失敗すると \exception{SystemError} 
を送出して \NULL を返します。
Python の式 \code{type(\var{o})}と同じです。\bifuncindex{type} 
この関数は戻り値の参照カウントをインクリメントします。
参照カウントのインクリメントが必要でない限り、広く使われていて
\ctype{PyTypeObject*} 型のポインタを返す表記法
\code{\var{o}->ob_type} の代わりに使う理由は全くありません。
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PyObject_TypeCheck}{PyObject *o, PyTypeObject *type}
オブジェクト \var{o} が、 \var{type} か \var{type} のサブタイプで
あるときに真を返します。どちらのパラメタも \NULL であってはなりません。
  \versionadded{2.2}
\end{cfuncdesc}

\begin{cfuncdesc}{Py_ssize_t}{PyObject_Length}{PyObject *o}
\cfuncline{Py_ssize_t}{PyObject_Size}{PyObject *o}
\var{o} の長さを返します。オブジェクト\var{o} がシーケンス型プロトコルと
マップ型プロトコルの両方を提供している場合、シーケンスとしての長さを
返します。エラーが生じると \code{-1} を返します。
Python の式 \samp{len(\var{o})}と同じです。\bifuncindex{len}
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyObject_GetItem}{PyObject *o, PyObject *key}
成功するとオブジェクト \var{key} に対応する \var{o} の要素を返し、
失敗すると \NULL{} を返します。 
Python の式 \samp{\var{o}[\var{key}]} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{int}{PyObject_SetItem}{PyObject *o,
                                         PyObject *key, PyObject *v}
オブジェクト \var{key} を値 \var{v} に対応付けます。
失敗すると \code{-1} を返します。
Python の文 \samp{\var{o}[\var{key}] = \var{v}} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{int}{PyObject_DelItem}{PyObject *o, PyObject *key}
オブジェクト \var{o} から \var{key} に対する対応付けを削除します。
失敗すると \code{-1} を返します。
 Python の文 \samp{del \var{o}[\var{key}]} と同じです。
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PyObject_AsFileDescriptor}{PyObject *o}
Python オブジェクトからファイル記述子を取り出します。
オブジェクトが整数か長整数なら、その値を返します。
(長)整数でない場合、オブジェクトに \method{fileno()} メソッドがあれば
呼び出します; この場合、 \method{fileno()} メソッドは
整数または長整数をファイル記述子の値として返さなければなりません。
失敗すると \code{-1} を返します。
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PyObject_Dir}{PyObject *o}
この関数は Python の式 \samp{dir(\var{o})} と同じで、
オブジェクトの変数名に割り当てている文字列からなるリスト
(空の場合もあります) を返します。エラーの場合には \NULL{}
を返します。引数を \NULL にすると、Python における\samp{dir()} 
と同様に、現在のローカルな名前を返します; この場合、
アクティブな実行フレームがなければ \NULL{} を返しますが、
\cfunction{PyErr_Occurred()} は偽を返します。
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PyObject_GetIter}{PyObject *o}
Python の式 \samp{iter(\var{o})} と同じです。
引数にとったオブジェクトに対する新たなイテレータか、
オブジェクトがすでにイテレータの場合にはオブジェクト自身を
返します。オブジェクトが反復処理不可能であった場合には
\exception{TypeError} を送出して \NULL{} を返します。
\end{cfuncdesc}


\section{数値型プロトコル (number protocol) \label{number}}

\begin{cfuncdesc}{int}{PyNumber_Check}{PyObject *o}
オブジェクト \var{o} が数値型プロトコルを提供している場合に
\code{1} を返し、そうでないときには偽を返します。
この関数呼び出しは常に成功します。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyNumber_Add}{PyObject *o1, PyObject *o2}
成功すると\var{o1} と \var{o2} を加算した結果を返し、
失敗すると \NULL{} を返します。
Python の式 \samp{\var{o1} + \var{o2}} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyNumber_Subtract}{PyObject *o1, PyObject *o2}
成功すると\var{o1} から \var{o2} を減算した結果を返し、
失敗すると \NULL{} を返します。
Python の式 \samp{\var{o1} - \var{o2}} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyNumber_Multiply}{PyObject *o1, PyObject *o2}
成功すると\var{o1} と \var{o2} を乗算した結果を返し、失敗すると \NULL{} を返します。
Python の式 \samp{\var{o1} * \var{o2}} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyNumber_Divide}{PyObject *o1, PyObject *o2}
成功すると \var{o1} を \var{o2} で除算した結果を返し,
失敗すると \NULL{} を返します。 
Python の式 \samp{\var{o1} / \var{o2}} と同じです。
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PyNumber_FloorDivide}{PyObject *o1, PyObject *o2}
成功すると\var{o1} を \var{o2} で除算した切捨て値を返し、
失敗すると \NULL{} を返します。 
``旧仕様の'' 整数間での除算と同じです。
\versionadded{2.2}
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyNumber_TrueDivide}{PyObject *o1, PyObject *o2}
成功すると、数学的な \var{o1} の \var{o2} による除算値に対する
妥当な近似 (reasonable approximation) を返し、
失敗すると \NULL{} を返します。
全ての実数を 2 を基数として表現するのは不可能なため、二進の浮動小数点数は
``近似値'' しか表現できません。このため、戻り値も近似になります。
この関数に二つの整数を渡した際、浮動小数点の値を返すことがあります。
  \versionadded{2.2}
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyNumber_Remainder}{PyObject *o1, PyObject *o2}
成功すると \var{o1} を \var{o2} で除算した剰余を返し、
失敗すると \NULL{} を返します。
Python の式 \samp{\var{o1} \%\ \var{o2}} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyNumber_Divmod}{PyObject *o1, PyObject *o2}
組み込み関数 \function{divmod()}\bifuncindex{divmod} を参照してください。
失敗すると \NULL{} を返します。
Python の式 \samp{divmod(\var{o1}, \var{o2})} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyNumber_Power}{PyObject *o1,
                                             PyObject *o2, PyObject *o3}
組み込み関数\function{pow()}\bifuncindex{pow} を参照してください。
失敗すると \NULL{} を返します。
Python の式 \samp{pow(\var{o1}, \var{o2}, \var{o3})}と同じです。
\var{o3} はオプションです。
\var{o3} を無視させたいなら、 \cdata{Py_None} を入れてください
(\var{o3} に\NULL{} を渡すと、不正なメモリアクセスを引き起こすことが
あります)。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyNumber_Negative}{PyObject *o}
成功すると\var{o} の符号反転を返し、失敗すると \NULL{} を返します。
Python の式 \samp{-\var{o}} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyNumber_Positive}{PyObject *o}
成功すると \var{o} を返し、失敗すると \NULL{} を返します。
Python の式 \samp{+\var{o}} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyNumber_Absolute}{PyObject *o}
成功すると \var{o} の絶対値を返し、失敗すると \NULL{} を返します。
Python の式 \samp{abs(\var{o})} と同じです。
  \bifuncindex{abs}
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyNumber_Invert}{PyObject *o}
成功すると \var{o} のビット単位反転 (bitwise negation) を返し、
失敗すると \NULL{} を返します。Python の式 \samp{\~\var{o}} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyNumber_Lshift}{PyObject *o1, PyObject *o2}
成功すると \var{o1} を \var{o2} だけ左シフトした結果を返し、
失敗すると \NULL{} を返します。
Python の式 \samp{\var{o1} <\code{<} \var{o2}} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyNumber_Rshift}{PyObject *o1, PyObject *o2}
成功すると \var{o1} を \var{o2} だけ右シフトした結果を返し、
失敗すると \NULL{} を返します。
Python の式 \samp{\var{o1} >\code{>} \var{o2}} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyNumber_And}{PyObject *o1, PyObject *o2}
成功すると \var{o1} と \var{o2} の ``ビット単位論理積 (bitwise and)'' を返し、
失敗すると \NULL{} を返します。
Python の式 \samp{\var{o1} \&\ \var{o2}} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyNumber_Xor}{PyObject *o1, PyObject *o2}
成功すると \var{o1} と \var{o2} の 
``ビット単位排他的論理和 (bitwise exclusive or)'' を返し、
失敗すると \NULL{} を返します。
Python の式 \samp{\var{o1} \textasciicircum{} \var{o2}} と同じです。
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PyNumber_Or}{PyObject *o1, PyObject *o2}
成功すると \var{o1} と \var{o2} の ``ビット単位論理和 (bitwise or)'' を返し
失敗すると \NULL{} を返します。
Python の式 \samp{\var{o1} | \var{o2}} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceAdd}{PyObject *o1, PyObject *o2}
成功すると\var{o1} と \var{o2} を加算した結果を返し、
失敗すると \NULL{} を返します。
\var{o1} が \emph{in-place} 演算をサポートする場合、in-place 演算を
行います。
Python の文 \samp{\var{o1} += \var{o2}} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceSubtract}{PyObject *o1,
                                                       PyObject *o2}
成功すると\var{o1} から \var{o2} を減算した結果を返し、
失敗すると \NULL{} を返します。
\var{o1} が \emph{in-place} 演算をサポートする場合、in-place 演算を
行います。
Python の文 \samp{\var{o1} -= \var{o2}} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceMultiply}{PyObject *o1,
                                                       PyObject *o2}
成功すると\var{o1} と \var{o2} を乗算した結果を返し、
失敗すると \NULL{} を返します。
\var{o1} が \emph{in-place} 演算をサポートする場合、in-place 演算を
行います。
Python の文 \samp{\var{o1} *= \var{o2}} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceDivide}{PyObject *o1,
                                                     PyObject *o2}
成功すると \var{o1} を \var{o2} で除算した結果を返し,
失敗すると \NULL{} を返します。
\var{o1} が \emph{in-place} 演算をサポートする場合、in-place 演算を
行います。
Python の文 \samp{\var{o1} /= \var{o2}} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceFloorDivide}{PyObject *o1,
                                                          PyObject *o2}
成功すると\var{o1} を \var{o2} で除算した切捨て値を返し、
失敗すると \NULL{} を返します。
\var{o1} が \emph{in-place} 演算をサポートする場合、in-place 演算を
行います。
Python の文 \samp{\var{o1} //= \var{o2}} と同じです。
  \versionadded{2.2}
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceTrueDivide}{PyObject *o1,
                                                         PyObject *o2}
成功すると、数学的な \var{o1} の \var{o2} による除算値に対する
妥当な近似 (reasonable approximation) を返し、
失敗すると \NULL{} を返します。
全ての実数を 2 を基数として表現するのは不可能なため、二進の浮動小数点数は
``近似値'' しか表現できません。このため、戻り値も近似になります。
この関数に二つの整数を渡した際、浮動小数点の値を返すことがあります。
\var{o1} が \emph{in-place} 演算をサポートする場合、in-place 演算を
行います。
  \versionadded{2.2}
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceRemainder}{PyObject *o1,
                                                        PyObject *o2}
成功すると \var{o1} を \var{o2} で除算した剰余を返し、
, 失敗すると \NULL{} を返します。
\var{o1} が \emph{in-place} 演算をサポートする場合、in-place 演算を
行います。
Python の文 \samp{\var{o1} \%= \var{o2}} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyNumber_InPlacePower}{PyObject *o1,
                                                    PyObject *o2, PyObject *o3}
組み込み関数\function{pow()}\bifuncindex{pow} を参照してください。
失敗すると \NULL{} を返します。
\var{o1} が \emph{in-place} 演算をサポートする場合、in-place 演算を
行います。
この関数は \var{o3} が \cdata{Py_None} の場合は Python 文
\samp{\var{o1} **= \var{o2}} と同じで、それ以外の場合は
\samp{pow(\var{o1}, \var{o2}, \var{o3})} の in-place 版です。
\var{o3} を無視させたいなら、 \cdata{Py_None} を入れてください
(\var{o3} に\NULL{} を渡すと、不正なメモリアクセスを引き起こすことが
あります)。
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceLshift}{PyObject *o1,
                                                     PyObject *o2}
成功すると \var{o1} を \var{o2} だけ左シフトした結果を返し、
失敗すると \NULL{} を返します。
\var{o1} が \emph{in-place} 演算をサポートする場合、in-place 演算を
行います。
Python の文 \samp{\var{o1} <\code{<=} \var{o2}} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceRshift}{PyObject *o1,
                                                     PyObject *o2}
成功すると \var{o1} を \var{o2} だけ右シフトした結果を返し、
失敗すると \NULL{} を返します。
\var{o1} が \emph{in-place} 演算をサポートする場合、in-place 演算を
行います。
Python の文 \samp{\var{o1} >>= \var{o2}} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceAnd}{PyObject *o1, PyObject *o2}
成功すると \var{o1} と \var{o2} の ``ビット単位論理積 (bitwise and)'' を返し、
失敗すると \NULL{} を返します。 
\var{o1} が \emph{in-place} 演算をサポートする場合、in-place 演算を行います。
Python の文 \samp{\var{o1} \&= \var{o2}} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceXor}{PyObject *o1, PyObject *o2}
成功すると \var{o1} と \var{o2} の ``ビット単位排他的論理和 
(bitwise exclusive or)'' を返し、失敗すると \NULL{} を返します。 
\var{o1} が \emph{in-place} 演算をサポートする場合、in-place 演算を
行います。
Python の文 \samp{\var{o1} \textasciicircum= \var{o2}} と同じです。
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceOr}{PyObject *o1, PyObject *o2}
成功すると \var{o1} と \var{o2} の ``ビット単位論理和 (bitwise or)'' を返し
失敗すると \NULL{} を返します。
\var{o1} が \emph{in-place} 演算をサポートする場合、in-place 演算を
行います。
Python の文 \samp{\var{o1} |= \var{o2}} と同じです。
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PyNumber_Coerce}{PyObject **p1, PyObject **p2}
この関数は\ctype{PyObject*} 型の二つの変数のアドレスを引数にとります。
\code{*\var{p1}} と\code{*\var{p2}} が指すオブジェクトが同じ型の場合、
それぞれの参照カウントをインクリメントして \code{0} (成功) を返します。
オブジェクトを変換して共通の数値型にできる場合、
\code{*p1} と \code{*p2} を変換後の値に置き換えて (参照カウントを
'新しく' して) 、\code{0} を返します。
変換が不可能な場合や、その他何らかのエラーが生じた場合、\code{-1}
(失敗) を返し、参照カウントをインクリメントしません。
\code{PyNumber_Coerce(\&o1, \&o2)} の呼び出しは Python 文
 \samp{\var{o1}, \var{o2} = coerce(\var{o1}, \var{o2})} と同じです。
  \bifuncindex{coerce}
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PyNumber_Int}{PyObject *o}
成功すると\var{o} を整数に変換したものを返し、
失敗すると \NULL{} を返します。 
引数の値が整数の範囲外の場合、長整数を代わりに返します。
Python の式 \samp{int(\var{o})}\bifuncindex{int} と同じです。
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PyNumber_Long}{PyObject *o}
成功すると\var{o} を長整数に変換したものを返し、
失敗すると \NULL{} を返します。  
Python の式 \samp{long(\var{o})}\bifuncindex{long} と同じです。
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PyNumber_Float}{PyObject *o}
成功すると\var{o} を浮動小数点数に変換したものを返し、
失敗すると \NULL{} を返します。  
Python の式 \samp{float(\var{o})}\bifuncindex{float} と同じです。
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PyNumber_Index}{PyObject *o}
\var{o}をPythonのintもしくはlong型に変換し、成功したらその値を、失敗したら
\NULL{}が返され、TypeError例外が送出されます。
\versionadded{2.5}
\end{cfuncdesc}

\begin{cfuncdesc}{Py_ssize_t}{PyNumber_AsSsize_t}{PyObject *o, PyObject *exc}
\var{o}を整数として解釈可能だった場合、Py_ssize_t型の値に変換して返します。
もし\var{o}がPythonのintもしくはlongに変換できたのに、Py_ssize_tへの変換が
\exception{OverflowError}になる場合は、\var{exc}引数で渡された型
(普通は\exception{IndexError}か\exception{OverflowError})
の例外を送出します。
もし、\var{exc}が\NULL{}なら、例外はクリアされて、値が負の場合は\var{PY_SSIZE_T_MIN}へ、
正の場合は\var{PY_SSIZE_T_MAX}へと制限されます。
\versionadded{2.5}
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PyIndex_Check}{PyObject *o}
\var{o}がインデックス整数であるときにTrueを返します。
(tp_as_number構造体のnb_indexスロットが埋まっている場合)
\versionadded{2.5}
\end{cfuncdesc}
 

\section{シーケンス型プロトコル (sequence protocol) \label{sequence}}

\begin{cfuncdesc}{int}{PySequence_Check}{PyObject *o}
オブジェクトがシーケンス型プロトコルを提供している場合に \code{1} を返し、
そうでないときには \code{0} を返します。
この関数呼び出しは常に成功します。
\end{cfuncdesc}

\begin{cfuncdesc}{Py_ssize_t}{PySequence_Size}{PyObject *o}
成功するとシーケンス \var{o} 中のオブジェクトの数を返し、
失敗すると \code{-1} を返します。
シーケンス型プロトコルをサポートしないオブジェクトに対しては、
Python の式 \samp{len(\var{o})}\bifuncindex{len} と同じ
になります。
\end{cfuncdesc}

\begin{cfuncdesc}{Py_ssize_t}{PySequence_Length}{PyObject *o}
\cfunction{PySequence_Size()} の別名です。
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PySequence_Concat}{PyObject *o1, PyObject *o2}
成功すると\var{o1} と \var{o2} の連結 (concatenation) を返し、
失敗すると \NULL{} を返します。
Python の式 \samp{\var{o1} + \var{o2}} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PySequence_Repeat}{PyObject *o, Py_ssize_t count}
成功するとオブジェクト\var{o} の \var{count} 回繰り返しを返し、
失敗すると \NULL{} を返します。
Python の式 \samp{\var{o} * \var{count}} と同じです。
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PySequence_InPlaceConcat}{PyObject *o1,
                                                       PyObject *o2}
成功すると\var{o1} と \var{o2} の連結 (concatenation) を返し、
失敗すると \NULL{} を返します。
\var{o1} が \emph{in-place} 演算をサポートする場合、in-place 演算を
行います。
Python の式 \samp{\var{o1} += \var{o2}} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PySequence_InPlaceRepeat}{PyObject *o, Py_ssize_t count}
成功するとオブジェクト\var{o} の \var{count} 回繰り返しを返し、
失敗すると \NULL{} を返します。
\var{o1} が \emph{in-place} 演算をサポートする場合、in-place 演算を
行います。
Python の式 \samp{\var{o} *= \var{count}} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PySequence_GetItem}{PyObject *o, Py_ssize_t i}
成功すると \var{o} の \var{i} 番目の要素を返し、
失敗すると \NULL{} を返します。
Python の式 \samp{\var{o}[\var{i}]} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PySequence_GetSlice}{PyObject *o, Py_ssize_t i1, Py_ssize_t i2}
成功すると\var{o} の \var{i1} から \var{i2} までの間のスライスを返し、
失敗すると \NULL{} を返します。
Python の式 \samp{\var{o}[\var{i1}:\var{i2}]} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{int}{PySequence_SetItem}{PyObject *o, int Py_ssize_t, PyObject *v}
\var{o} の \var{i} 番目の要素に \var{v} を代入します。
失敗すると \code{-1} を返します。
Python の文 \samp{\var{o}[\var{i}] = \var{v}} と同じです。
この関数は \var{v} への参照を盗み取り\emph{ません}。
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PySequence_DelItem}{PyObject *o, Py_ssize_t i}
\var{o} の \var{i} 番目の要素を削除します。
失敗すると \code{-1} を返します。
Python の文 \samp{del \var{o}[\var{i}]} と同じです。
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PySequence_SetSlice}{PyObject *o, Py_ssize_t i1,
                                            Py_ssize_t i2, PyObject *v}
\var{o} の \var{i1} から \var{i2} までの間のスライスに \var{v}
を代入します。
Python の文 \samp{\var{o}[\var{i1}:\var{i2}] = \var{v}} と同じです。
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PySequence_DelSlice}{PyObject *o, int Py_ssize_t, int Py_ssize_t}
シーケンスオブジェクト \var{o} の \var{i1} から \var{i2} までの間の
スライスを削除します。失敗すると \code{-1} を返します。
Python の文 \samp{del \var{o}[\var{i1}:\var{i2}]} と同じです。
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PySequence_Count}{PyObject *o, PyObject *value}
\var{o} における \var{value} の出現回数、すなわち 
\code{\var{o}[\var{key}] == \var{value}} となる \var{key} の個数を
返します。失敗すると \code{-1} を返します。
Python の式 \samp{\var{o}.count(\var{value})} と同じです。
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PySequence_Contains}{PyObject *o, PyObject *value}
\var{o} に\var{value} が入っているか判定します。
\var{o} のある要素が \var{value} と等価 (equal) ならば\code{1} を
返し、それ以外の場合には \code{0} を返します。
エラーが発生すると \code{-1} を返します。
Python の式 \samp{\var{value} in \var{o}} と同じです。
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PySequence_Index}{PyObject *o, PyObject *value}
\code{\var{o}[\var{i}] == \var{value}} となる最初に見つかったインデクス
\var{i} を返します。
エラーが発生すると \code{-1} を返します。
Python の式 \samp{\var{o}.index(\var{value})} と同じです。
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PySequence_List}{PyObject *o}
任意のシーケンス \var{o} と同じ内容を持つリストオブジェクトを返します。
返されるリストは必ず新しいリストオブジェクトになります。
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o}
任意のシーケンス \var{o} と同じ内容を持つタプルオブジェクトを返します。
失敗したら\NULL{}を返します。
\var{o} がタプルの場合、新たな参照を返します。
それ以外の場合、適切な内容が入ったタプルを構築して返します。
Pythonの式 \samp{tuple(\var{o})} と同じです。
\bifuncindex{tuple}
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PySequence_Fast}{PyObject *o, const char *m}
シーケンス \var{o} がすでにタプルやリストであれば \var{o} を返し、
そうでなければ \var{o} をタプルで返します。
返されるタプルのメンバにアクセスするには
\cfunction{PySequence_Fast_GET_ITEM()} を使ってください。
失敗すると \NULL{} を返します。
オブジェクトがシーケンスでなければ、\var{m} がメッセージテキストに
なっている\exception{TypeError} を送出します。

\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PySequence_Fast_GET_ITEM}{PyObject *o, Py_ssize_t i}
\var{o} が\NULL でなく、\cfunction{PySequence_Fast()} が返した
オブジェクトであり、かつ\var{i} がインデクスの範囲内にあると
仮定して、\var{o} の \var{i} 番目の要素を返します。
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject**}{PySequence_Fast_ITEMS}{PyObject *o}
PyObject ポインタの背後にあるアレイを返します．この関数では，\var{o} は
\cfunction{PySequence_Fast()} の返したオブジェクトであり，
\NULL でないものと仮定しています．
  \versionadded{2.4}  
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PySequence_ITEM}{PyObject *o, Py_ssize_t i}
成功すると the \var{i}th element of \var{o} を返し、
失敗すると \NULL{} を返します。
\cfunction{PySequence_GetItem()} ですが、
\cfunction{PySequence_Check(\var{o})} が真になるかチェックせず、
負のインデクスに対する調整を行いません。
  \versionadded{2.3}
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PySequence_Fast_GET_SIZE}{PyObject *o}
\var{o} が\NULL でなく、\cfunction{PySequence_Fast()} が返した
オブジェクトであると仮定して、\var{o} の長さを返します。
\var{o} のサイズは\cfunction{PySequence_Size()} を呼び出しても
得られますが、\cfunction{PySequence_Fast_GET_SIZE()} の方が
\var{o} をリストかタプルであると仮定して処理するため、より高速です。
\end{cfuncdesc}


\section{マップ型プロトコル (mapping protocol) \label{mapping}}

\begin{cfuncdesc}{int}{PyMapping_Check}{PyObject *o}
オブジェクトがマップ型プロトコルを提供している場合に \code{1} を返し、
そうでないときには \code{0} を返します。
この関数呼び出しは常に成功します。
\end{cfuncdesc}


\begin{cfuncdesc}{Py_ssize_t}{PyMapping_Length}{PyObject *o}
成功するとオブジェクト \var{o} 中のキーの数を返し、
失敗すると \code{-1} を返します。
マップ型プロトコルを提供していないオブジェクトに対しては、
Python の式 \samp{len(\var{o})}\bifuncindex{len} と同じ
になります。
\end{cfuncdesc}


\begin{cfuncdesc}{int}{PyMapping_DelItemString}{PyObject *o, char *key}
オブジェクト \var{o} から \var{key} に関する対応付けを削除します。
失敗すると \code{-1} を返します。
Python の文 \samp{del \var{o}[\var{key}]} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{int}{PyMapping_DelItem}{PyObject *o, PyObject *key}
オブジェクト \var{o} から \var{key} に対する対応付けを削除します。
失敗すると \code{-1} を返します。
Python の文 \samp{del \var{o}[\var{key}]} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{int}{PyMapping_HasKeyString}{PyObject *o, char *key}
成功すると、マップ型オブジェクトがキー \var{key} を持つ場合に
\code{1} を返し、そうでないときには \code{0} を返します。
Python の式 \samp{\var{o}.has_key(\var{key})} と同じです。
この関数呼び出しは常に成功します。
\end{cfuncdesc}


\begin{cfuncdesc}{int}{PyMapping_HasKey}{PyObject *o, PyObject *key}
マップ型オブジェクトがキー \var{key} を持つ場合に \code{1} を返し、
そうでないときには \code{0} を返します。
Python の式 \samp{\var{o}.has_key(\var{key})} と同じです。
この関数呼び出しは常に成功します。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyMapping_Keys}{PyObject *o}
成功するとオブジェクト \var{o} のキーからなるリストを返します。
失敗すると \NULL を返します。
Python の式 \samp{\var{o}.keys()} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyMapping_Values}{PyObject *o}
成功するとオブジェクト \var{o} のキーに対応する値からなるリストを返します。
失敗すると \NULL を返します。
Python の式 \samp{\var{o}.values()} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyMapping_Items}{PyObject *o}
成功するとオブジェクト \var{o} の要素対、すなわちキーと値のペアが
入ったタプルからなるリストを返します。
失敗すると \NULL を返します。
Python の式 \samp{\var{o}.items()} と同じです。
\end{cfuncdesc}


\begin{cfuncdesc}{PyObject*}{PyMapping_GetItemString}{PyObject *o, char *key}
オブジェクト \var{key} に対応する\var{o} の要素を返します。
失敗すると \NULL を返します。
Python の式 \samp{\var{o}[\var{key}]} と同じです。
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PyMapping_SetItemString}{PyObject *o, char *key,
                                                PyObject *v}
オブジェクト\var{o} で \var{key} を値 \var{v} に対応付けます。
失敗すると \code{-1} を返します。
Python の文 \samp{\var{o}[\var{key}] = \var{v}} と同じです。
\end{cfuncdesc}


\section{イテレータプロトコル (iterator protocol) \label{iterator}}

\versionadded{2.2}

イテレータを扱うための固有の関数は二つしかありません。

\begin{cfuncdesc}{int}{PyIter_Check}{PyObject *o}
\var{o} がイテレータプロトコルをサポートする場合に真を返します。
\end{cfuncdesc}

\begin{cfuncdesc}{PyObject*}{PyIter_Next}{PyObject *o}
反復処理 \var{o} における次の値を返します。オブジェクトが
イテレータの場合、この関数は反復処理における次の値を取り出します。
要素が何も残っていない場合には例外がセットされていない状態で \NULL{} を
返します。オブジェクトがイテレータでない場合には \exception{TypeError}
を送出します。要素を取り出す際にエラーが生じると \NULL{} を返し、
発生した例外を送出します。
\end{cfuncdesc}

イテレータの返す要素にわたって反復処理を行うループを書くと、
C のコードは以下のようになるはずです:

\begin{verbatim}
PyObject *iterator = PyObject_GetIter(obj);
PyObject *item;

if (iterator == NULL) {
    /* エラーの伝播処理をここに書く */
}

while (item = PyIter_Next(iterator)) {
    /* 取り出した要素で何らかの処理を行う */
    ...
    /* 終わったら参照を放棄する */
    Py_DECREF(item);
}

Py_DECREF(iterator);

if (PyErr_Occurred()) {
    /* エラーの伝播処理をここに書く */
}
else {
    /* 別の処理を続ける */
}
\end{verbatim}


\section{バッファプロトコル (buffer protocol) \label{abstract-buffer}}

\begin{cfuncdesc}{int}{PyObject_AsCharBuffer}{PyObject *obj,
                                              const char **buffer,
                                              Py_ssize_t *buffer_len}
文字ベースの入力として使える読み出し専用メモリ上の位置へのポインタを
返します。\var{obj} 引数は単一セグメントからなる
文字バッファインタフェースをサポートしていなければなりません。
成功すると \code{0}を返し、\var{buffer} をメモリの位置に、 
\var{buffer_len} をバッファの長さに設定します。エラーの際には 
\code{-1} を返し、\exception{TypeError} をセットします。
  \versionadded{1.6}
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PyObject_AsReadBuffer}{PyObject *obj,
                                              const void **buffer,
                                              Py_ssize_t *buffer_len}
任意のデータを収めた読み出し専用のメモリ上の位置へのポインタを
返します。\var{obj} 引数は単一セグメントからなる読み出し可能
バッファインタフェースをサポートしていなければなりません。
成功すると \code{0}を返し、\var{buffer} をメモリの位置に、 
\var{buffer_len} をバッファの長さに設定します。エラーの際には 
\code{-1} を返し、\exception{TypeError} をセットします。
  \versionadded{1.6}
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PyObject_CheckReadBuffer}{PyObject *o}
\var{o} が単一セグメントからなる読み出し可能バッファインタフェース
をサポートしている場合に \code{1} を返します。それ以外の場合には
\code{0} を返します。
  \versionadded{2.2}
\end{cfuncdesc}

\begin{cfuncdesc}{int}{PyObject_AsWriteBuffer}{PyObject *obj,
                                               void **buffer,
                                               Py_ssize_t *buffer_len}
書き込み可能なメモリ上の位置へのポインタを返します。\var{obj} 
引数は単一セグメントからなる文字バッファインタフェース
をサポートしていなければなりません。成功すると \code{0}を返し、
\var{buffer} をメモリの位置に、 \var{buffer_len} をバッファの
長さに設定します。エラーの際には \code{-1} を返し、
\exception{TypeError} をセットします。
\versionadded{1.6}
\end{cfuncdesc}

