Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/list.rst @ 54294:dba767bc3155 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
remove mention of old ctypes version
author Benjamin Peterson <benjamin@python.org>
date Sat, 23 May 2009 20:59:09 +0000
parents 7bb1a4cd5ee5
children 0e054c657062
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 .. _listobjects:
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 List Objects
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 .. index:: object: list
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
9
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 .. ctype:: PyListObject
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
12
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
13 This subtype of :ctype:`PyObject` represents a Python list object.
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
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
16 .. cvar:: PyTypeObject PyList_Type
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:: single: ListType (in module types)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
19
53426
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
20 This instance of :ctype:`PyTypeObject` represents the Python list type.
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
21 This is the same object as ``list`` and ``types.ListType`` in the Python
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
22 layer.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
23
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
24
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
25 .. cfunction:: int PyList_Check(PyObject *p)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
26
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
27 Return true if *p* is a list object or an instance of a subtype of the list
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
28 type.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
29
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
30 .. versionchanged:: 2.2
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
31 Allowed subtypes to be accepted.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
32
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 .. cfunction:: int PyList_CheckExact(PyObject *p)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
35
53426
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
36 Return true if *p* is a list object, but not an instance of a subtype of
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
37 the list type.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
38
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
39 .. versionadded:: 2.2
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
40
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
41
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
42 .. cfunction:: PyObject* PyList_New(Py_ssize_t len)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
43
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
44 Return a new list of length *len* on success, or *NULL* on failure.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
45
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
46 .. note::
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
47
53426
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
48 If *length* is greater than zero, the returned list object's items are
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
49 set to ``NULL``. Thus you cannot use abstract API functions such as
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
50 :cfunc:`PySequence_SetItem` or expose the object to Python code before
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
51 setting all items to a real object with :cfunc:`PyList_SetItem`.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
52
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: 44796
diff changeset
53 .. 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: 44796
diff changeset
54 This function used an :ctype:`int` for *size*. 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: 44796
diff changeset
55 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: 44796
diff changeset
56
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
57
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
58 .. cfunction:: Py_ssize_t PyList_Size(PyObject *list)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
59
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
60 .. index:: builtin: len
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
61
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
62 Return the length of the list object in *list*; this is equivalent to
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
63 ``len(list)`` on a list object.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
64
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: 44796
diff changeset
65 .. 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: 44796
diff changeset
66 This function returned an :ctype:`int`. This might require changes in
85cc9512b60c Issue #4129: Belatedly document which C API functions had their argument(s) or
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
67 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: 44796
diff changeset
68
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
69
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
70 .. cfunction:: Py_ssize_t PyList_GET_SIZE(PyObject *list)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
71
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
72 Macro form of :cfunc:`PyList_Size` without error checking.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
73
53427
63286242dd9d Issue #4129: Add a versionchanged notice for a few forgotten entries.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53426
diff changeset
74 .. versionchanged:: 2.5
53429
7bb1a4cd5ee5 Since it's a macro, actually refer to it as such instead of function.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53427
diff changeset
75 This macro returned an :ctype:`int`. This might require changes in your
7bb1a4cd5ee5 Since it's a macro, actually refer to it as such instead of function.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53427
diff changeset
76 code for properly supporting 64-bit systems.
53427
63286242dd9d Issue #4129: Add a versionchanged notice for a few forgotten entries.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53426
diff changeset
77
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
78
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
79 .. cfunction:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
80
53426
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
81 Return the object at position *pos* in the list pointed to by *p*. The
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
82 position must be positive, indexing from the end of the list is not
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
83 supported. If *pos* is out of bounds, return *NULL* and set an
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
84 :exc:`IndexError` exception.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
85
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: 44796
diff changeset
86 .. 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: 44796
diff changeset
87 This function used an :ctype:`int` for *index*. 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: 44796
diff changeset
88 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: 44796
diff changeset
89
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
90
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
91 .. cfunction:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
92
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
93 Macro form of :cfunc:`PyList_GetItem` without error checking.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
94
53427
63286242dd9d Issue #4129: Add a versionchanged notice for a few forgotten entries.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53426
diff changeset
95 .. versionchanged:: 2.5
53429
7bb1a4cd5ee5 Since it's a macro, actually refer to it as such instead of function.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53427
diff changeset
96 This macro used an :ctype:`int` for *i*. This might require changes in
7bb1a4cd5ee5 Since it's a macro, actually refer to it as such instead of function.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53427
diff changeset
97 your code for properly supporting 64-bit systems.
53427
63286242dd9d Issue #4129: Add a versionchanged notice for a few forgotten entries.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53426
diff changeset
98
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
99
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
100 .. cfunction:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
101
53426
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
102 Set the item at index *index* in list to *item*. Return ``0`` on success
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
103 or ``-1`` on failure.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
104
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
105 .. note::
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
106
53426
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
107 This function "steals" a reference to *item* and discards a reference to
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
108 an item already in the list at the affected position.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
109
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: 44796
diff changeset
110 .. 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: 44796
diff changeset
111 This function used an :ctype:`int` for *index*. 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: 44796
diff changeset
112 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: 44796
diff changeset
113
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
114
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
115 .. cfunction:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
116
53426
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
117 Macro form of :cfunc:`PyList_SetItem` without error checking. This is
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
118 normally only used to fill in new lists where there is no previous content.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
119
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
120 .. note::
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
121
53429
7bb1a4cd5ee5 Since it's a macro, actually refer to it as such instead of function.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53427
diff changeset
122 This macro "steals" a reference to *item*, and, unlike
53426
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
123 :cfunc:`PyList_SetItem`, does *not* discard a reference to any item that
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
124 it being replaced; any reference in *list* at position *i* will be
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
125 leaked.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
126
53427
63286242dd9d Issue #4129: Add a versionchanged notice for a few forgotten entries.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53426
diff changeset
127 .. versionchanged:: 2.5
53429
7bb1a4cd5ee5 Since it's a macro, actually refer to it as such instead of function.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53427
diff changeset
128 This macro used an :ctype:`int` for *i*. This might require
53427
63286242dd9d Issue #4129: Add a versionchanged notice for a few forgotten entries.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53426
diff changeset
129 changes in your code for properly supporting 64-bit systems.
63286242dd9d Issue #4129: Add a versionchanged notice for a few forgotten entries.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53426
diff changeset
130
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
131
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
132 .. cfunction:: int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
133
53426
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
134 Insert the item *item* into list *list* in front of index *index*. Return
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
135 ``0`` if successful; return ``-1`` and set an exception if unsuccessful.
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
136 Analogous to ``list.insert(index, item)``.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
137
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: 44796
diff changeset
138 .. 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: 44796
diff changeset
139 This function used an :ctype:`int` for *index*. 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: 44796
diff changeset
140 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: 44796
diff changeset
141
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
142
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
143 .. cfunction:: int PyList_Append(PyObject *list, PyObject *item)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
144
53426
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
145 Append the object *item* at the end of list *list*. Return ``0`` if
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
146 successful; return ``-1`` and set an exception if unsuccessful. Analogous
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
147 to ``list.append(item)``.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
148
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
149
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
150 .. cfunction:: PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
151
53426
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
152 Return a list of the objects in *list* containing the objects *between*
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
153 *low* and *high*. Return *NULL* and set an exception if unsuccessful.
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
154 Analogous to ``list[low:high]``.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
155
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: 44796
diff changeset
156 .. 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: 44796
diff changeset
157 This function used an :ctype:`int` for *low* and *high*. 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: 44796
diff changeset
158 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: 44796
diff changeset
159
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
160
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
161 .. cfunction:: int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
162
53426
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
163 Set the slice of *list* between *low* and *high* to the contents of
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
164 *itemlist*. Analogous to ``list[low:high] = itemlist``. The *itemlist* may
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
165 be *NULL*, indicating the assignment of an empty list (slice deletion).
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
166 Return ``0`` on success, ``-1`` on failure.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
167
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: 44796
diff changeset
168 .. 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: 44796
diff changeset
169 This function used an :ctype:`int` for *low* and *high*. 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: 44796
diff changeset
170 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: 44796
diff changeset
171
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
172
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
173 .. cfunction:: int PyList_Sort(PyObject *list)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
174
53426
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
175 Sort the items of *list* in place. Return ``0`` on success, ``-1`` on
8fba2584f38b Reformat, since I've been busy here anyway.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53414
diff changeset
176 failure. This is equivalent to ``list.sort()``.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
177
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
178
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
179 .. cfunction:: int PyList_Reverse(PyObject *list)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
180
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
181 Reverse the items of *list* in place. Return ``0`` on success, ``-1`` on
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
182 failure. This is the equivalent of ``list.reverse()``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
183
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
184
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
185 .. cfunction:: PyObject* PyList_AsTuple(PyObject *list)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
186
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
187 .. index:: builtin: tuple
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
188
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
189 Return a new tuple object containing the contents of *list*; equivalent to
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
190 ``tuple(list)``.