Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/long.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 85cc9512b60c
children 28de83f17d08
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 .. _longobjects:
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 Long Integer 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: long integer
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:: PyLongObject
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 long integer 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 PyLong_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: LongType (in modules types)
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 This instance of :ctype:`PyTypeObject` represents the Python long integer type.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
21 This is the same object as ``long`` and ``types.LongType``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
22
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 .. cfunction:: int PyLong_Check(PyObject *p)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
25
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
26 Return true if its argument is a :ctype:`PyLongObject` or a subtype of
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
27 :ctype:`PyLongObject`.
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 .. versionchanged:: 2.2
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
30 Allowed subtypes to be accepted.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
31
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 .. cfunction:: int PyLong_CheckExact(PyObject *p)
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 Return true if its argument is a :ctype:`PyLongObject`, but not a subtype of
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
36 :ctype:`PyLongObject`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
37
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
38 .. versionadded:: 2.2
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
39
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 .. cfunction:: PyObject* PyLong_FromLong(long v)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
42
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
43 Return a new :ctype:`PyLongObject` object from *v*, or *NULL* on failure.
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
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
46 .. cfunction:: PyObject* PyLong_FromUnsignedLong(unsigned long v)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
47
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
48 Return a new :ctype:`PyLongObject` object from a C :ctype:`unsigned long`, or
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
49 *NULL* on failure.
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
46568
eb2746e8b983 #2691: document PyLong (s)size_t APIs, patch by Alexander Belopolsky.
Georg Brandl <georg@python.org>
parents: 45429
diff changeset
52 .. cfunction:: PyObject* PyLong_FromSsize_t(Py_ssize_t v)
eb2746e8b983 #2691: document PyLong (s)size_t APIs, patch by Alexander Belopolsky.
Georg Brandl <georg@python.org>
parents: 45429
diff changeset
53
eb2746e8b983 #2691: document PyLong (s)size_t APIs, patch by Alexander Belopolsky.
Georg Brandl <georg@python.org>
parents: 45429
diff changeset
54 Return a new :ctype:`PyLongObject` object from a C :ctype:`Py_ssize_t`, or
eb2746e8b983 #2691: document PyLong (s)size_t APIs, patch by Alexander Belopolsky.
Georg Brandl <georg@python.org>
parents: 45429
diff changeset
55 *NULL* on failure.
eb2746e8b983 #2691: document PyLong (s)size_t APIs, patch by Alexander Belopolsky.
Georg Brandl <georg@python.org>
parents: 45429
diff changeset
56
52530
aa7cf3283d6e #5566: fix versionadded from PyLong ssize_t functions.
Georg Brandl <georg@python.org>
parents: 51517
diff changeset
57 .. versionadded:: 2.6
46568
eb2746e8b983 #2691: document PyLong (s)size_t APIs, patch by Alexander Belopolsky.
Georg Brandl <georg@python.org>
parents: 45429
diff changeset
58
eb2746e8b983 #2691: document PyLong (s)size_t APIs, patch by Alexander Belopolsky.
Georg Brandl <georg@python.org>
parents: 45429
diff changeset
59
eb2746e8b983 #2691: document PyLong (s)size_t APIs, patch by Alexander Belopolsky.
Georg Brandl <georg@python.org>
parents: 45429
diff changeset
60 .. cfunction:: PyObject* PyLong_FromSize_t(size_t v)
eb2746e8b983 #2691: document PyLong (s)size_t APIs, patch by Alexander Belopolsky.
Georg Brandl <georg@python.org>
parents: 45429
diff changeset
61
eb2746e8b983 #2691: document PyLong (s)size_t APIs, patch by Alexander Belopolsky.
Georg Brandl <georg@python.org>
parents: 45429
diff changeset
62 Return a new :ctype:`PyLongObject` object from a C :ctype:`size_t`, or
eb2746e8b983 #2691: document PyLong (s)size_t APIs, patch by Alexander Belopolsky.
Georg Brandl <georg@python.org>
parents: 45429
diff changeset
63 *NULL* on failure.
eb2746e8b983 #2691: document PyLong (s)size_t APIs, patch by Alexander Belopolsky.
Georg Brandl <georg@python.org>
parents: 45429
diff changeset
64
52530
aa7cf3283d6e #5566: fix versionadded from PyLong ssize_t functions.
Georg Brandl <georg@python.org>
parents: 51517
diff changeset
65 .. versionadded:: 2.6
46568
eb2746e8b983 #2691: document PyLong (s)size_t APIs, patch by Alexander Belopolsky.
Georg Brandl <georg@python.org>
parents: 45429
diff changeset
66
eb2746e8b983 #2691: document PyLong (s)size_t APIs, patch by Alexander Belopolsky.
Georg Brandl <georg@python.org>
parents: 45429
diff changeset
67
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
68 .. cfunction:: PyObject* PyLong_FromLongLong(PY_LONG_LONG v)
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 Return a new :ctype:`PyLongObject` object from a C :ctype:`long long`, or *NULL*
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
71 on failure.
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
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
74 .. cfunction:: PyObject* PyLong_FromUnsignedLongLong(unsigned PY_LONG_LONG v)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
75
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
76 Return a new :ctype:`PyLongObject` object from a C :ctype:`unsigned long long`,
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
77 or *NULL* on failure.
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
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
80 .. cfunction:: PyObject* PyLong_FromDouble(double v)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
81
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
82 Return a new :ctype:`PyLongObject` object from the integer part of *v*, or
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
83 *NULL* on failure.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
84
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
85
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
86 .. cfunction:: PyObject* PyLong_FromString(char *str, char **pend, int base)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
87
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
88 Return a new :ctype:`PyLongObject` based on the string value in *str*, which is
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
89 interpreted according to the radix in *base*. If *pend* is non-*NULL*,
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
90 ``*pend`` will point to the first character in *str* which follows the
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
91 representation of the number. If *base* is ``0``, the radix will be determined
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
92 based on the leading characters of *str*: if *str* starts with ``'0x'`` or
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
93 ``'0X'``, radix 16 will be used; if *str* starts with ``'0'``, radix 8 will be
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
94 used; otherwise radix 10 will be used. If *base* is not ``0``, it must be
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
95 between ``2`` and ``36``, inclusive. Leading spaces are ignored. If there are
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
96 no digits, :exc:`ValueError` will be raised.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
97
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
98
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
99 .. cfunction:: PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
100
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
101 Convert a sequence of Unicode digits to a Python long integer value. The first
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
102 parameter, *u*, points to the first character of the Unicode string, *length*
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
103 gives the number of characters, and *base* is the radix for the conversion. The
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
104 radix must be in the range [2, 36]; if it is out of range, :exc:`ValueError`
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
105 will be raised.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
106
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
107 .. versionadded:: 1.6
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: 52530
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: 52530
diff changeset
110 This function used an :ctype:`int` for *length*. 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: 52530
diff changeset
111 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: 52530
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:: PyObject* PyLong_FromVoidPtr(void *p)
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 Create a Python integer or long integer from the pointer *p*. The pointer value
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
117 can be retrieved from the resulting value using :cfunc:`PyLong_AsVoidPtr`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
118
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
119 .. versionadded:: 1.5.2
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
120
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
121 .. versionchanged:: 2.5
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
122 If the integer is larger than LONG_MAX, a positive long integer is returned.
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
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
125 .. cfunction:: long PyLong_AsLong(PyObject *pylong)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
126
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
127 .. index::
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
128 single: LONG_MAX
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
129 single: OverflowError (built-in exception)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
130
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
131 Return a C :ctype:`long` representation of the contents of *pylong*. If
46568
eb2746e8b983 #2691: document PyLong (s)size_t APIs, patch by Alexander Belopolsky.
Georg Brandl <georg@python.org>
parents: 45429
diff changeset
132 *pylong* is greater than :const:`LONG_MAX`, an :exc:`OverflowError` is raised
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: 46568
diff changeset
133 and ``-1`` will be returned.
46568
eb2746e8b983 #2691: document PyLong (s)size_t APIs, patch by Alexander Belopolsky.
Georg Brandl <georg@python.org>
parents: 45429
diff changeset
134
eb2746e8b983 #2691: document PyLong (s)size_t APIs, patch by Alexander Belopolsky.
Georg Brandl <georg@python.org>
parents: 45429
diff changeset
135
eb2746e8b983 #2691: document PyLong (s)size_t APIs, patch by Alexander Belopolsky.
Georg Brandl <georg@python.org>
parents: 45429
diff changeset
136 .. cfunction:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)
eb2746e8b983 #2691: document PyLong (s)size_t APIs, patch by Alexander Belopolsky.
Georg Brandl <georg@python.org>
parents: 45429
diff changeset
137
eb2746e8b983 #2691: document PyLong (s)size_t APIs, patch by Alexander Belopolsky.
Georg Brandl <georg@python.org>
parents: 45429
diff changeset
138 .. index::
eb2746e8b983 #2691: document PyLong (s)size_t APIs, patch by Alexander Belopolsky.
Georg Brandl <georg@python.org>
parents: 45429
diff changeset
139 single: PY_SSIZE_T_MAX
eb2746e8b983 #2691: document PyLong (s)size_t APIs, patch by Alexander Belopolsky.
Georg Brandl <georg@python.org>
parents: 45429
diff changeset
140 single: OverflowError (built-in exception)
eb2746e8b983 #2691: document PyLong (s)size_t APIs, patch by Alexander Belopolsky.
Georg Brandl <georg@python.org>
parents: 45429
diff changeset
141
eb2746e8b983 #2691: document PyLong (s)size_t APIs, patch by Alexander Belopolsky.
Georg Brandl <georg@python.org>
parents: 45429
diff changeset
142 Return a C :ctype:`Py_ssize_t` representation of the contents of *pylong*. If
eb2746e8b983 #2691: document PyLong (s)size_t APIs, patch by Alexander Belopolsky.
Georg Brandl <georg@python.org>
parents: 45429
diff changeset
143 *pylong* is greater than :const:`PY_SSIZE_T_MAX`, an :exc:`OverflowError` is raised
eb2746e8b983 #2691: document PyLong (s)size_t APIs, patch by Alexander Belopolsky.
Georg Brandl <georg@python.org>
parents: 45429
diff changeset
144 and ``-1`` will be returned.
eb2746e8b983 #2691: document PyLong (s)size_t APIs, patch by Alexander Belopolsky.
Georg Brandl <georg@python.org>
parents: 45429
diff changeset
145
52530
aa7cf3283d6e #5566: fix versionadded from PyLong ssize_t functions.
Georg Brandl <georg@python.org>
parents: 51517
diff changeset
146 .. versionadded:: 2.6
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
147
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 .. cfunction:: unsigned long PyLong_AsUnsignedLong(PyObject *pylong)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
150
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
151 .. index::
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
152 single: ULONG_MAX
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
153 single: OverflowError (built-in exception)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
154
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
155 Return a C :ctype:`unsigned long` representation of the contents of *pylong*.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
156 If *pylong* is greater than :const:`ULONG_MAX`, an :exc:`OverflowError` is
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
157 raised.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
158
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 .. cfunction:: PY_LONG_LONG PyLong_AsLongLong(PyObject *pylong)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
161
51517
20609fc13a13 Issue #5175: PyLong_AsUnsignedLongLong now raises OverflowError for
Mark Dickinson <dickinsm@gmail.com>
parents: 50522
diff changeset
162 .. index::
20609fc13a13 Issue #5175: PyLong_AsUnsignedLongLong now raises OverflowError for
Mark Dickinson <dickinsm@gmail.com>
parents: 50522
diff changeset
163 single: OverflowError (built-in exception)
20609fc13a13 Issue #5175: PyLong_AsUnsignedLongLong now raises OverflowError for
Mark Dickinson <dickinsm@gmail.com>
parents: 50522
diff changeset
164
20609fc13a13 Issue #5175: PyLong_AsUnsignedLongLong now raises OverflowError for
Mark Dickinson <dickinsm@gmail.com>
parents: 50522
diff changeset
165 Return a C :ctype:`long long` from a Python long integer. If
20609fc13a13 Issue #5175: PyLong_AsUnsignedLongLong now raises OverflowError for
Mark Dickinson <dickinsm@gmail.com>
parents: 50522
diff changeset
166 *pylong* cannot be represented as a :ctype:`long long`, an
20609fc13a13 Issue #5175: PyLong_AsUnsignedLongLong now raises OverflowError for
Mark Dickinson <dickinsm@gmail.com>
parents: 50522
diff changeset
167 :exc:`OverflowError` is raised and ``-1`` is returned.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
168
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
169 .. versionadded:: 2.2
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
170
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
171
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
172 .. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
173
51517
20609fc13a13 Issue #5175: PyLong_AsUnsignedLongLong now raises OverflowError for
Mark Dickinson <dickinsm@gmail.com>
parents: 50522
diff changeset
174 .. index::
20609fc13a13 Issue #5175: PyLong_AsUnsignedLongLong now raises OverflowError for
Mark Dickinson <dickinsm@gmail.com>
parents: 50522
diff changeset
175 single: OverflowError (built-in exception)
20609fc13a13 Issue #5175: PyLong_AsUnsignedLongLong now raises OverflowError for
Mark Dickinson <dickinsm@gmail.com>
parents: 50522
diff changeset
176
20609fc13a13 Issue #5175: PyLong_AsUnsignedLongLong now raises OverflowError for
Mark Dickinson <dickinsm@gmail.com>
parents: 50522
diff changeset
177 Return a C :ctype:`unsigned long long` from a Python long integer. If
20609fc13a13 Issue #5175: PyLong_AsUnsignedLongLong now raises OverflowError for
Mark Dickinson <dickinsm@gmail.com>
parents: 50522
diff changeset
178 *pylong* cannot be represented as an :ctype:`unsigned long long`, an
20609fc13a13 Issue #5175: PyLong_AsUnsignedLongLong now raises OverflowError for
Mark Dickinson <dickinsm@gmail.com>
parents: 50522
diff changeset
179 :exc:`OverflowError` is raised and ``(unsigned long long)-1`` is
20609fc13a13 Issue #5175: PyLong_AsUnsignedLongLong now raises OverflowError for
Mark Dickinson <dickinsm@gmail.com>
parents: 50522
diff changeset
180 returned.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
181
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
182 .. versionadded:: 2.2
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
183
51517
20609fc13a13 Issue #5175: PyLong_AsUnsignedLongLong now raises OverflowError for
Mark Dickinson <dickinsm@gmail.com>
parents: 50522
diff changeset
184 .. versionchanged:: 2.7
20609fc13a13 Issue #5175: PyLong_AsUnsignedLongLong now raises OverflowError for
Mark Dickinson <dickinsm@gmail.com>
parents: 50522
diff changeset
185 A negative *pylong* now raises :exc:`OverflowError`, not
20609fc13a13 Issue #5175: PyLong_AsUnsignedLongLong now raises OverflowError for
Mark Dickinson <dickinsm@gmail.com>
parents: 50522
diff changeset
186 :exc:`TypeError`.
20609fc13a13 Issue #5175: PyLong_AsUnsignedLongLong now raises OverflowError for
Mark Dickinson <dickinsm@gmail.com>
parents: 50522
diff changeset
187
44796
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 .. cfunction:: unsigned long PyLong_AsUnsignedLongMask(PyObject *io)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
190
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
191 Return a C :ctype:`unsigned long` from a Python long integer, without checking
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
192 for overflow.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
193
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
194 .. versionadded:: 2.3
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
195
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 .. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *io)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
198
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
199 Return a C :ctype:`unsigned long long` from a Python long integer, without
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
200 checking for overflow.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
201
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
202 .. versionadded:: 2.3
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
203
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 .. cfunction:: double PyLong_AsDouble(PyObject *pylong)
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
206
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
207 Return a C :ctype:`double` representation of the contents of *pylong*. If
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
208 *pylong* cannot be approximately represented as a :ctype:`double`, an
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
209 :exc:`OverflowError` exception is raised and ``-1.0`` will be returned.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
210
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:: void* PyLong_AsVoidPtr(PyObject *pylong)
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 Convert a Python integer or long integer *pylong* to a C :ctype:`void` pointer.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
215 If *pylong* cannot be converted, an :exc:`OverflowError` will be raised. This
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
216 is only assured to produce a usable :ctype:`void` pointer for values created
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
217 with :cfunc:`PyLong_FromVoidPtr`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
218
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
219 .. versionadded:: 1.5.2
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
220
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
221 .. versionchanged:: 2.5
45429
853af5bbb497 A lot more typo fixes by Ori Avtalion.
Georg Brandl <georg@python.org>
parents: 44796
diff changeset
222 For values outside 0..LONG_MAX, both signed and unsigned integers are accepted.
44796
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
223
13dc65fe8599 Split the monstrous C API manual files in smaller parts.
Georg Brandl <georg@python.org>
parents:
diff changeset
224