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

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

PyTypeObject `PyDict_Type`
  この `PyTypeObject` のインスタンスは Python の辞書を表現します。 このオブジェクトは、Python プログラムには `types.DictType` および `types.DictionaryType` として公開されています。

int `PyDict_Check`( | PyObject *p)

  p が辞書型オブジェクトか、辞書型のサブタイプのインスタンス である場合に真を返します。 バージョン2.2 以降で変更された 仕様: サブタイプを引数にとれるようになりました

PyObject* `PyDict_New`( | )

  戻り値: 新たな参照.
  新たな空の辞書を返します。失敗すると `NULL` を返します。

PyObject* `PyDictProxy_New`( | PyObject *dict)

  戻り値: 新たな参照.
  ある辞書型オブジェクトに対して、読み出し専用に制限されたプロキシ オブジェクト (proxy object) を返します。通常、この関数は 動的でないクラス型 (non-dynamic class type) のクラス辞書を 変更させないためにプロキシを作成するために使われます。 バージョン2.2 以降で新規追加された 仕様です。

void `PyDict_Clear`( | PyObject *p)

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

PyObject* `PyDict_Copy`( | PyObject *p)

  戻り値: 新たな参照.
  p と同じキーと値のペアが入った新たな辞書を返します。 バージョン1.6 以降で新規追加された 仕様です。

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

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

int `PyDict_SetItemString`( | PyObject *p, char *key, PyObject *val)

  辞書 p に、 key をキーとして値 value を 挿入します。 key は `char*` 型でなければなりません。 キーオブジェクトは`PyString_FromString(key)` で生成 されます。 成功した場合には `0` を、失敗した場合には `-1` を返します。

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)

  戻り値: 借りた参照.
  辞書p 内で key をキーとするオブジェクトを返します。 キー key が存在しない場合には `NULL` を返しますが、例外を セット しません。

PyObject* `PyDict_GetItemString`( | PyObject *p, char *key)

  戻り値: 借りた参照.
  `PyDict_GetItem()` と同じですが、key は `PyObject*` ではなく `char*` で指定します。

PyObject* `PyDict_Items`( | PyObject *p)

  戻り値: 新たな参照.
  辞書オブジェクトのメソッド `item()` のように、 辞書内の全ての要素対が入った `PyListObject` を返します。 (`items()` については Python ライブラリリファレンス を 参照してください。)

PyObject* `PyDict_Keys`( | PyObject *p)

  戻り値: 新たな参照.
  辞書オブジェクトのメソッド `keys()` のように、 辞書内の全てのキーが入った `PyListObject` を返します。 (`keys()` については Python ライブラリリファレンス を 参照してください。)

PyObject* `PyDict_Values`( | PyObject *p)

  戻り値: 新たな参照.
  辞書オブジェクトのメソッド `values()` のように、 辞書内の全ての値が入った `PyListObject` を返します。 (`values()` については Python ライブラリリファレンス を 参照してください。)

int `PyDict_Size`( | PyObject *p)

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

int `PyDict_Next`( | PyObject *p, int *ppos, PyObject **pkey, PyObject **pvalue)

  辞書 p 内の全てのキー/値のペアにわたる反復処理を行います。 ppos が参照している `int` 型は、この関数で反復処理 を開始する際に、最初に関数を呼び出すよりも前に `0` に 初期化しておかなければなりません; この関数は辞書内の各ペアを 取り上げるごとに真を返し、全てのペアを取り上げたことが分かると 偽を返します。パラメタ pkey および pvalue には、 それぞれ辞書の各々のキーと値を指すポインタか、または `NULL` が入ります。この関数から返される参照はすべて借りた参照になります。

  以下に例を示します:

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

      while (PyDict_Next(self->dict, &pos, &key, &value)) {
          /* 取り出した値で何らかの処理を行う... */
          ...
      }

  反復処理中に辞書 p を変更してはなりません。 (Python 2.1 からは) 辞書を反復処理する際に、キーに対応する値を 変更しても大丈夫になりましたが、キーの集合を変更しないことが 前提です。以下に例を示します:

      PyObject *key, *value;
      int 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);
      }

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)` と同じです。 成功した場合には `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 以降で新規追加された 仕様です。