summaryrefslogtreecommitdiffstats
path: root/Doc/c-api/sequence.rst
blob: 359bf6dbc70f8f84e6d0b65833a8d5daa6c2c821 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
.. highlightlang:: c

.. _sequence:

Sequence Protocol
=================


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

   Return ``1`` if the object provides sequence protocol, and ``0`` otherwise.
   This function always succeeds.


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

   .. index:: builtin: len

   Returns the number of objects in sequence *o* on success, and ``-1`` on failure.
   For objects that do not provide sequence protocol, this is equivalent to the
   Python expression ``len(o)``.


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

   Alternate name for :cfunc:`PySequence_Size`.


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

   Return the concatenation of *o1* and *o2* on success, and *NULL* on failure.
   This is the equivalent of the Python expression ``o1 + o2``.


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

   Return the result of repeating sequence object *o* *count* times, or *NULL* on
   failure.  This is the equivalent of the Python expression ``o * count``.


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

   Return the concatenation of *o1* and *o2* on success, and *NULL* on failure.
   The operation is done *in-place* when *o1* supports it.  This is the equivalent
   of the Python expression ``o1 += o2``.


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

   Return the result of repeating sequence object *o* *count* times, or *NULL* on
   failure.  The operation is done *in-place* when *o* supports it.  This is the
   equivalent of the Python expression ``o *= count``.


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

   Return the *i*th element of *o*, or *NULL* on failure. This is the equivalent of
   the Python expression ``o[i]``.


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

   Return the slice of sequence object *o* between *i1* and *i2*, or *NULL* on
   failure. This is the equivalent of the Python expression ``o[i1:i2]``.


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

   Assign object *v* to the *i*th element of *o*.  Returns ``-1`` on failure.  This
   is the equivalent of the Python statement ``o[i] = v``.  This function *does
   not* steal a reference to *v*.


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

   Delete the *i*th element of object *o*.  Returns ``-1`` on failure.  This is the
   equivalent of the Python statement ``del o[i]``.


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

   Assign the sequence object *v* to the slice in sequence object *o* from *i1* to
   *i2*.  This is the equivalent of the Python statement ``o[i1:i2] = v``.


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

   Delete the slice in sequence object *o* from *i1* to *i2*.  Returns ``-1`` on
   failure.  This is the equivalent of the Python statement ``del o[i1:i2]``.


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

   Return the number of occurrences of *value* in *o*, that is, return the number
   of keys for which ``o[key] == value``.  On failure, return ``-1``.  This is
   equivalent to the Python expression ``o.count(value)``.


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

   Determine if *o* contains *value*.  If an item in *o* is equal to *value*,
   return ``1``, otherwise return ``0``. On error, return ``-1``.  This is
   equivalent to the Python expression ``value in o``.


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

   Return the first index *i* for which ``o[i] == value``.  On error, return
   ``-1``.    This is equivalent to the Python expression ``o.index(value)``.


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

   Return a list object with the same contents as the arbitrary sequence *o*.  The
   returned list is guaranteed to be new.


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

   .. index:: builtin: tuple

   Return a tuple object with the same contents as the arbitrary sequence *o* or
   *NULL* on failure.  If *o* is a tuple, a new reference will be returned,
   otherwise a tuple will be constructed with the appropriate contents.  This is
   equivalent to the Python expression ``tuple(o)``.


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

   Returns the sequence *o* as a tuple, unless it is already a tuple or list, in
   which case *o* is returned.  Use :cfunc:`PySequence_Fast_GET_ITEM` to access the
   members of the result.  Returns *NULL* on failure.  If the object is not a
   sequence, raises :exc:`TypeError` with *m* as the message text.


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

   Return the *i*th element of *o*, assuming that *o* was returned by
   :cfunc:`PySequence_Fast`, *o* is not *NULL*, and that *i* is within bounds.


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

   Return the underlying array of PyObject pointers.  Assumes that *o* was returned
   by :cfunc:`PySequence_Fast` and *o* is not *NULL*.

   .. versionadded:: 2.4


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

   Return the *i*th element of *o* or *NULL* on failure. Macro form of
   :cfunc:`PySequence_GetItem` but without checking that
   :cfunc:`PySequence_Check(o)` is true and without adjustment for negative
   indices.

   .. versionadded:: 2.3


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

   Returns the length of *o*, assuming that *o* was returned by
   :cfunc:`PySequence_Fast` and that *o* is not *NULL*.  The size can also be
   gotten by calling :cfunc:`PySequence_Size` on *o*, but
   :cfunc:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* is a list
   or tuple.