Objetos dicionários¶
-
PyTypeObject
PyDict_Type
¶ Esta instância do
PyTypeObject
representa o tipo do dicionário Python. Este é o mesmo objetodict
na camada do Python.
-
int
PyDict_Check
(PyObject *p)¶ Retorna verdadeiro se p é um objeto dicionário ou uma instância de um subtipo do tipo dicionário. Esta função sempre tem sucesso.
-
int
PyDict_CheckExact
(PyObject *p)¶ Retorna verdadeiro se p é um objeto dicionário, mas não uma instância de um subtipo do tipo dicionário. Esta função sempre tem sucesso.
-
PyObject*
PyDict_New
()¶ - Return value: New reference.
Retorna um novo dicionário vazio ou
NULL
em caso de falha.
-
PyObject*
PyDictProxy_New
(PyObject *mapping)¶ - Return value: New reference.
Retorna um objeto
types.MappingProxyType
para um mapeamento que reforça o comportamento somente leitura. Isso normalmente é usado para criar uma visão para evitar a modificação do dicionário para tipos de classes não dinâmicas.
-
int
PyDict_Contains
(PyObject *p, PyObject *key)¶ Determina se o dicionário p contém key. Se um item em p corresponder à key, retorna
1
, caso contrário, retorna0
. Em caso de erro, retorna-1
. Isso é equivalente à expressão Pythonkey in p
.
-
PyObject*
PyDict_Copy
(PyObject *p)¶ - Return value: New reference.
Retorna um novo dicionário que contém o mesmo chave-valor como p.
-
int
PyDict_SetItem
(PyObject *p, PyObject *key, PyObject *val)¶ Insere val no dicionário p com a tecla key. key deve ser hasheável; se não for,
TypeError
será levantada. Retorna0
em caso de sucesso ou-1
em caso de falha. Esta função não rouba uma referência a val.
-
int
PyDict_SetItemString
(PyObject *p, const char *key, PyObject *val)¶ Insere val no dicionário p usando key como uma chave. key deve ser a
const char*
. O objeto chave é criado usandoPyUnicode_FromString(key)
. Retorna0
em caso de sucesso ou-1
em caso de falha. Esta função não rouba uma referência a val.
-
int
PyDict_DelItem
(PyObject *p, PyObject *key)¶ Remove a entrada no dicionário p com a chave key. key deve ser hasheável; se não for,
TypeError
é levantada. Se key não estiver no dicionário,KeyError
é levantada. Retorna0
em caso de sucesso ou-1
em caso de falha.
-
int
PyDict_DelItemString
(PyObject *p, const char *key)¶ Remove a entrada no dicionário p que tem uma chave especificada pela string key. Se key não estiver no dicionário,
KeyError
é levantada. Retorna0
em caso de sucesso ou-1
em caso de falha.
-
PyObject*
PyDict_GetItem
(PyObject *p, PyObject *key)¶ - Return value: Borrowed reference.
Retorna o objeto do dicionário p que possui uma chave key. Retorna
NULL
se a chave key não estiver presente, mas sem definir uma exceção.Observe que as exceções que ocorrem ao chamar os métodos
__hash__()
e__eq__()
serão suprimidas. Para obter o relatório de erros, usePyDict_GetItemWithError()
.
-
PyObject*
PyDict_GetItemWithError
(PyObject *p, PyObject *key)¶ - Return value: Borrowed reference.
Variante de
PyDict_GetItem()
que não suprime exceções. RetornaNULL
com uma exceção definida se uma exceção ocorreu. RetornaNULL
** sem ** uma exceção definida se a chave não estiver presente.
-
PyObject*
PyDict_GetItemString
(PyObject *p, const char *key)¶ - Return value: Borrowed reference.
É o mesmo que
PyDict_GetItem()
, mas key é especificada como umconst char*
, em vez de umPyObject*
.Observe que as exceções que ocorrem ao chamar os métodos
__hash__()
e__eq__()
e criar um objeto string temporário serão suprimidas. Para obter o relatório de erros, usePyDict_GetItemWithError()
.
-
PyObject*
PyDict_SetDefault
(PyObject *p, PyObject *key, PyObject *defaultobj)¶ - Return value: Borrowed reference.
Isso é o mesmo que o
dict.setdefault()
de nível Python. Se presente, ele retorna o valor correspondente a key do dicionário p. Se a chave não estiver no dict, ela será inserida com o valor defaultobj e defaultobj será retornado. Esta função avalia a função hash de key apenas uma vez, em vez de avaliá-la independentemente para a pesquisa e a inserção.Novo na versão 3.4.
-
PyObject*
PyDict_Items
(PyObject *p)¶ - Return value: New reference.
Retorna um
PyListObject
contendo todos os itens do dicionário.
-
PyObject*
PyDict_Keys
(PyObject *p)¶ - Return value: New reference.
Retorna um
PyListObject
contendo todas as chaves do dicionário.
-
PyObject*
PyDict_Values
(PyObject *p)¶ - Return value: New reference.
Retorna um
PyListObject
contendo todos os valores do dicionário p.
-
Py_ssize_t
PyDict_Size
(PyObject *p)¶ Retorna o número de itens no dicionário. Isso é equivalente a
len(p)
em um dicionário.
-
int
PyDict_Next
(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)¶ Itera todos os pares de valores-chave no dicionário p. O
Py_ssize_t
referido por ppos deve ser inicializado para0
antes da primeira chamada para esta função para iniciar a iteração; a função retorna true para cada par no dicionário e false quando todos os pares forem relatados. Os parâmetros pkey e pvalue devem apontar para variáveis dePyObject*
que serão preenchidas com cada chave e valor, respectivamente, ou podem serNULL
. Todas as referências retornadas por meio deles são emprestadas. ppos não deve ser alterado durante a iteração. Seu valor representa deslocamentos dentro da estrutura do dicionário interno e, como a estrutura é esparsa, os deslocamentos não são consecutivos.Por exemplo:
PyObject *key, *value; Py_ssize_t pos = 0; while (PyDict_Next(self->dict, &pos, &key, &value)) { /* do something interesting with the values... */ ... }
O dicionário p não deve sofrer mutação durante a iteração. É seguro modificar os valores das chaves à medida que você itera no dicionário, mas apenas enquanto o conjunto de chaves não mudar. Por exemplo:
PyObject *key, *value; Py_ssize_t pos = 0; while (PyDict_Next(self->dict, &pos, &key, &value)) { long i = PyLong_AsLong(value); if (i == -1 && PyErr_Occurred()) { return -1; } PyObject *o = PyLong_FromLong(i + 1); 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)¶ Itera sobre o objeto de mapeamento b adicionando pares de valores-chave ao dicionário a. b pode ser um dicionário, ou qualquer objeto que suporte
PyMapping_Keys()
ePyObject_GetItem()
. Se override for verdadeiro, os pares existentes em a serão substituídos se uma chave correspondente for encontrada em b, caso contrário, os pares serão adicionados apenas se não houver uma chave correspondente em a. Retorna0
em caso de sucesso ou-1
se uma exceção foi levantada.
-
int
PyDict_Update
(PyObject *a, PyObject *b)¶ É o mesmo que
PyDict_Merge(a, b, 1)
em C, e é semelhante aa.update(b)
em Python, exceto quePyDict_Update()
não cai na iteração em uma sequência de pares de valores de chave se o segundo argumento não tiver o atributo “keys”. Retorna0
em caso de sucesso ou-1
se uma exceção foi levantada.
-
int
PyDict_MergeFromSeq2
(PyObject *a, PyObject *seq2, int override)¶ Atualiza ou mescla no dicionário a, a partir dos pares de chave-valor em seq2. seq2 deve ser um objeto iterável produzindo objetos iteráveis de comprimento 2, vistos como pares chave-valor. No caso de chaves duplicadas, a última vence se override for verdadeiro, caso contrário, a primeira vence. Retorne
0
em caso de sucesso ou-1
se uma exceção foi levantada. Python equivalente (exceto para o valor de retorno):def PyDict_MergeFromSeq2(a, seq2, override): for key, value in seq2: if override or key not in a: a[key] = value