mirror of https://github.com/python/cpython
Reformat prior to editing.
This commit is contained in:
Jeroen Ruigrok van der Werven
parent
5d98ec76bb
commit
c42c099436
|
|
@ -19,8 +19,9 @@ Dictionary Objects
|
|||
single: DictType (in module types)
|
||||
single: DictionaryType (in module types)
|
||||
|
||||
This instance of :ctype:`PyTypeObject` represents the Python dictionary type.
|
||||
This is exposed to Python programs as ``dict`` and ``types.DictType``.
|
||||
This instance of :ctype:`PyTypeObject` represents the Python dictionary
|
||||
type. This is exposed to Python programs as ``dict`` and
|
||||
``types.DictType``.
|
||||
|
||||
|
||||
.. cfunction:: int PyDict_Check(PyObject *p)
|
||||
|
|
@ -34,8 +35,8 @@ Dictionary Objects
|
|||
|
||||
.. cfunction:: int PyDict_CheckExact(PyObject *p)
|
||||
|
||||
Return true if *p* is a dict object, but not an instance of a subtype of the
|
||||
dict type.
|
||||
Return true if *p* is a dict object, but not an instance of a subtype of
|
||||
the dict type.
|
||||
|
||||
.. versionadded:: 2.4
|
||||
|
||||
|
|
@ -47,9 +48,9 @@ Dictionary Objects
|
|||
|
||||
.. cfunction:: PyObject* PyDictProxy_New(PyObject *dict)
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
.. versionadded:: 2.2
|
||||
|
||||
|
|
@ -61,9 +62,9 @@ Dictionary Objects
|
|||
|
||||
.. cfunction:: int PyDict_Contains(PyObject *p, PyObject *key)
|
||||
|
||||
Determine if dictionary *p* contains *key*. If an item in *p* is matches *key*,
|
||||
return ``1``, otherwise return ``0``. On error, return ``-1``. This is
|
||||
equivalent to the Python expression ``key in p``.
|
||||
Determine if dictionary *p* contains *key*. If an item in *p* is matches
|
||||
*key*, return ``1``, otherwise return ``0``. On error, return ``-1``.
|
||||
This is equivalent to the Python expression ``key in p``.
|
||||
|
||||
.. versionadded:: 2.4
|
||||
|
||||
|
|
@ -78,24 +79,25 @@ Dictionary Objects
|
|||
.. cfunction:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)
|
||||
|
||||
Insert *value* into the dictionary *p* with a key of *key*. *key* must be
|
||||
:term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return ``0``
|
||||
on success or ``-1`` on failure.
|
||||
:term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return
|
||||
``0`` on success or ``-1`` on failure.
|
||||
|
||||
|
||||
.. cfunction:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
|
||||
|
||||
.. index:: single: PyString_FromString()
|
||||
|
||||
Insert *value* into the dictionary *p* using *key* as a key. *key* should be a
|
||||
:ctype:`char\*`. The key object is created using ``PyString_FromString(key)``.
|
||||
Return ``0`` on success or ``-1`` on failure.
|
||||
Insert *value* into the dictionary *p* using *key* as a key. *key* should
|
||||
be a :ctype:`char\*`. The key object is created using
|
||||
``PyString_FromString(key)``. Return ``0`` on success or ``-1`` on
|
||||
failure.
|
||||
|
||||
|
||||
.. cfunction:: int PyDict_DelItem(PyObject *p, PyObject *key)
|
||||
|
||||
Remove the entry in dictionary *p* with key *key*. *key* must be hashable; if it
|
||||
isn't, :exc:`TypeError` is raised. Return ``0`` on success or ``-1`` on
|
||||
failure.
|
||||
Remove the entry in dictionary *p* with key *key*. *key* must be hashable;
|
||||
if it isn't, :exc:`TypeError` is raised. Return ``0`` on success or ``-1``
|
||||
on failure.
|
||||
|
||||
|
||||
.. cfunction:: int PyDict_DelItemString(PyObject *p, char *key)
|
||||
|
|
@ -106,8 +108,8 @@ Dictionary Objects
|
|||
|
||||
.. cfunction:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key)
|
||||
|
||||
Return the object from dictionary *p* which has a key *key*. Return *NULL* if
|
||||
the key *key* is not present, but *without* setting an exception.
|
||||
Return the object from dictionary *p* which has a key *key*. Return *NULL*
|
||||
if the key *key* is not present, but *without* setting an exception.
|
||||
|
||||
|
||||
.. cfunction:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
|
||||
|
|
@ -118,41 +120,42 @@ Dictionary Objects
|
|||
|
||||
.. cfunction:: PyObject* PyDict_Items(PyObject *p)
|
||||
|
||||
Return a :ctype:`PyListObject` containing all the items from the dictionary, as
|
||||
in the dictionary method :meth:`dict.items`.
|
||||
Return a :ctype:`PyListObject` containing all the items from the
|
||||
dictionary, as in the dictionary method :meth:`dict.items`.
|
||||
|
||||
|
||||
.. cfunction:: PyObject* PyDict_Keys(PyObject *p)
|
||||
|
||||
Return a :ctype:`PyListObject` containing all the keys from the dictionary, as
|
||||
in the dictionary method :meth:`dict.keys`.
|
||||
Return a :ctype:`PyListObject` containing all the keys from the dictionary,
|
||||
as in the dictionary method :meth:`dict.keys`.
|
||||
|
||||
|
||||
.. cfunction:: PyObject* PyDict_Values(PyObject *p)
|
||||
|
||||
Return a :ctype:`PyListObject` containing all the values from the dictionary
|
||||
*p*, as in the dictionary method :meth:`dict.values`.
|
||||
Return a :ctype:`PyListObject` containing all the values from the
|
||||
dictionary *p*, as in the dictionary method :meth:`dict.values`.
|
||||
|
||||
|
||||
.. cfunction:: Py_ssize_t PyDict_Size(PyObject *p)
|
||||
|
||||
.. index:: builtin: len
|
||||
|
||||
Return the number of items in the dictionary. This is equivalent to ``len(p)``
|
||||
on a dictionary.
|
||||
Return the number of items in the dictionary. This is equivalent to
|
||||
``len(p)`` on a dictionary.
|
||||
|
||||
|
||||
.. cfunction:: int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
|
||||
|
||||
Iterate over all key-value pairs in the dictionary *p*. The :ctype:`int`
|
||||
referred to by *ppos* must be initialized to ``0`` prior to the first call to
|
||||
this function to start the iteration; the function returns true for each pair in
|
||||
the dictionary, and false once all pairs have been reported. The parameters
|
||||
*pkey* and *pvalue* should either point to :ctype:`PyObject\*` variables that
|
||||
will be filled in with each key and value, respectively, or may be *NULL*. Any
|
||||
references returned through them are borrowed. *ppos* should not be altered
|
||||
during iteration. Its value represents offsets within the internal dictionary
|
||||
structure, and since the structure is sparse, the offsets are not consecutive.
|
||||
referred to by *ppos* must be initialized to ``0`` prior to the first call
|
||||
to this function to start the iteration; the function returns true for each
|
||||
pair in the dictionary, and false once all pairs have been reported. The
|
||||
parameters *pkey* and *pvalue* should either point to :ctype:`PyObject\*`
|
||||
variables that will be filled in with each key and value, respectively, or
|
||||
may be *NULL*. Any references returned through them are borrowed. *ppos*
|
||||
should not be altered during iteration. Its value represents offsets within
|
||||
the internal dictionary structure, and since the structure is sparse, the
|
||||
offsets are not consecutive.
|
||||
|
||||
For example::
|
||||
|
||||
|
|
@ -164,9 +167,10 @@ Dictionary Objects
|
|||
...
|
||||
}
|
||||
|
||||
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::
|
||||
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;
|
||||
|
|
@ -186,12 +190,12 @@ Dictionary Objects
|
|||
|
||||
.. cfunction:: int PyDict_Merge(PyObject *a, PyObject *b, int override)
|
||||
|
||||
Iterate over mapping object *b* adding key-value pairs to dictionary *a*. *b*
|
||||
may be a dictionary, or any object supporting :func:`PyMapping_Keys` and
|
||||
:func:`PyObject_GetItem`. If *override* is true, existing pairs in *a* will be
|
||||
replaced if a matching key is found in *b*, otherwise pairs will only be added
|
||||
if there is not a matching key in *a*. Return ``0`` on success or ``-1`` if an
|
||||
exception was raised.
|
||||
Iterate over mapping object *b* adding key-value pairs to dictionary *a*.
|
||||
*b* may be a dictionary, or any object supporting :func:`PyMapping_Keys`
|
||||
and :func:`PyObject_GetItem`. If *override* is true, existing pairs in *a*
|
||||
will be replaced if a matching key is found in *b*, otherwise pairs will
|
||||
only be added if there is not a matching key in *a*. Return ``0`` on
|
||||
success or ``-1`` if an exception was raised.
|
||||
|
||||
.. versionadded:: 2.2
|
||||
|
||||
|
|
@ -206,11 +210,12 @@ Dictionary Objects
|
|||
|
||||
.. cfunction:: int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)
|
||||
|
||||
Update or merge into dictionary *a*, from the key-value pairs in *seq2*. *seq2*
|
||||
must be an iterable object producing iterable objects of length 2, viewed as
|
||||
key-value pairs. In case of duplicate keys, the last wins if *override* is
|
||||
true, else the first wins. Return ``0`` on success or ``-1`` if an exception was
|
||||
raised. Equivalent Python (except for the return value)::
|
||||
Update or merge into dictionary *a*, from the key-value pairs in *seq2*.
|
||||
*seq2* must be an iterable object producing iterable objects of length 2,
|
||||
viewed as key-value pairs. In case of duplicate keys, the last wins if
|
||||
*override* is true, else the first wins. Return ``0`` on success or ``-1``
|
||||
if an exception was raised. Equivalent Python (except for the return
|
||||
value)::
|
||||
|
||||
def PyDict_MergeFromSeq2(a, seq2, override):
|
||||
for key, value in seq2:
|
||||
|
|
|
|||
Loading…
Reference in New Issue