/Doc/c-api/int.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 130 lines · 75 code · 55 blank · 0 comment · 0 complexity · 2f45ee48529a9e77aedcbddc26673aa1 MD5 · raw file

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