Objeto Set
**********

Esta seção detalha a API pública para os objetos "set" e "frozenset".
Qualquer funcionalidade não listada abaixo é melhor acessada usando o
protocolo de objeto abstrato (incluindo "PyObject_CallMethod()",
"PyObject_RichCompareBool()", "PyObject_Hash()", "PyObject_Repr()",
"PyObject_IsTrue()", "PyObject_Print()", and "PyObject_GetIter()") ou
o protocolo abstrato de número (incluindo "PyNumber_And()",
"PyNumber_Subtract()", "PyNumber_Or()", "PyNumber_Xor()",
"PyNumber_InPlaceAnd()", "PyNumber_InPlaceSubtract()",
"PyNumber_InPlaceOr()" e "PyNumber_InPlaceXor()").

PySetObject

   Este subtipo de "PyObject" é usado para manter os dados internos
   para ambos os objetos "set" e "frozenset". É como um "PyDictObject"
   em que tem um tamanho fixo para conjuntos pequenos (muito parecido
   com o armazenamento de tupla) e apontará para um bloco de memória
   de tamanho variável separado para conjuntos de tamanho médio e
   grande (muito parecido com lista armazenamento). Nenhum dos campos
   desta estrutura deve ser considerado público e está sujeito a
   alterações. Todo o acesso deve ser feito por meio da API
   documentada, em vez de manipular os valores na estrutura.

PyTypeObject PySet_Type

   Essa é uma instância de "PyTypeObject" representando a classe
   Python do tipo *set*

PyTypeObject PyFrozenSet_Type

   Esta é uma instância de "PyTypeObject" representando o tipo Python
   "frozenset".

As macros de verificação de tipo a seguir funcionam em ponteiros para
qualquer objeto Python. Da mesma forma, as funções construtoras
funcionam com qualquer objeto Python iterável.

int PySet_Check(PyObject *p)

   Retorna verdadeiro se *p* for um objeto "set" ou uma instância de
   um subtipo.

int PyFrozenSet_Check(PyObject *p)

   Retorna verdadeiro se *p* for um objeto "frozenset" ou uma
   instância de um subtipo.

int PyAnySet_Check(PyObject *p)

   Retorna verdadeiro se *p* for um objeto "set", um objeto
   "frozenset" ou uma instância de um subtipo.

int PyAnySet_CheckExact(PyObject *p)

   Retorna verdadeiro se *p* for um objeto "set" ou um objeto
   "frozenset", mas não uma instância de um subtipo.

int PyFrozenSet_CheckExact(PyObject *p)

   Retorna verdadeiro se *p* for um objeto "frozenset", mas não uma
   instância de um subtipo.

PyObject* PySet_New(PyObject *iterable)
    *Return value: New reference.*

   Return a new "set" containing objects returned by the *iterable*.
   The *iterable* may be *NULL* to create a new empty set.  Return the
   new set on success or *NULL* on failure.  Raise "TypeError" if
   *iterable* is not actually iterable.  The constructor is also
   useful for copying a set ("c=set(s)").

PyObject* PyFrozenSet_New(PyObject *iterable)
    *Return value: New reference.*

   Return a new "frozenset" containing objects returned by the
   *iterable*. The *iterable* may be *NULL* to create a new empty
   frozenset.  Return the new set on success or *NULL* on failure.
   Raise "TypeError" if *iterable* is not actually iterable.

As seguintes funções e macros estão disponíveis para instâncias de
"set" ou "frozenset" ou instâncias de seus subtipos.

Py_ssize_t PySet_Size(PyObject *anyset)

   Retorna o comprimento de um objeto "set" ou "frozenset".
   Equivalente a "len(anyset)". Levanta um "PyExc_SystemError" se
   *anyset* não for um "set", "frozenset", ou uma instância de um
   subtipo.

Py_ssize_t PySet_GET_SIZE(PyObject *anyset)

   Forma macro de "PySet_Size()" sem verificação de erros.

int PySet_Contains(PyObject *anyset, PyObject *key)

   Retorna "1" se encontrado, "0" se não encontrado, e "-1" se um erro
   é encontrado. Ao contrário do método Python "__contains__()", esta
   função não converte automaticamente conjuntos não hasheáveis em
   frozensets temporários. Levanta um "TypeError" se a *key* não for
   hasheável. Levanta "PyExc_SystemError" se *anyset* não é um "set",
   "frozenset", ou uma instância de um subtipo.

int PySet_Add(PyObject *set, PyObject *key)

   Adiciona *key* a uma instância de "set". Também funciona com
   instâncias de "frozenset" (como "PyTuple_SetItem()", ele pode ser
   usado para preencher os valores de novos conjuntos de congelamentos
   antes que eles sejam expostos a outro código). Retorna "0" em caso
   de sucesso ou "-1" em caso de falha. Levanta um "TypeError" se a
   *key* não for hasheável. Levanta uma "MemoryError" se não houver
   espaço para crescer. Levanta uma "SystemError" se *set* não for uma
   instância de "set" ou seu subtipo.

As seguintes funções estão disponíveis para instâncias de "set" ou
seus subtipos, mas não para instâncias de "frozenset" ou seus
subtipos.

int PySet_Discard(PyObject *set, PyObject *key)

   Retorna "1" se encontrado e removido, "0" se não encontrado
   (nenhuma ação realizada) e "-1" se um erro for encontrado. Não
   levanta "KeyError" para chaves ausentes. Levanta uma "TypeError" se
   a *key* não for hasheável. Ao contrário do método Python
   "discard()", esta função não converte automaticamente conjuntos não
   hasheáveis em frozensets temporários. Levanta "PyExc_SystemError"
   se *set* não é uma instância de "set" ou seu subtipo.

PyObject* PySet_Pop(PyObject *set)
    *Return value: New reference.*

   Return a new reference to an arbitrary object in the *set*, and
   removes the object from the *set*.  Return *NULL* on failure.
   Raise "KeyError" if the set is empty. Raise a "SystemError" if
   *set* is not an instance of "set" or its subtype.

int PySet_Clear(PyObject *set)

   Limpa todos os elementos de um set existente

int PySet_ClearFreeList()

   Limpe a lista livre. Retorna o número total de itens liberados.

   Novo na versão 3.3.
