Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/slice.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 3d07c9b23951
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 .. _slice-objects:
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 Slice 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
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
9 .. cvar:: PyTypeObject PySlice_Type
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 .. index:: single: SliceType (in module types)
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 The type object for slice objects. This is the same as ``slice`` and
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
14 ``types.SliceType``.
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
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
17 .. cfunction:: int PySlice_Check(PyObject *ob)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
18
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
19 Return true if *ob* is a slice object; *ob* must not be *NULL*.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
20
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
21
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
22 .. cfunction:: PyObject* PySlice_New(PyObject *start, PyObject *stop, PyObject *step)
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 Return a new slice object with the given values. The *start*, *stop*, and
53418
179f4593bd3e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
25 *step* parameters are used as the values of the slice object attributes of
179f4593bd3e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
26 the same names. Any of the values may be *NULL*, in which case the
179f4593bd3e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
27 ``None`` will be used for the corresponding attribute. Return *NULL* if
179f4593bd3e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
28 the new object could not be allocated.
44796
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
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
31 .. cfunction:: int PySlice_GetIndices(PySliceObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step)
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 Retrieve the start, stop and step indices from the slice object *slice*,
53418
179f4593bd3e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
34 assuming a sequence of length *length*. Treats indices greater than
179f4593bd3e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
35 *length* as errors.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
36
53418
179f4593bd3e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
37 Returns 0 on success and -1 on error with no exception set (unless one of
179f4593bd3e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
38 the indices was not :const:`None` and failed to be converted to an integer,
179f4593bd3e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
39 in which case -1 is returned with an exception set).
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
40
53418
179f4593bd3e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
41 You probably do not want to use this function. If you want to use slice
179f4593bd3e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
42 objects in versions of Python prior to 2.3, you would probably do well to
179f4593bd3e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
43 incorporate the source of :cfunc:`PySlice_GetIndicesEx`, suitably renamed,
179f4593bd3e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
44 in the source of your extension.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
45
53419
3d07c9b23951 Issue #4129: Document more int -> Py_ssize_t changes.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53418
diff changeset
46 .. versionchanged:: 2.5
3d07c9b23951 Issue #4129: Document more int -> Py_ssize_t changes.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53418
diff changeset
47 This function used an :ctype:`int` type for *length* and an
3d07c9b23951 Issue #4129: Document more int -> Py_ssize_t changes.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53418
diff changeset
48 :ctype:`int *` type for *start*, *stop*, and *step*. This might require
3d07c9b23951 Issue #4129: Document more int -> Py_ssize_t changes.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53418
diff changeset
49 changes in your code for properly supporting 64-bit systems.
3d07c9b23951 Issue #4129: Document more int -> Py_ssize_t changes.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53418
diff changeset
50
44796
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:: int PySlice_GetIndicesEx(PySliceObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step, Py_ssize_t *slicelength)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
53
53418
179f4593bd3e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
54 Usable replacement for :cfunc:`PySlice_GetIndices`. Retrieve the start,
179f4593bd3e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
55 stop, and step indices from the slice object *slice* assuming a sequence of
179f4593bd3e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
56 length *length*, and store the length of the slice in *slicelength*. Out
179f4593bd3e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
57 of bounds indices are clipped in a manner consistent with the handling of
179f4593bd3e Reformat prior to editing.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 44796
diff changeset
58 normal slices.
44796
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 Returns 0 on success and -1 on error with exception set.
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 .. versionadded:: 2.3
53419
3d07c9b23951 Issue #4129: Document more int -> Py_ssize_t changes.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53418
diff changeset
63
3d07c9b23951 Issue #4129: Document more int -> Py_ssize_t changes.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53418
diff changeset
64 .. versionchanged:: 2.5
3d07c9b23951 Issue #4129: Document more int -> Py_ssize_t changes.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53418
diff changeset
65 This function used an :ctype:`int` type for *length* and an
3d07c9b23951 Issue #4129: Document more int -> Py_ssize_t changes.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53418
diff changeset
66 :ctype:`int *` type for *start*, *stop*, *step*, and *slicelength*. This
3d07c9b23951 Issue #4129: Document more int -> Py_ssize_t changes.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53418
diff changeset
67 might require changes in your code for properly supporting 64-bit
3d07c9b23951 Issue #4129: Document more int -> Py_ssize_t changes.
Jeroen Ruigrok van der Werven <asmodai@in-nomine.org>
parents: 53418
diff changeset
68 systems.