summaryrefslogtreecommitdiffstats
path: root/Doc/c-api/int.rst
blob: 94bf380ec3ad09a62be872c906b6ebc9d8b1e32b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
.. highlightlang:: c

.. _intobjects:

Plain Integer Objects
---------------------

.. index:: object: integer


.. ctype:: PyIntObject

   This subtype of :ctype:`PyObject` represents a Python integer object.


.. cvar:: PyTypeObject PyInt_Type

   .. index:: single: IntType (in modules types)

   This instance of :ctype:`PyTypeObject` represents the Python plain integer type.
   This is the same object as ``int`` and ``types.IntType``.


.. cfunction:: int PyInt_Check(PyObject *o)

   Return true if *o* is of type :cdata:`PyInt_Type` or a subtype of
   :cdata:`PyInt_Type`.

   .. versionchanged:: 2.2
      Allowed subtypes to be accepted.


.. cfunction:: int PyInt_CheckExact(PyObject *o)

   Return true if *o* is of type :cdata:`PyInt_Type`, but not a subtype of
   :cdata:`PyInt_Type`.

   .. versionadded:: 2.2


.. cfunction:: PyObject* PyInt_FromString(char *str, char **pend, int base)

   Return a new :ctype:`PyIntObject` or :ctype:`PyLongObject` based on the string
   value in *str*, which is interpreted according to the radix in *base*.  If
   *pend* is non-*NULL*, ``*pend`` will point to the first character in *str* which
   follows the representation of the number.  If *base* is ``0``, the radix will be
   determined based on the leading characters of *str*: if *str* starts with
   ``'0x'`` or ``'0X'``, radix 16 will be used; if *str* starts with ``'0'``, radix
   8 will be used; otherwise radix 10 will be used.  If *base* is not ``0``, it
   must be between ``2`` and ``36``, inclusive.  Leading spaces are ignored.  If
   there are no digits, :exc:`ValueError` will be raised.  If the string represents
   a number too large to be contained within the machine's :ctype:`long int` type
   and overflow warnings are being suppressed, a :ctype:`PyLongObject` will be
   returned.  If overflow warnings are not being suppressed, *NULL* will be
   returned in this case.


.. cfunction:: PyObject* PyInt_FromLong(long ival)

   Create a new integer object with a value of *ival*.

   The current implementation keeps an array of integer objects for all integers
   between ``-5`` and ``256``, when you create an int in that range you actually
   just get back a reference to the existing object. So it should be possible to
   change the value of ``1``.  I suspect the behaviour of Python in this case is
   undefined. :-)


.. cfunction:: PyObject* PyInt_FromSsize_t(Py_ssize_t ival)

   Create a new integer object with a value of *ival*. If the value exceeds
   ``LONG_MAX``, a long integer object is returned.

   .. versionadded:: 2.5


.. cfunction:: long PyInt_AsLong(PyObject *io)

   Will first attempt to cast the object to a :ctype:`PyIntObject`, if it is not
   already one, and then return its value. If there is an error, ``-1`` is
   returned, and the caller should check ``PyErr_Occurred()`` to find out whether
   there was an error, or whether the value just happened to be -1.


.. cfunction:: long PyInt_AS_LONG(PyObject *io)

   Return the value of the object *io*.  No error checking is performed.


.. cfunction:: unsigned long PyInt_AsUnsignedLongMask(PyObject *io)

   Will first attempt to cast the object to a :ctype:`PyIntObject` or
   :ctype:`PyLongObject`, if it is not already one, and then return its value as
   unsigned long.  This function does not check for overflow.

   .. versionadded:: 2.3


.. cfunction:: unsigned PY_LONG_LONG PyInt_AsUnsignedLongLongMask(PyObject *io)

   Will first attempt to cast the object to a :ctype:`PyIntObject` or
   :ctype:`PyLongObject`, if it is not already one, and then return its value as
   unsigned long long, without checking for overflow.

   .. versionadded:: 2.3


.. cfunction:: Py_ssize_t PyInt_AsSsize_t(PyObject *io)

   Will first attempt to cast the object to a :ctype:`PyIntObject` or
   :ctype:`PyLongObject`, if it is not already one, and then return its value as
   :ctype:`Py_ssize_t`.

   .. versionadded:: 2.5


.. cfunction:: long PyInt_GetMax()

   .. index:: single: LONG_MAX

   Return the system's idea of the largest integer it can handle
   (:const:`LONG_MAX`, as defined in the system header files).


.. cfunction:: void PyInt_CompactFreeList(size_t *bc, size_t *bf, size_t *sum)

   Compact the integer free list. *bc* is the number of allocated blocks before
   blocks are freed, *bf* is the number of freed blocks and *sum* is the number
   of remaining objects in the blocks.

   .. versionadded:: 2.6