/Doc/c-api/int.rst

  1.. highlightlang:: c
  2
  3.. _intobjects:
  4
  5Plain Integer Objects
  6---------------------
  7
  8.. index:: object: integer
  9
 10
 11.. ctype:: PyIntObject
 12
 13   This subtype of :ctype:`PyObject` represents a Python integer object.
 14
 15
 16.. cvar:: PyTypeObject PyInt_Type
 17
 18   .. index:: single: IntType (in modules types)
 19
 20   This instance of :ctype:`PyTypeObject` represents the Python plain integer type.
 21   This is the same object as ``int`` and ``types.IntType``.
 22
 23
 24.. cfunction:: int PyInt_Check(PyObject *o)
 25
 26   Return true if *o* is of type :cdata:`PyInt_Type` or a subtype of
 27   :cdata:`PyInt_Type`.
 28
 29   .. versionchanged:: 2.2
 30      Allowed subtypes to be accepted.
 31
 32
 33.. cfunction:: int PyInt_CheckExact(PyObject *o)
 34
 35   Return true if *o* is of type :cdata:`PyInt_Type`, but not a subtype of
 36   :cdata:`PyInt_Type`.
 37
 38   .. versionadded:: 2.2
 39
 40
 41.. cfunction:: PyObject* PyInt_FromString(char *str, char **pend, int base)
 42
 43   Return a new :ctype:`PyIntObject` or :ctype:`PyLongObject` based on the string
 44   value in *str*, which is interpreted according to the radix in *base*.  If
 45   *pend* is non-*NULL*, ``*pend`` will point to the first character in *str* which
 46   follows the representation of the number.  If *base* is ``0``, the radix will be
 47   determined based on the leading characters of *str*: if *str* starts with
 48   ``'0x'`` or ``'0X'``, radix 16 will be used; if *str* starts with ``'0'``, radix
 49   8 will be used; otherwise radix 10 will be used.  If *base* is not ``0``, it
 50   must be between ``2`` and ``36``, inclusive.  Leading spaces are ignored.  If
 51   there are no digits, :exc:`ValueError` will be raised.  If the string represents
 52   a number too large to be contained within the machine's :ctype:`long int` type
 53   and overflow warnings are being suppressed, a :ctype:`PyLongObject` will be
 54   returned.  If overflow warnings are not being suppressed, *NULL* will be
 55   returned in this case.
 56
 57
 58.. cfunction:: PyObject* PyInt_FromLong(long ival)
 59
 60   Create a new integer object with a value of *ival*.
 61
 62   The current implementation keeps an array of integer objects for all integers
 63   between ``-5`` and ``256``, when you create an int in that range you actually
 64   just get back a reference to the existing object. So it should be possible to
 65   change the value of ``1``.  I suspect the behaviour of Python in this case is
 66   undefined. :-)
 67
 68
 69.. cfunction:: PyObject* PyInt_FromSsize_t(Py_ssize_t ival)
 70
 71   Create a new integer object with a value of *ival*. If the value exceeds
 72   ``LONG_MAX``, a long integer object is returned.
 73
 74   .. versionadded:: 2.5
 75
 76
 77.. cfunction:: long PyInt_AsLong(PyObject *io)
 78
 79   Will first attempt to cast the object to a :ctype:`PyIntObject`, if it is not
 80   already one, and then return its value. If there is an error, ``-1`` is
 81   returned, and the caller should check ``PyErr_Occurred()`` to find out whether
 82   there was an error, or whether the value just happened to be -1.
 83
 84
 85.. cfunction:: long PyInt_AS_LONG(PyObject *io)
 86
 87   Return the value of the object *io*.  No error checking is performed.
 88
 89
 90.. cfunction:: unsigned long PyInt_AsUnsignedLongMask(PyObject *io)
 91
 92   Will first attempt to cast the object to a :ctype:`PyIntObject` or
 93   :ctype:`PyLongObject`, if it is not already one, and then return its value as
 94   unsigned long.  This function does not check for overflow.
 95
 96   .. versionadded:: 2.3
 97
 98
 99.. cfunction:: unsigned PY_LONG_LONG PyInt_AsUnsignedLongLongMask(PyObject *io)
100
101   Will first attempt to cast the object to a :ctype:`PyIntObject` or
102   :ctype:`PyLongObject`, if it is not already one, and then return its value as
103   unsigned long long, without checking for overflow.
104
105   .. versionadded:: 2.3
106
107
108.. cfunction:: Py_ssize_t PyInt_AsSsize_t(PyObject *io)
109
110   Will first attempt to cast the object to a :ctype:`PyIntObject` or
111   :ctype:`PyLongObject`, if it is not already one, and then return its value as
112   :ctype:`Py_ssize_t`.
113
114   .. versionadded:: 2.5
115
116
117.. cfunction:: long PyInt_GetMax()
118
119   .. index:: single: LONG_MAX
120
121   Return the system's idea of the largest integer it can handle
122   (:const:`LONG_MAX`, as defined in the system header files).
123
124
125.. cfunction:: int PyInt_ClearFreeList(void)
126
127   Clear the integer free list. Return the number of items that could not
128   be freed.
129
130   .. versionadded:: 2.6