summaryrefslogtreecommitdiffstats
path: root/Doc/c-api/int.rst
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/c-api/int.rst')
-rw-r--r--Doc/c-api/int.rst122
1 files changed, 122 insertions, 0 deletions
diff --git a/Doc/c-api/int.rst b/Doc/c-api/int.rst
new file mode 100644
index 0000000..526083b
--- /dev/null
+++ b/Doc/c-api/int.rst
@@ -0,0 +1,122 @@
+.. highlightlang:: c
+
+.. _intobjects:
+
+Plain Integer Objects
+---------------------
+
+.. index:: object: integer
+
+
+.. ctype:: PyIntObject
+
+ This subtype of :ctype:`PyObject` represents a Python integer object.
+
+
+.. cvar:: PyTypeObject PyInt_Type
+
+ .. index:: single: IntType (in modules types)
+
+ This instance of :ctype:`PyTypeObject` represents the Python plain integer type.
+ This is the same object as ``int`` and ``types.IntType``.
+
+
+.. cfunction:: int PyInt_Check(PyObject *o)
+
+ Return true if *o* is of type :cdata:`PyInt_Type` or a subtype of
+ :cdata:`PyInt_Type`.
+
+ .. versionchanged:: 2.2
+ Allowed subtypes to be accepted.
+
+
+.. cfunction:: int PyInt_CheckExact(PyObject *o)
+
+ Return true if *o* is of type :cdata:`PyInt_Type`, but not a subtype of
+ :cdata:`PyInt_Type`.
+
+ .. versionadded:: 2.2
+
+
+.. cfunction:: PyObject* PyInt_FromString(char *str, char **pend, int base)
+
+ Return a new :ctype:`PyIntObject` or :ctype:`PyLongObject` based on the string
+ value in *str*, which is interpreted according to the radix in *base*. If
+ *pend* is non-*NULL*, ``*pend`` will point to the first character in *str* which
+ follows the representation of the number. If *base* is ``0``, the radix will be
+ determined based on the leading characters of *str*: if *str* starts with
+ ``'0x'`` or ``'0X'``, radix 16 will be used; if *str* starts with ``'0'``, radix
+ 8 will be used; otherwise radix 10 will be used. If *base* is not ``0``, it
+ must be between ``2`` and ``36``, inclusive. Leading spaces are ignored. If
+ there are no digits, :exc:`ValueError` will be raised. If the string represents
+ a number too large to be contained within the machine's :ctype:`long int` type
+ and overflow warnings are being suppressed, a :ctype:`PyLongObject` will be
+ returned. If overflow warnings are not being suppressed, *NULL* will be
+ returned in this case.
+
+
+.. cfunction:: PyObject* PyInt_FromLong(long ival)
+
+ Create a new integer object with a value of *ival*.
+
+ The current implementation keeps an array of integer objects for all integers
+ between ``-5`` and ``256``, when you create an int in that range you actually
+ just get back a reference to the existing object. So it should be possible to
+ change the value of ``1``. I suspect the behaviour of Python in this case is
+ undefined. :-)
+
+
+.. cfunction:: PyObject* PyInt_FromSsize_t(Py_ssize_t ival)
+
+ Create a new integer object with a value of *ival*. If the value exceeds
+ ``LONG_MAX``, a long integer object is returned.
+
+ .. versionadded:: 2.5
+
+
+.. cfunction:: long PyInt_AsLong(PyObject *io)
+
+ Will first attempt to cast the object to a :ctype:`PyIntObject`, if it is not
+ already one, and then return its value. If there is an error, ``-1`` is
+ returned, and the caller should check ``PyErr_Occurred()`` to find out whether
+ there was an error, or whether the value just happened to be -1.
+
+
+.. cfunction:: long PyInt_AS_LONG(PyObject *io)
+
+ Return the value of the object *io*. No error checking is performed.
+
+
+.. cfunction:: unsigned long PyInt_AsUnsignedLongMask(PyObject *io)
+
+ Will first attempt to cast the object to a :ctype:`PyIntObject` or
+ :ctype:`PyLongObject`, if it is not already one, and then return its value as
+ unsigned long. This function does not check for overflow.
+
+ .. versionadded:: 2.3
+
+
+.. cfunction:: unsigned PY_LONG_LONG PyInt_AsUnsignedLongLongMask(PyObject *io)
+
+ Will first attempt to cast the object to a :ctype:`PyIntObject` or
+ :ctype:`PyLongObject`, if it is not already one, and then return its value as
+ unsigned long long, without checking for overflow.
+
+ .. versionadded:: 2.3
+
+
+.. cfunction:: Py_ssize_t PyInt_AsSsize_t(PyObject *io)
+
+ Will first attempt to cast the object to a :ctype:`PyIntObject` or
+ :ctype:`PyLongObject`, if it is not already one, and then return its value as
+ :ctype:`Py_ssize_t`.
+
+ .. versionadded:: 2.5
+
+
+.. cfunction:: long PyInt_GetMax()
+
+ .. index:: single: LONG_MAX
+
+ Return the system's idea of the largest integer it can handle
+ (:const:`LONG_MAX`, as defined in the system header files).