Doc/c-api/int.rst

   1 .. highlightlang:: c
   2
   3 .. _intobjects:
   4
   5 Plain 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 is larger
  72    than ``LONG_MAX`` or smaller than ``LONG_MIN``, a long integer object is
  73    returned.
  74
  75    .. versionadded:: 2.5
  76
  77
  78 .. cfunction:: PyObject* PyInt_FromSize_t(size_t ival)
  79
  80    Create a new integer object with a value of *ival*. If the value exceeds
  81    ``LONG_MAX``, a long integer object is returned.
  82
  83    .. versionadded:: 2.5
  84
  85
  86 .. cfunction:: long PyInt_AsLong(PyObject *io)
  87
  88    Will first attempt to cast the object to a :ctype:`PyIntObject`, if it is not
  89    already one, and then return its value. If there is an error, ``-1`` is
  90    returned, and the caller should check ``PyErr_Occurred()`` to find out whether
  91    there was an error, or whether the value just happened to be -1.
  92
  93
  94 .. cfunction:: long PyInt_AS_LONG(PyObject *io)
  95
  96    Return the value of the object *io*.  No error checking is performed.
  97
  98
  99 .. cfunction:: unsigned long PyInt_AsUnsignedLongMask(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.  This function does not check for overflow.
 104
 105    .. versionadded:: 2.3
 106
 107
 108 .. cfunction:: unsigned PY_LONG_LONG PyInt_AsUnsignedLongLongMask(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    unsigned long long, without checking for overflow.
 113
 114    .. versionadded:: 2.3
 115
 116
 117 .. cfunction:: Py_ssize_t PyInt_AsSsize_t(PyObject *io)
 118
 119    Will first attempt to cast the object to a :ctype:`PyIntObject` or
 120    :ctype:`PyLongObject`, if it is not already one, and then return its value as
 121    :ctype:`Py_ssize_t`.
 122
 123    .. versionadded:: 2.5
 124
 125
 126 .. cfunction:: long PyInt_GetMax()
 127
 128    .. index:: single: LONG_MAX
 129
 130    Return the system's idea of the largest integer it can handle
 131    (:const:`LONG_MAX`, as defined in the system header files).
 132
 133
 134 .. cfunction:: int PyInt_ClearFreeList()
 135
 136    Clear the integer free list. Return the number of items that could not
 137    be freed.
 138
 139    .. versionadded:: 2.6