python3.13/cpython/longobject.h

0001 #ifndef Py_CPYTHON_LONGOBJECT_H
0002 #  error "this header file must not be included directly"
0003 #endif
0004
0005 PyAPI_FUNC(PyObject*) PyLong_FromUnicodeObject(PyObject *u, int base);
0006
0007 #define Py_ASNATIVEBYTES_DEFAULTS -1
0008 #define Py_ASNATIVEBYTES_BIG_ENDIAN 0
0009 #define Py_ASNATIVEBYTES_LITTLE_ENDIAN 1
0010 #define Py_ASNATIVEBYTES_NATIVE_ENDIAN 3
0011 #define Py_ASNATIVEBYTES_UNSIGNED_BUFFER 4
0012 #define Py_ASNATIVEBYTES_REJECT_NEGATIVE 8
0013 #define Py_ASNATIVEBYTES_ALLOW_INDEX 16
0014
0015 /* PyLong_AsNativeBytes: Copy the integer value to a native variable.
0016    buffer points to the first byte of the variable.
0017    n_bytes is the number of bytes available in the buffer. Pass 0 to request
0018    the required size for the value.
0019    flags is a bitfield of the following flags:
0020    * 1 - little endian
0021    * 2 - native endian
0022    * 4 - unsigned destination (e.g. don't reject copying 255 into one byte)
0023    * 8 - raise an exception for negative inputs
0024    * 16 - call __index__ on non-int types
0025    If flags is -1 (all bits set), native endian is used, value truncation
0026    behaves most like C (allows negative inputs and allow MSB set), and non-int
0027    objects will raise a TypeError.
0028    Big endian mode will write the most significant byte into the address
0029    directly referenced by buffer; little endian will write the least significant
0030    byte into that address.
0031
0032    If an exception is raised, returns a negative value.
0033    Otherwise, returns the number of bytes that are required to store the value.
0034    To check that the full value is represented, ensure that the return value is
0035    equal or less than n_bytes.
0036    All n_bytes are guaranteed to be written (unless an exception occurs), and
0037    so ignoring a positive return value is the equivalent of a downcast in C.
0038    In cases where the full value could not be represented, the returned value
0039    may be larger than necessary - this function is not an accurate way to
0040    calculate the bit length of an integer object.
0041    */
0042 PyAPI_FUNC(Py_ssize_t) PyLong_AsNativeBytes(PyObject* v, void* buffer,
0043     Py_ssize_t n_bytes, int flags);
0044
0045 /* PyLong_FromNativeBytes: Create an int value from a native integer
0046    n_bytes is the number of bytes to read from the buffer. Passing 0 will
0047    always produce the zero int.
0048    PyLong_FromUnsignedNativeBytes always produces a non-negative int.
0049    flags is the same as for PyLong_AsNativeBytes, but only supports selecting
0050    the endianness or forcing an unsigned buffer.
0051
0052    Returns the int object, or NULL with an exception set. */
0053 PyAPI_FUNC(PyObject*) PyLong_FromNativeBytes(const void* buffer, size_t n_bytes,
0054     int flags);
0055 PyAPI_FUNC(PyObject*) PyLong_FromUnsignedNativeBytes(const void* buffer,
0056     size_t n_bytes, int flags);
0057
0058 PyAPI_FUNC(int) PyUnstable_Long_IsCompact(const PyLongObject* op);
0059 PyAPI_FUNC(Py_ssize_t) PyUnstable_Long_CompactValue(const PyLongObject* op);
0060
0061 // _PyLong_Sign.  Return 0 if v is 0, -1 if v < 0, +1 if v > 0.
0062 // v must not be NULL, and must be a normalized long.
0063 // There are no error cases.
0064 PyAPI_FUNC(int) _PyLong_Sign(PyObject *v);
0065
0066 /* _PyLong_NumBits.  Return the number of bits needed to represent the
0067    absolute value of a long.  For example, this returns 1 for 1 and -1, 2
0068    for 2 and -2, and 2 for 3 and -3.  It returns 0 for 0.
0069    v must not be NULL, and must be a normalized long.
0070    (size_t)-1 is returned and OverflowError set if the true result doesn't
0071    fit in a size_t.
0072 */
0073 PyAPI_FUNC(size_t) _PyLong_NumBits(PyObject *v);
0074
0075 /* _PyLong_FromByteArray:  View the n unsigned bytes as a binary integer in
0076    base 256, and return a Python int with the same numeric value.
0077    If n is 0, the integer is 0.  Else:
0078    If little_endian is 1/true, bytes[n-1] is the MSB and bytes[0] the LSB;
0079    else (little_endian is 0/false) bytes[0] is the MSB and bytes[n-1] the
0080    LSB.
0081    If is_signed is 0/false, view the bytes as a non-negative integer.
0082    If is_signed is 1/true, view the bytes as a 2's-complement integer,
0083    non-negative if bit 0x80 of the MSB is clear, negative if set.
0084    Error returns:
0085    + Return NULL with the appropriate exception set if there's not
0086      enough memory to create the Python int.
0087 */
0088 PyAPI_FUNC(PyObject *) _PyLong_FromByteArray(
0089     const unsigned char* bytes, size_t n,
0090     int little_endian, int is_signed);
0091
0092 /* _PyLong_AsByteArray: Convert the least-significant 8*n bits of long
0093    v to a base-256 integer, stored in array bytes.  Normally return 0,
0094    return -1 on error.
0095    If little_endian is 1/true, store the MSB at bytes[n-1] and the LSB at
0096    bytes[0]; else (little_endian is 0/false) store the MSB at bytes[0] and
0097    the LSB at bytes[n-1].
0098    If is_signed is 0/false, it's an error if v < 0; else (v >= 0) n bytes
0099    are filled and there's nothing special about bit 0x80 of the MSB.
0100    If is_signed is 1/true, bytes is filled with the 2's-complement
0101    representation of v's value.  Bit 0x80 of the MSB is the sign bit.
0102    Error returns (-1):
0103    + is_signed is 0 and v < 0.  TypeError is set in this case, and bytes
0104      isn't altered.
0105    + n isn't big enough to hold the full mathematical value of v.  For
0106      example, if is_signed is 0 and there are more digits in the v than
0107      fit in n; or if is_signed is 1, v < 0, and n is just 1 bit shy of
0108      being large enough to hold a sign bit.  OverflowError is set in this
0109      case, but bytes holds the least-significant n bytes of the true value.
0110 */
0111 PyAPI_FUNC(int) _PyLong_AsByteArray(PyLongObject* v,
0112     unsigned char* bytes, size_t n,
0113     int little_endian, int is_signed, int with_exceptions);
0114
0115 /* For use by the gcd function in mathmodule.c */
0116 PyAPI_FUNC(PyObject *) _PyLong_GCD(PyObject *, PyObject *);