Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/sequence.rst @ 65035:87f4b32905df 2.7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Cosmetic fix to use print function.
author Hirokazu Yamamoto <ocean-city@m2.ccsnet.ne.jp>
date Fri, 01 Oct 2010 10:48:47 +0000
parents c62b652251d8
children b36cb4602e21
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 .. highlightlang:: c
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
2
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
3 .. _sequence:
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
4
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 Sequence Protocol
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
6 =================
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
7
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
8
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
9 .. cfunction:: int PySequence_Check(PyObject *o)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
10
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
11 Return ``1`` if the object provides sequence protocol, and ``0`` otherwise.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
12 This function always succeeds.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
13
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
14
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
15 .. cfunction:: Py_ssize_t PySequence_Size(PyObject *o)
53414
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
16 Py_ssize_t PySequence_Length(PyObject *o)
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
17
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
18 .. index:: builtin: len
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
19
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
20 Returns the number of objects in sequence *o* on success, and ``-1`` on failure.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
21 For objects that do not provide sequence protocol, this is equivalent to the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
22 Python expression ``len(o)``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
23
53414
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
24 .. versionchanged:: 2.5
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
25 These functions returned an :ctype:`int` type. This might require
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
26 changes in your code for properly supporting 64-bit systems.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
27
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
28
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
29 .. cfunction:: PyObject* PySequence_Concat(PyObject *o1, PyObject *o2)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
30
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
31 Return the concatenation of *o1* and *o2* on success, and *NULL* on failure.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
32 This is the equivalent of the Python expression ``o1 + o2``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
33
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
34
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
35 .. cfunction:: PyObject* PySequence_Repeat(PyObject *o, Py_ssize_t count)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
36
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
37 Return the result of repeating sequence object *o* *count* times, or *NULL* on
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
38 failure. This is the equivalent of the Python expression ``o * count``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
39
53414
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
40 .. versionchanged:: 2.5
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
41 This function used an :ctype:`int` type for *count*. This might require
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
42 changes in your code for properly supporting 64-bit systems.
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
43
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
44
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
45 .. cfunction:: PyObject* PySequence_InPlaceConcat(PyObject *o1, PyObject *o2)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
46
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
47 Return the concatenation of *o1* and *o2* on success, and *NULL* on failure.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
48 The operation is done *in-place* when *o1* supports it. This is the equivalent
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
49 of the Python expression ``o1 += o2``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
50
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
51
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
52 .. cfunction:: PyObject* PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
53
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
54 Return the result of repeating sequence object *o* *count* times, or *NULL* on
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
55 failure. The operation is done *in-place* when *o* supports it. This is the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
56 equivalent of the Python expression ``o *= count``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
57
53414
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
58 .. versionchanged:: 2.5
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
59 This function used an :ctype:`int` type for *count*. This might require
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
60 changes in your code for properly supporting 64-bit systems.
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
61
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
62
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
63 .. cfunction:: PyObject* PySequence_GetItem(PyObject *o, Py_ssize_t i)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
64
54446
c62b652251d8 Fix some more small markup problems.
Georg Brandl <georg@python.org>
parents: 53435
diff changeset
65 Return the *i*\ th element of *o*, or *NULL* on failure. This is the equivalent of
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
66 the Python expression ``o[i]``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
67
53414
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
68 .. versionchanged:: 2.5
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
69 This function used an :ctype:`int` type for *i*. This might require
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
70 changes in your code for properly supporting 64-bit systems.
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
71
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
72
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
73 .. cfunction:: PyObject* PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
74
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
75 Return the slice of sequence object *o* between *i1* and *i2*, or *NULL* on
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
76 failure. This is the equivalent of the Python expression ``o[i1:i2]``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
77
53414
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
78 .. versionchanged:: 2.5
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
79 This function used an :ctype:`int` type for *i1* and *i2*. This might
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
80 require changes in your code for properly supporting 64-bit systems.
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
81
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
82
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
83 .. cfunction:: int PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
84
54446
c62b652251d8 Fix some more small markup problems.
Georg Brandl <georg@python.org>
parents: 53435
diff changeset
85 Assign object *v* to the *i*\ th element of *o*. Returns ``-1`` on failure. This
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
86 is the equivalent of the Python statement ``o[i] = v``. This function *does
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
87 not* steal a reference to *v*.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
88
53414
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
89 .. versionchanged:: 2.5
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
90 This function used an :ctype:`int` type for *i*. This might require
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
91 changes in your code for properly supporting 64-bit systems.
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
92
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
93
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
94 .. cfunction:: int PySequence_DelItem(PyObject *o, Py_ssize_t i)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
95
54446
c62b652251d8 Fix some more small markup problems.
Georg Brandl <georg@python.org>
parents: 53435
diff changeset
96 Delete the *i*\ th element of object *o*. Returns ``-1`` on failure. This is the
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
97 equivalent of the Python statement ``del o[i]``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
98
53414
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
99 .. versionchanged:: 2.5
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
100 This function used an :ctype:`int` type for *i*. This might require
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
101 changes in your code for properly supporting 64-bit systems.
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
102
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
103
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
104 .. cfunction:: int PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2, PyObject *v)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
105
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
106 Assign the sequence object *v* to the slice in sequence object *o* from *i1* to
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
107 *i2*. This is the equivalent of the Python statement ``o[i1:i2] = v``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
108
53414
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
109 .. versionchanged:: 2.5
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
110 This function used an :ctype:`int` type for *i1* and *i2*. This might
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
111 require changes in your code for properly supporting 64-bit systems.
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
112
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
113
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
114 .. cfunction:: int PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
115
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
116 Delete the slice in sequence object *o* from *i1* to *i2*. Returns ``-1`` on
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
117 failure. This is the equivalent of the Python statement ``del o[i1:i2]``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
118
53414
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
119 .. versionchanged:: 2.5
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
120 This function used an :ctype:`int` type for *i1* and *i2*. This might
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
121 require changes in your code for properly supporting 64-bit systems.
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
122
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
123
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
124 .. cfunction:: Py_ssize_t PySequence_Count(PyObject *o, PyObject *value)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
125
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
126 Return the number of occurrences of *value* in *o*, that is, return the number
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
127 of keys for which ``o[key] == value``. On failure, return ``-1``. This is
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
128 equivalent to the Python expression ``o.count(value)``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
129
53414
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
130 .. versionchanged:: 2.5
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
131 This function returned an :ctype:`int` type. This might require changes
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
132 in your code for properly supporting 64-bit systems.
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
133
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
134
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
135 .. cfunction:: int PySequence_Contains(PyObject *o, PyObject *value)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
136
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
137 Determine if *o* contains *value*. If an item in *o* is equal to *value*,
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
138 return ``1``, otherwise return ``0``. On error, return ``-1``. This is
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
139 equivalent to the Python expression ``value in o``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
140
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
141
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
142 .. cfunction:: Py_ssize_t PySequence_Index(PyObject *o, PyObject *value)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
143
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
144 Return the first index *i* for which ``o[i] == value``. On error, return
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
145 ``-1``. This is equivalent to the Python expression ``o.index(value)``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
146
53414
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
147 .. versionchanged:: 2.5
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
148 This function returned an :ctype:`int` type. This might require changes
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
149 in your code for properly supporting 64-bit systems.
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 50522
diff changeset
150
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
151
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
152 .. cfunction:: PyObject* PySequence_List(PyObject *o)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
153
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
154 Return a list object with the same contents as the arbitrary sequence *o*. The
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
155 returned list is guaranteed to be new.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
156
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
157
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
158 .. cfunction:: PyObject* PySequence_Tuple(PyObject *o)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
159
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
160 .. index:: builtin: tuple
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
161
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
162 Return a tuple object with the same contents as the arbitrary sequence *o* or
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
163 *NULL* on failure. If *o* is a tuple, a new reference will be returned,
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
164 otherwise a tuple will be constructed with the appropriate contents. This is
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
165 equivalent to the Python expression ``tuple(o)``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
166
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
167
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
168 .. cfunction:: PyObject* PySequence_Fast(PyObject *o, const char *m)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
169
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
170 Returns the sequence *o* as a tuple, unless it is already a tuple or list, in
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
171 which case *o* is returned. Use :cfunc:`PySequence_Fast_GET_ITEM` to access the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
172 members of the result. Returns *NULL* on failure. If the object is not a
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
173 sequence, raises :exc:`TypeError` with *m* as the message text.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
174
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
175
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
176 .. cfunction:: PyObject* PySequence_Fast_GET_ITEM(PyObject *o, Py_ssize_t i)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
177
54446
c62b652251d8 Fix some more small markup problems.
Georg Brandl <georg@python.org>
parents: 53435
diff changeset
178 Return the *i*\ th element of *o*, assuming that *o* was returned by
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
179 :cfunc:`PySequence_Fast`, *o* is not *NULL*, and that *i* is within bounds.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
180
53435
12791812788d Issue #4129: int -> Py_ssize_t documentation.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
181 .. versionchanged:: 2.5
12791812788d Issue #4129: int -> Py_ssize_t documentation.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
182 This function used an :ctype:`int` type for *i*. This might require
12791812788d Issue #4129: int -> Py_ssize_t documentation.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
183 changes in your code for properly supporting 64-bit systems.
12791812788d Issue #4129: int -> Py_ssize_t documentation.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
184
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
185
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
186 .. cfunction:: PyObject** PySequence_Fast_ITEMS(PyObject *o)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
187
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
188 Return the underlying array of PyObject pointers. Assumes that *o* was returned
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
189 by :cfunc:`PySequence_Fast` and *o* is not *NULL*.
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 47931
diff changeset
190
47931
e286bd0f4e1b Add cautionary note on the use of PySequence_Fast_ITEMS.
Raymond Hettinger <python@rcn.com>
parents: 44796
diff changeset
191 Note, if a list gets resized, the reallocation may relocate the items array.
50522
ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from
Georg Brandl <georg@python.org>
parents: 47931
diff changeset
192 So, only use the underlying array pointer in contexts where the sequence
47931
e286bd0f4e1b Add cautionary note on the use of PySequence_Fast_ITEMS.
Raymond Hettinger <python@rcn.com>
parents: 44796
diff changeset
193 cannot change.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
194
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
195 .. versionadded:: 2.4
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
196
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
197
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
198 .. cfunction:: PyObject* PySequence_ITEM(PyObject *o, Py_ssize_t i)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
199
54446
c62b652251d8 Fix some more small markup problems.
Georg Brandl <georg@python.org>
parents: 53435
diff changeset
200 Return the *i*\ th element of *o* or *NULL* on failure. Macro form of
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
201 :cfunc:`PySequence_GetItem` but without checking that
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
202 :cfunc:`PySequence_Check(o)` is true and without adjustment for negative
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
203 indices.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
204
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
205 .. versionadded:: 2.3
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
206
53435
12791812788d Issue #4129: int -> Py_ssize_t documentation.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
207 .. versionchanged:: 2.5
12791812788d Issue #4129: int -> Py_ssize_t documentation.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
208 This function used an :ctype:`int` type for *i*. This might require
12791812788d Issue #4129: int -> Py_ssize_t documentation.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
209 changes in your code for properly supporting 64-bit systems.
12791812788d Issue #4129: int -> Py_ssize_t documentation.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
210
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
211
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
212 .. cfunction:: Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
213
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
214 Returns the length of *o*, assuming that *o* was returned by
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
215 :cfunc:`PySequence_Fast` and that *o* is not *NULL*. The size can also be
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
216 gotten by calling :cfunc:`PySequence_Size` on *o*, but
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
217 :cfunc:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* is a list
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
218 or tuple.