/Doc/c-api/long.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 213 lines · 120 code · 93 blank · 0 comment · 0 complexity · 68621544b0005fd9e4780db8d2b7cd6f MD5 · raw file

  1. .. highlightlang:: c
  2. .. _longobjects:
  3. Long Integer Objects
  4. --------------------
  5. .. index:: object: long integer
  6. .. ctype:: PyLongObject
  7. This subtype of :ctype:`PyObject` represents a Python long integer object.
  8. .. cvar:: PyTypeObject PyLong_Type
  9. .. index:: single: LongType (in modules types)
  10. This instance of :ctype:`PyTypeObject` represents the Python long integer type.
  11. This is the same object as ``long`` and ``types.LongType``.
  12. .. cfunction:: int PyLong_Check(PyObject *p)
  13. Return true if its argument is a :ctype:`PyLongObject` or a subtype of
  14. :ctype:`PyLongObject`.
  15. .. versionchanged:: 2.2
  16. Allowed subtypes to be accepted.
  17. .. cfunction:: int PyLong_CheckExact(PyObject *p)
  18. Return true if its argument is a :ctype:`PyLongObject`, but not a subtype of
  19. :ctype:`PyLongObject`.
  20. .. versionadded:: 2.2
  21. .. cfunction:: PyObject* PyLong_FromLong(long v)
  22. Return a new :ctype:`PyLongObject` object from *v*, or *NULL* on failure.
  23. .. cfunction:: PyObject* PyLong_FromUnsignedLong(unsigned long v)
  24. Return a new :ctype:`PyLongObject` object from a C :ctype:`unsigned long`, or
  25. *NULL* on failure.
  26. .. cfunction:: PyObject* PyLong_FromSsize_t(Py_ssize_t v)
  27. Return a new :ctype:`PyLongObject` object from a C :ctype:`Py_ssize_t`, or
  28. *NULL* on failure.
  29. .. versionadded:: 2.6
  30. .. cfunction:: PyObject* PyLong_FromSize_t(size_t v)
  31. Return a new :ctype:`PyLongObject` object from a C :ctype:`size_t`, or
  32. *NULL* on failure.
  33. .. versionadded:: 2.6
  34. .. cfunction:: PyObject* PyLong_FromLongLong(PY_LONG_LONG v)
  35. Return a new :ctype:`PyLongObject` object from a C :ctype:`long long`, or *NULL*
  36. on failure.
  37. .. cfunction:: PyObject* PyLong_FromUnsignedLongLong(unsigned PY_LONG_LONG v)
  38. Return a new :ctype:`PyLongObject` object from a C :ctype:`unsigned long long`,
  39. or *NULL* on failure.
  40. .. cfunction:: PyObject* PyLong_FromDouble(double v)
  41. Return a new :ctype:`PyLongObject` object from the integer part of *v*, or
  42. *NULL* on failure.
  43. .. cfunction:: PyObject* PyLong_FromString(char *str, char **pend, int base)
  44. Return a new :ctype:`PyLongObject` based on the string value in *str*, which is
  45. interpreted according to the radix in *base*. If *pend* is non-*NULL*,
  46. ``*pend`` will point to the first character in *str* which follows the
  47. representation of the number. If *base* is ``0``, the radix will be determined
  48. based on the leading characters of *str*: if *str* starts with ``'0x'`` or
  49. ``'0X'``, radix 16 will be used; if *str* starts with ``'0'``, radix 8 will be
  50. used; otherwise radix 10 will be used. If *base* is not ``0``, it must be
  51. between ``2`` and ``36``, inclusive. Leading spaces are ignored. If there are
  52. no digits, :exc:`ValueError` will be raised.
  53. .. cfunction:: PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base)
  54. Convert a sequence of Unicode digits to a Python long integer value. The first
  55. parameter, *u*, points to the first character of the Unicode string, *length*
  56. gives the number of characters, and *base* is the radix for the conversion. The
  57. radix must be in the range [2, 36]; if it is out of range, :exc:`ValueError`
  58. will be raised.
  59. .. versionadded:: 1.6
  60. .. versionchanged:: 2.5
  61. This function used an :ctype:`int` for *length*. This might require
  62. changes in your code for properly supporting 64-bit systems.
  63. .. cfunction:: PyObject* PyLong_FromVoidPtr(void *p)
  64. Create a Python integer or long integer from the pointer *p*. The pointer value
  65. can be retrieved from the resulting value using :cfunc:`PyLong_AsVoidPtr`.
  66. .. versionadded:: 1.5.2
  67. .. versionchanged:: 2.5
  68. If the integer is larger than LONG_MAX, a positive long integer is returned.
  69. .. cfunction:: long PyLong_AsLong(PyObject *pylong)
  70. .. index::
  71. single: LONG_MAX
  72. single: OverflowError (built-in exception)
  73. Return a C :ctype:`long` representation of the contents of *pylong*. If
  74. *pylong* is greater than :const:`LONG_MAX`, an :exc:`OverflowError` is raised
  75. and ``-1`` will be returned.
  76. .. cfunction:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)
  77. .. index::
  78. single: PY_SSIZE_T_MAX
  79. single: OverflowError (built-in exception)
  80. Return a C :ctype:`Py_ssize_t` representation of the contents of *pylong*. If
  81. *pylong* is greater than :const:`PY_SSIZE_T_MAX`, an :exc:`OverflowError` is raised
  82. and ``-1`` will be returned.
  83. .. versionadded:: 2.6
  84. .. cfunction:: unsigned long PyLong_AsUnsignedLong(PyObject *pylong)
  85. .. index::
  86. single: ULONG_MAX
  87. single: OverflowError (built-in exception)
  88. Return a C :ctype:`unsigned long` representation of the contents of *pylong*.
  89. If *pylong* is greater than :const:`ULONG_MAX`, an :exc:`OverflowError` is
  90. raised.
  91. .. cfunction:: PY_LONG_LONG PyLong_AsLongLong(PyObject *pylong)
  92. Return a C :ctype:`long long` from a Python long integer. If *pylong* cannot be
  93. represented as a :ctype:`long long`, an :exc:`OverflowError` will be raised.
  94. .. versionadded:: 2.2
  95. .. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong)
  96. Return a C :ctype:`unsigned long long` from a Python long integer. If *pylong*
  97. cannot be represented as an :ctype:`unsigned long long`, an :exc:`OverflowError`
  98. will be raised if the value is positive, or a :exc:`TypeError` will be raised if
  99. the value is negative.
  100. .. versionadded:: 2.2
  101. .. cfunction:: unsigned long PyLong_AsUnsignedLongMask(PyObject *io)
  102. Return a C :ctype:`unsigned long` from a Python long integer, without checking
  103. for overflow.
  104. .. versionadded:: 2.3
  105. .. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *io)
  106. Return a C :ctype:`unsigned long long` from a Python long integer, without
  107. checking for overflow.
  108. .. versionadded:: 2.3
  109. .. cfunction:: double PyLong_AsDouble(PyObject *pylong)
  110. Return a C :ctype:`double` representation of the contents of *pylong*. If
  111. *pylong* cannot be approximately represented as a :ctype:`double`, an
  112. :exc:`OverflowError` exception is raised and ``-1.0`` will be returned.
  113. .. cfunction:: void* PyLong_AsVoidPtr(PyObject *pylong)
  114. Convert a Python integer or long integer *pylong* to a C :ctype:`void` pointer.
  115. If *pylong* cannot be converted, an :exc:`OverflowError` will be raised. This
  116. is only assured to produce a usable :ctype:`void` pointer for values created
  117. with :cfunc:`PyLong_FromVoidPtr`.
  118. .. versionadded:: 1.5.2
  119. .. versionchanged:: 2.5
  120. For values outside 0..LONG_MAX, both signed and unsigned integers are accepted.