1 .. highlightlang:: c

     2 

     3 .. _sequence:

     4 

     5 Sequence Protocol

     6 =================

     7 

     8 

     9 .. cfunction:: int PySequence_Check(PyObject *o)

    10 

    11    Return ``1`` if the object provides sequence protocol, and ``0`` otherwise.

    12    This function always succeeds.

    13 

    14 

    15 .. cfunction:: Py_ssize_t PySequence_Size(PyObject *o)

    16 

    17    .. index:: builtin: len

    18 

    19    Returns the number of objects in sequence *o* on success, and ``-1`` on failure.

    20    For objects that do not provide sequence protocol, this is equivalent to the

    21    Python expression ``len(o)``.

    22 

    23 

    24 .. cfunction:: Py_ssize_t PySequence_Length(PyObject *o)

    25 

    26    Alternate name for :cfunc:`PySequence_Size`.

    27 

    28 

    29 .. cfunction:: PyObject* PySequence_Concat(PyObject *o1, PyObject *o2)

    30 

    31    Return the concatenation of *o1* and *o2* on success, and *NULL* on failure.

    32    This is the equivalent of the Python expression ``o1 + o2``.

    33 

    34 

    35 .. cfunction:: PyObject* PySequence_Repeat(PyObject *o, Py_ssize_t count)

    36 

    37    Return the result of repeating sequence object *o* *count* times, or *NULL* on

    38    failure.  This is the equivalent of the Python expression ``o * count``.

    39 

    40 

    41 .. cfunction:: PyObject* PySequence_InPlaceConcat(PyObject *o1, PyObject *o2)

    42 

    43    Return the concatenation of *o1* and *o2* on success, and *NULL* on failure.

    44    The operation is done *in-place* when *o1* supports it.  This is the equivalent

    45    of the Python expression ``o1 += o2``.

    46 

    47 

    48 .. cfunction:: PyObject* PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count)

    49 

    50    Return the result of repeating sequence object *o* *count* times, or *NULL* on

    51    failure.  The operation is done *in-place* when *o* supports it.  This is the

    52    equivalent of the Python expression ``o *= count``.

    53 

    54 

    55 .. cfunction:: PyObject* PySequence_GetItem(PyObject *o, Py_ssize_t i)

    56 

    57    Return the *i*th element of *o*, or *NULL* on failure. This is the equivalent of

    58    the Python expression ``o[i]``.

    59 

    60 

    61 .. cfunction:: PyObject* PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)

    62 

    63    Return the slice of sequence object *o* between *i1* and *i2*, or *NULL* on

    64    failure. This is the equivalent of the Python expression ``o[i1:i2]``.

    65 

    66 

    67 .. cfunction:: int PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v)

    68 

    69    Assign object *v* to the *i*th element of *o*.  Returns ``-1`` on failure.  This

    70    is the equivalent of the Python statement ``o[i] = v``.  This function *does

    71    not* steal a reference to *v*.

    72 

    73 

    74 .. cfunction:: int PySequence_DelItem(PyObject *o, Py_ssize_t i)

    75 

    76    Delete the *i*th element of object *o*.  Returns ``-1`` on failure.  This is the

    77    equivalent of the Python statement ``del o[i]``.

    78 

    79 

    80 .. cfunction:: int PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2, PyObject *v)

    81 

    82    Assign the sequence object *v* to the slice in sequence object *o* from *i1* to

    83    *i2*.  This is the equivalent of the Python statement ``o[i1:i2] = v``.

    84 

    85 

    86 .. cfunction:: int PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)

    87 

    88    Delete the slice in sequence object *o* from *i1* to *i2*.  Returns ``-1`` on

    89    failure.  This is the equivalent of the Python statement ``del o[i1:i2]``.

    90 

    91 

    92 .. cfunction:: Py_ssize_t PySequence_Count(PyObject *o, PyObject *value)

    93 

    94    Return the number of occurrences of *value* in *o*, that is, return the number

    95    of keys for which ``o[key] == value``.  On failure, return ``-1``.  This is

    96    equivalent to the Python expression ``o.count(value)``.

    97 

    98 

    99 .. cfunction:: int PySequence_Contains(PyObject *o, PyObject *value)

   100 

   101    Determine if *o* contains *value*.  If an item in *o* is equal to *value*,

   102    return ``1``, otherwise return ``0``. On error, return ``-1``.  This is

   103    equivalent to the Python expression ``value in o``.

   104 

   105 

   106 .. cfunction:: Py_ssize_t PySequence_Index(PyObject *o, PyObject *value)

   107 

   108    Return the first index *i* for which ``o[i] == value``.  On error, return

   109    ``-1``.    This is equivalent to the Python expression ``o.index(value)``.

   110 

   111 

   112 .. cfunction:: PyObject* PySequence_List(PyObject *o)

   113 

   114    Return a list object with the same contents as the arbitrary sequence *o*.  The

   115    returned list is guaranteed to be new.

   116 

   117 

   118 .. cfunction:: PyObject* PySequence_Tuple(PyObject *o)

   119 

   120    .. index:: builtin: tuple

   121 

   122    Return a tuple object with the same contents as the arbitrary sequence *o* or

   123    *NULL* on failure.  If *o* is a tuple, a new reference will be returned,

   124    otherwise a tuple will be constructed with the appropriate contents.  This is

   125    equivalent to the Python expression ``tuple(o)``.

   126 

   127 

   128 .. cfunction:: PyObject* PySequence_Fast(PyObject *o, const char *m)

   129 

   130    Returns the sequence *o* as a tuple, unless it is already a tuple or list, in

   131    which case *o* is returned.  Use :cfunc:`PySequence_Fast_GET_ITEM` to access the

   132    members of the result.  Returns *NULL* on failure.  If the object is not a

   133    sequence, raises :exc:`TypeError` with *m* as the message text.

   134 

   135 

   136 .. cfunction:: PyObject* PySequence_Fast_GET_ITEM(PyObject *o, Py_ssize_t i)

   137 

   138    Return the *i*th element of *o*, assuming that *o* was returned by

   139    :cfunc:`PySequence_Fast`, *o* is not *NULL*, and that *i* is within bounds.

   140 

   141 

   142 .. cfunction:: PyObject** PySequence_Fast_ITEMS(PyObject *o)

   143 

   144    Return the underlying array of PyObject pointers.  Assumes that *o* was returned

   145    by :cfunc:`PySequence_Fast` and *o* is not *NULL*.

   146    

   147    Note, if a list gets resized, the reallocation may relocate the items array.

   148    So, only use the underlying array pointer in contexts where the sequence 

   149    cannot change.

   150 

   151    .. versionadded:: 2.4

   152 

   153 

   154 .. cfunction:: PyObject* PySequence_ITEM(PyObject *o, Py_ssize_t i)

   155 

   156    Return the *i*th element of *o* or *NULL* on failure. Macro form of

   157    :cfunc:`PySequence_GetItem` but without checking that

   158    :cfunc:`PySequence_Check(o)` is true and without adjustment for negative

   159    indices.

   160 

   161    .. versionadded:: 2.3

   162 

   163 

   164 .. cfunction:: Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o)

   165 

   166    Returns the length of *o*, assuming that *o* was returned by

   167    :cfunc:`PySequence_Fast` and that *o* is not *NULL*.  The size can also be

   168    gotten by calling :cfunc:`PySequence_Size` on *o*, but

   169    :cfunc:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* is a list

   170    or tuple.