辞書オブジェクト (dictionary object)
************************************

PyDictObject

   この "PyObject" のサブタイプは Python の辞書オブジェクトを表現しま
   す。

PyTypeObject PyDict_Type

   This instance of "PyTypeObject" represents the Python dictionary
   type.  This is exposed to Python programs as "dict" and
   "types.DictType".

int PyDict_Check(PyObject *p)

   引数が辞書オブジェクトか辞書型のサブタイプのインスタンスの場合に真
   を返します。

   バージョン 2.2 で変更: Allowed subtypes to be accepted.

int PyDict_CheckExact(PyObject *p)

   *p* が辞書型オブジェクトであり、かつ辞書型のサブクラスのインスタン
   スでない場合に真を返します。

   バージョン 2.4 で追加.

PyObject* PyDict_New()
    *Return value: New reference.*

   空の新たな辞書を返します。失敗すると *NULL* を返します。

PyObject* PyDictProxy_New(PyObject *dict)
    *Return value: New reference.*

   Return a proxy object for a mapping which enforces read-only
   behavior. This is normally used to create a proxy to prevent
   modification of the dictionary for non-dynamic class types.

   バージョン 2.2 で追加.

void PyDict_Clear(PyObject *p)

   現在辞書に入っている全てのキーと値のペアを除去して空にします。

int PyDict_Contains(PyObject *p, PyObject *key)

   辞書 *p* に *key* が入っているか判定します。*p* の要素が *key* に一
   致した場合は "1" を返し、それ以外の場合には "0" を返します。エラー
   の場合 "-1" を返します。この関数は Python の式 "key in p" と等価で
   す。

   バージョン 2.4 で追加.

PyObject* PyDict_Copy(PyObject *p)
    *Return value: New reference.*

   *p* と同じキーと値のペアが入った新たな辞書を返します。

   バージョン 1.6 で追加.

int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)

   辞書 *p* に、 *key* をキーとして値 *value* を挿入します。 *key* は
   ハッシュ可能(*hashable*)でなければなりません; ハッシュ可能でない場
   合、 "TypeError" を送出します。成功した場合には "0" を、失敗した場
   合には "-1" を返します。

int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)

   Insert *value* into the dictionary *p* using *key* as a key. *key*
   should be a "char*".  The key object is created using
   "PyString_FromString(key)".  Return "0" on success or "-1" on
   failure.

int PyDict_DelItem(PyObject *p, PyObject *key)

   辞書 *p* から *key* をキーとするエントリを除去します。 *key* はハッ
   シュ可能でなければなりません;  ハッシュ可能でない場合、 "TypeError"
   を送出します。成功した場合には "0" を、失敗した場合には "-1" を返し
   ます。

int PyDict_DelItemString(PyObject *p, char *key)

   辞書 *p* から文字列 *key* をキーとするエントリを除去します。成功し
   た場合には "0" を、失敗した場合には "-1" を返します。

PyObject* PyDict_GetItem(PyObject *p, PyObject *key)
    *Return value: Borrowed reference.*

   辞書 *p* 内で *key* をキーとするオブジェクトを返します。キー *key*
   が存在しない場合には *NULL* を返しますが、例外をセット *しません*。

PyObject* PyDict_GetItemString(PyObject *p, const char *key)
    *Return value: Borrowed reference.*

   "PyDict_GetItem()" と同じですが、 *key* は "PyObject*" ではなく
   "char*" で指定します。

PyObject* PyDict_Items(PyObject *p)
    *Return value: New reference.*

   Return a "PyListObject" containing all the items from the
   dictionary, as in the dictionary method "dict.items()".

PyObject* PyDict_Keys(PyObject *p)
    *Return value: New reference.*

   Return a "PyListObject" containing all the keys from the
   dictionary, as in the dictionary method "dict.keys()".

PyObject* PyDict_Values(PyObject *p)
    *Return value: New reference.*

   Return a "PyListObject" containing all the values from the
   dictionary *p*, as in the dictionary method "dict.values()".

Py_ssize_t PyDict_Size(PyObject *p)

   辞書内の要素の数を返します。辞書に対して "len(p)" を実行するのと同
   じです。

   バージョン 2.5 で変更: This function returned an "int" type.  This
   might require changes in your code for properly supporting 64-bit
   systems.

int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)

   辞書 *p* 内の全てのキー/値のペアにわたる反復処理を行います。 *ppos*
   が参照している "Py_ssize_t" 型は、この関数で反復処理を開始する際に
   、最初に関数を呼び出すよりも前に "0" に初期化しておかなければなりま
   せん; この関数は辞書内の各ペアを取り上げるごとに真を返し、全てのペ
   アを取り上げたことが分かると偽を返します。パラメタ *pkey* および
   *pvalue* には、それぞれ辞書の各々のキーと値が埋められた "PyObject*"
   変数を指すポインタか、または *NULL* が入ります。この関数から返され
   る参照はすべて借用参照になります。反復処理中に *ppos* を変更しては
   なりません。この値は内部的な辞書構造体のオフセットを表現しており、
   構造体はスパースなので、オフセットの値に一貫性がないためです。

   例えば:

      PyObject *key, *value;
      Py_ssize_t pos = 0;

      while (PyDict_Next(self->dict, &pos, &key, &value)) {
          /* do something interesting with the values... */
          ...
      }

   The dictionary *p* should not be mutated during iteration.  It is
   safe (since Python 2.1) to modify the values of the keys as you
   iterate over the dictionary, but only so long as the set of keys
   does not change.  For example:

      PyObject *key, *value;
      Py_ssize_t pos = 0;

      while (PyDict_Next(self->dict, &pos, &key, &value)) {
          int i = PyInt_AS_LONG(value) + 1;
          PyObject *o = PyInt_FromLong(i);
          if (o == NULL)
              return -1;
          if (PyDict_SetItem(self->dict, key, o) < 0) {
              Py_DECREF(o);
              return -1;
          }
          Py_DECREF(o);
      }

   バージョン 2.5 で変更: This function used an "int *" type for
   *ppos*. This might require changes in your code for properly
   supporting 64-bit systems.

int PyDict_Merge(PyObject *a, PyObject *b, int override)

   マップ型オブジェクト *b* の全ての要素にわたって、反復的にキー/値の
   ペアを辞書 *a* に追加します。 *b* は辞書か、 "PyMapping_Keys()" ま
   たは "PyObject_GetItem()" をサポートする何らかのオブジェクトにでき
   ます。 *override* が真ならば、 *a* のキーと一致するキーが *b* にあ
   る際に、既存のペアを置き換えます。それ以外の場合は、 *b* のキーに一
   致するキーが *a* にないときのみ追加を行います。成功した場合には "0"
   を返し、例外が送出された場合には "-1" を返します。

   バージョン 2.2 で追加.

int PyDict_Update(PyObject *a, PyObject *b)

   C で表せば "PyDict_Merge(a, b, 1)" と同じで、また Python の
   "a.update(b)" と似ていますが、 "PyDict_Update()" は第二引数が 「
   keys」 属性を持たない場合にキー/値ペアのシーケンスを反復することは
   ありません。成功した場合には "0" を返し、例外が送出された場合には
   "-1" を返します。

   バージョン 2.2 で追加.

int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)

   *seq2* 内のキー/値ペアを使って、辞書 *a* の内容を更新したり統合した
   りします。*seq2* は、キー/値のペアとみなせる長さ 2 の反復可能オブジ
   ェクト(iterable object) を生成する反復可能オブジェクトでなければな
   りません。重複するキーが存在する場合、*override* が真ならば先に出現
   したキーを使い、そうでない場合は後に出現したキーを使います。成功し
   た場合には "0" を返し、例外が送出された場合には "-1" を返します。(
   戻り値以外は) 等価な Python コードを書くと、以下のようになります:

      def PyDict_MergeFromSeq2(a, seq2, override):
          for key, value in seq2:
              if override or key not in a:
                  a[key] = value

   バージョン 2.2 で追加.
