← Back to branch summary

~dkuhlman/python-training-materials/Materials

« back to all changes in this revision

Viewing changes to python-3.5.1-docs-html/_sources/c-api/long.txt

  • Committer: Dave Kuhlman
  • Date: 2017-04-15 16:24:56 UTC
  • Revision ID: dkuhlman@davekuhlman.org-20170415162456-iav9vozzg4iwqwv3
Updated docs

Show diffs side-by-side

added added

removed removed

Lines of Context:
python-3.5.1-docs-html/_sources/c-api/long.txt
1
 
.. highlightlang:: c
2
 
 
3
 
.. _longobjects:
4
 
 
5
 
Integer Objects
6
 
---------------
7
 
 
8
 
.. index:: object: long integer
9
 
           object: integer
10
 
 
11
 
All integers are implemented as "long" integer objects of arbitrary size.
12
 
 
13
 
.. c:type:: PyLongObject
14
 
 
15
 
   This subtype of :c:type:`PyObject` represents a Python integer object.
16
 
 
17
 
 
18
 
.. c:var:: PyTypeObject PyLong_Type
19
 
 
20
 
   This instance of :c:type:`PyTypeObject` represents the Python integer type.
21
 
   This is the same object as :class:`int` in the Python layer.
22
 
 
23
 
 
24
 
.. c:function:: int PyLong_Check(PyObject *p)
25
 
 
26
 
   Return true if its argument is a :c:type:`PyLongObject` or a subtype of
27
 
   :c:type:`PyLongObject`.
28
 
 
29
 
 
30
 
.. c:function:: int PyLong_CheckExact(PyObject *p)
31
 
 
32
 
   Return true if its argument is a :c:type:`PyLongObject`, but not a subtype of
33
 
   :c:type:`PyLongObject`.
34
 
 
35
 
 
36
 
.. c:function:: PyObject* PyLong_FromLong(long v)
37
 
 
38
 
   Return a new :c:type:`PyLongObject` object from *v*, or *NULL* on failure.
39
 
 
40
 
   The current implementation keeps an array of integer objects for all integers
41
 
   between ``-5`` and ``256``, when you create an int in that range you actually
42
 
   just get back a reference to the existing object. So it should be possible to
43
 
   change the value of ``1``.  I suspect the behaviour of Python in this case is
44
 
   undefined. :-)
45
 
 
46
 
 
47
 
.. c:function:: PyObject* PyLong_FromUnsignedLong(unsigned long v)
48
 
 
49
 
   Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long`, or
50
 
   *NULL* on failure.
51
 
 
52
 
 
53
 
.. c:function:: PyObject* PyLong_FromSsize_t(Py_ssize_t v)
54
 
 
55
 
   Return a new :c:type:`PyLongObject` object from a C :c:type:`Py_ssize_t`, or
56
 
   *NULL* on failure.
57
 
 
58
 
 
59
 
.. c:function:: PyObject* PyLong_FromSize_t(size_t v)
60
 
 
61
 
   Return a new :c:type:`PyLongObject` object from a C :c:type:`size_t`, or
62
 
   *NULL* on failure.
63
 
 
64
 
 
65
 
.. c:function:: PyObject* PyLong_FromLongLong(PY_LONG_LONG v)
66
 
 
67
 
   Return a new :c:type:`PyLongObject` object from a C :c:type:`long long`, or *NULL*
68
 
   on failure.
69
 
 
70
 
 
71
 
.. c:function:: PyObject* PyLong_FromUnsignedLongLong(unsigned PY_LONG_LONG v)
72
 
 
73
 
   Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long long`,
74
 
   or *NULL* on failure.
75
 
 
76
 
 
77
 
.. c:function:: PyObject* PyLong_FromDouble(double v)
78
 
 
79
 
   Return a new :c:type:`PyLongObject` object from the integer part of *v*, or
80
 
   *NULL* on failure.
81
 
 
82
 
 
83
 
.. c:function:: PyObject* PyLong_FromString(const char *str, char **pend, int base)
84
 
 
85
 
   Return a new :c:type:`PyLongObject` based on the string value in *str*, which
86
 
   is interpreted according to the radix in *base*.  If *pend* is non-*NULL*,
87
 
   *\*pend* will point to the first character in *str* which follows the
88
 
   representation of the number.  If *base* is ``0``, the radix will be
89
 
   determined based on the leading characters of *str*: if *str* starts with
90
 
   ``'0x'`` or ``'0X'``, radix 16 will be used; if *str* starts with ``'0o'`` or
91
 
   ``'0O'``, radix 8 will be used; if *str* starts with ``'0b'`` or ``'0B'``,
92
 
   radix 2 will be used; otherwise radix 10 will be used.  If *base* is not
93
 
   ``0``, it must be between ``2`` and ``36``, inclusive.  Leading spaces are
94
 
   ignored.  If there are no digits, :exc:`ValueError` will be raised.
95
 
 
96
 
 
97
 
.. c:function:: PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base)
98
 
 
99
 
   Convert a sequence of Unicode digits to a Python integer value.  The Unicode
100
 
   string is first encoded to a byte string using :c:func:`PyUnicode_EncodeDecimal`
101
 
   and then converted using :c:func:`PyLong_FromString`.
102
 
 
103
 
   .. deprecated-removed:: 3.3 4.0
104
 
      Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
105
 
      :c:func:`PyLong_FromUnicodeObject`.
106
 
 
107
 
 
108
 
.. c:function:: PyObject* PyLong_FromUnicodeObject(PyObject *u, int base)
109
 
 
110
 
   Convert a sequence of Unicode digits in the string *u* to a Python integer
111
 
   value.  The Unicode string is first encoded to a byte string using
112
 
   :c:func:`PyUnicode_EncodeDecimal` and then converted using
113
 
   :c:func:`PyLong_FromString`.
114
 
 
115
 
   .. versionadded:: 3.3
116
 
 
117
 
 
118
 
.. c:function:: PyObject* PyLong_FromVoidPtr(void *p)
119
 
 
120
 
   Create a Python integer from the pointer *p*. The pointer value can be
121
 
   retrieved from the resulting value using :c:func:`PyLong_AsVoidPtr`.
122
 
 
123
 
 
124
 
.. XXX alias PyLong_AS_LONG (for now)
125
 
.. c:function:: long PyLong_AsLong(PyObject *obj)
126
 
 
127
 
   .. index::
128
 
      single: LONG_MAX
129
 
      single: OverflowError (built-in exception)
130
 
 
131
 
   Return a C :c:type:`long` representation of *obj*.  If *obj* is not an
132
 
   instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method
133
 
   (if present) to convert it to a :c:type:`PyLongObject`.
134
 
 
135
 
   Raise :exc:`OverflowError` if the value of *obj* is out of range for a
136
 
   :c:type:`long`.
137
 
 
138
 
 
139
 
.. c:function:: long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)
140
 
 
141
 
   Return a C :c:type:`long` representation of *obj*.  If *obj* is not an
142
 
   instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method
143
 
   (if present) to convert it to a :c:type:`PyLongObject`.
144
 
 
145
 
   If the value of *obj* is greater than :const:`LONG_MAX` or less than
146
 
   :const:`LONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively, and
147
 
   return ``-1``; otherwise, set *\*overflow* to ``0``.  If any other exception
148
 
   occurs set *\*overflow* to ``0`` and return ``-1`` as usual.
149
 
 
150
 
 
151
 
.. c:function:: PY_LONG_LONG PyLong_AsLongLong(PyObject *obj)
152
 
 
153
 
   .. index::
154
 
      single: OverflowError (built-in exception)
155
 
 
156
 
   Return a C :c:type:`long long` representation of *obj*.  If *obj* is not an
157
 
   instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method
158
 
   (if present) to convert it to a :c:type:`PyLongObject`.
159
 
 
160
 
   Raise :exc:`OverflowError` if the value of *obj* is out of range for a
161
 
   :c:type:`long`.
162
 
 
163
 
 
164
 
.. c:function:: PY_LONG_LONG PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)
165
 
 
166
 
   Return a C :c:type:`long long` representation of *obj*.  If *obj* is not an
167
 
   instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method
168
 
   (if present) to convert it to a :c:type:`PyLongObject`.
169
 
 
170
 
   If the value of *obj* is greater than :const:`PY_LLONG_MAX` or less than
171
 
   :const:`PY_LLONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively,
172
 
   and return ``-1``; otherwise, set *\*overflow* to ``0``.  If any other
173
 
   exception occurs set *\*overflow* to ``0`` and return ``-1`` as usual.
174
 
 
175
 
   .. versionadded:: 3.2
176
 
 
177
 
 
178
 
.. c:function:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)
179
 
 
180
 
   .. index::
181
 
      single: PY_SSIZE_T_MAX
182
 
      single: OverflowError (built-in exception)
183
 
 
184
 
   Return a C :c:type:`Py_ssize_t` representation of *pylong*.  *pylong* must
185
 
   be an instance of :c:type:`PyLongObject`.
186
 
 
187
 
   Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
188
 
   :c:type:`Py_ssize_t`.
189
 
 
190
 
 
191
 
.. c:function:: unsigned long PyLong_AsUnsignedLong(PyObject *pylong)
192
 
 
193
 
   .. index::
194
 
      single: ULONG_MAX
195
 
      single: OverflowError (built-in exception)
196
 
 
197
 
   Return a C :c:type:`unsigned long` representation of *pylong*.  *pylong*
198
 
   must be an instance of :c:type:`PyLongObject`.
199
 
 
200
 
   Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
201
 
   :c:type:`unsigned long`.
202
 
 
203
 
 
204
 
.. c:function:: size_t PyLong_AsSize_t(PyObject *pylong)
205
 
 
206
 
   Return a C :c:type:`size_t` representation of *pylong*.  *pylong* must be
207
 
   an instance of :c:type:`PyLongObject`.
208
 
 
209
 
   Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
210
 
   :c:type:`size_t`.
211
 
 
212
 
 
213
 
.. c:function:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong)
214
 
 
215
 
   .. index::
216
 
      single: OverflowError (built-in exception)
217
 
 
218
 
   Return a C :c:type:`unsigned PY_LONG_LONG` representation of *pylong*.
219
 
   *pylong* must be an instance of :c:type:`PyLongObject`.
220
 
 
221
 
   Raise :exc:`OverflowError` if the value of *pylong* is out of range for an
222
 
   :c:type:`unsigned PY_LONG_LONG`.
223
 
 
224
 
   .. versionchanged:: 3.1
225
 
      A negative *pylong* now raises :exc:`OverflowError`, not :exc:`TypeError`.
226
 
 
227
 
 
228
 
.. c:function:: unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)
229
 
 
230
 
   Return a C :c:type:`unsigned long` representation of *obj*.  If *obj*
231
 
   is not an instance of :c:type:`PyLongObject`, first call its :meth:`__int__`
232
 
   method (if present) to convert it to a :c:type:`PyLongObject`.
233
 
 
234
 
   If the value of *obj* is out of range for an :c:type:`unsigned long`,
235
 
   return the reduction of that value modulo :const:`ULONG_MAX + 1`.
236
 
 
237
 
 
238
 
.. c:function:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *obj)
239
 
 
240
 
   Return a C :c:type:`unsigned long long` representation of *obj*.  If *obj*
241
 
   is not an instance of :c:type:`PyLongObject`, first call its :meth:`__int__`
242
 
   method (if present) to convert it to a :c:type:`PyLongObject`.
243
 
 
244
 
   If the value of *obj* is out of range for an :c:type:`unsigned long long`,
245
 
   return the reduction of that value modulo :const:`PY_ULLONG_MAX + 1`.
246
 
 
247
 
 
248
 
.. c:function:: double PyLong_AsDouble(PyObject *pylong)
249
 
 
250
 
   Return a C :c:type:`double` representation of *pylong*.  *pylong* must be
251
 
   an instance of :c:type:`PyLongObject`.
252
 
 
253
 
   Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
254
 
   :c:type:`double`.
255
 
 
256
 
 
257
 
.. c:function:: void* PyLong_AsVoidPtr(PyObject *pylong)
258
 
 
259
 
   Convert a Python integer *pylong* to a C :c:type:`void` pointer.
260
 
   If *pylong* cannot be converted, an :exc:`OverflowError` will be raised.  This
261
 
   is only assured to produce a usable :c:type:`void` pointer for values created
262
 
   with :c:func:`PyLong_FromVoidPtr`.