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 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