python3.13/internal/pycore_long.h

0001 #ifndef Py_INTERNAL_LONG_H
0002 #define Py_INTERNAL_LONG_H
0003 #ifdef __cplusplus
0004 extern "C" {
0005 #endif
0006
0007 #ifndef Py_BUILD_CORE
0008 #  error "this header requires Py_BUILD_CORE define"
0009 #endif
0010
0011 #include "pycore_bytesobject.h"   // _PyBytesWriter
0012 #include "pycore_global_objects.h"// _PY_NSMALLNEGINTS
0013 #include "pycore_runtime.h"       // _PyRuntime
0014
0015 /*
0016  * Default int base conversion size limitation: Denial of Service prevention.
0017  *
0018  * Chosen such that this isn't wildly slow on modern hardware and so that
0019  * everyone's existing deployed numpy test suite passes before
0020  * https://github.com/numpy/numpy/issues/22098 is widely available.
0021  *
0022  * $ python -m timeit -s 's = "1"*4300' 'int(s)'
0023  * 2000 loops, best of 5: 125 usec per loop
0024  * $ python -m timeit -s 's = "1"*4300; v = int(s)' 'str(v)'
0025  * 1000 loops, best of 5: 311 usec per loop
0026  * (zen2 cloud VM)
0027  *
0028  * 4300 decimal digits fits a ~14284 bit number.
0029  */
0030 #define _PY_LONG_DEFAULT_MAX_STR_DIGITS 4300
0031 /*
0032  * Threshold for max digits check.  For performance reasons int() and
0033  * int.__str__() don't checks values that are smaller than this
0034  * threshold.  Acts as a guaranteed minimum size limit for bignums that
0035  * applications can expect from CPython.
0036  *
0037  * % python -m timeit -s 's = "1"*640; v = int(s)' 'str(int(s))'
0038  * 20000 loops, best of 5: 12 usec per loop
0039  *
0040  * "640 digits should be enough for anyone." - gps
0041  * fits a ~2126 bit decimal number.
0042  */
0043 #define _PY_LONG_MAX_STR_DIGITS_THRESHOLD 640
0044
0045 #if ((_PY_LONG_DEFAULT_MAX_STR_DIGITS != 0) && \
0046    (_PY_LONG_DEFAULT_MAX_STR_DIGITS < _PY_LONG_MAX_STR_DIGITS_THRESHOLD))
0047 # error "_PY_LONG_DEFAULT_MAX_STR_DIGITS smaller than threshold."
0048 #endif
0049
0050 /* runtime lifecycle */
0051
0052 extern PyStatus _PyLong_InitTypes(PyInterpreterState *);
0053 extern void _PyLong_FiniTypes(PyInterpreterState *interp);
0054
0055
0056 /* other API */
0057
0058 #define _PyLong_SMALL_INTS _Py_SINGLETON(small_ints)
0059
0060 // _PyLong_GetZero() and _PyLong_GetOne() must always be available
0061 // _PyLong_FromUnsignedChar must always be available
0062 #if _PY_NSMALLPOSINTS < 257
0063 #  error "_PY_NSMALLPOSINTS must be greater than or equal to 257"
0064 #endif
0065
0066 // Return a reference to the immortal zero singleton.
0067 // The function cannot return NULL.
0068 static inline PyObject* _PyLong_GetZero(void)
0069 { return (PyObject *)&_PyLong_SMALL_INTS[_PY_NSMALLNEGINTS]; }
0070
0071 // Return a reference to the immortal one singleton.
0072 // The function cannot return NULL.
0073 static inline PyObject* _PyLong_GetOne(void)
0074 { return (PyObject *)&_PyLong_SMALL_INTS[_PY_NSMALLNEGINTS+1]; }
0075
0076 static inline PyObject* _PyLong_FromUnsignedChar(unsigned char i)
0077 {
0078     return (PyObject *)&_PyLong_SMALL_INTS[_PY_NSMALLNEGINTS+i];
0079 }
0080
0081 // _PyLong_Frexp returns a double x and an exponent e such that the
0082 // true value is approximately equal to x * 2**e.  e is >= 0.  x is
0083 // 0.0 if and only if the input is 0 (in which case, e and x are both
0084 // zeroes); otherwise, 0.5 <= abs(x) < 1.0.  On overflow, which is
0085 // possible if the number of bits doesn't fit into a Py_ssize_t, sets
0086 // OverflowError and returns -1.0 for x, 0 for e.
0087 //
0088 // Export for 'math' shared extension
0089 PyAPI_DATA(double) _PyLong_Frexp(PyLongObject *a, Py_ssize_t *e);
0090
0091 extern PyObject* _PyLong_FromBytes(const char *, Py_ssize_t, int);
0092
0093 // _PyLong_DivmodNear.  Given integers a and b, compute the nearest
0094 // integer q to the exact quotient a / b, rounding to the nearest even integer
0095 // in the case of a tie.  Return (q, r), where r = a - q*b.  The remainder r
0096 // will satisfy abs(r) <= abs(b)/2, with equality possible only if q is
0097 // even.
0098 //
0099 // Export for '_datetime' shared extension.
0100 PyAPI_DATA(PyObject*) _PyLong_DivmodNear(PyObject *, PyObject *);
0101
0102 // _PyLong_Format: Convert the long to a string object with given base,
0103 // appending a base prefix of 0[box] if base is 2, 8 or 16.
0104 // Export for '_tkinter' shared extension.
0105 PyAPI_DATA(PyObject*) _PyLong_Format(PyObject *obj, int base);
0106
0107 // Export for 'math' shared extension
0108 PyAPI_DATA(PyObject*) _PyLong_Rshift(PyObject *, size_t);
0109
0110 // Export for 'math' shared extension
0111 PyAPI_DATA(PyObject*) _PyLong_Lshift(PyObject *, size_t);
0112
0113 PyAPI_FUNC(PyObject*) _PyLong_Add(PyLongObject *left, PyLongObject *right);
0114 PyAPI_FUNC(PyObject*) _PyLong_Multiply(PyLongObject *left, PyLongObject *right);
0115 PyAPI_FUNC(PyObject*) _PyLong_Subtract(PyLongObject *left, PyLongObject *right);
0116
0117 // Export for 'binascii' shared extension.
0118 PyAPI_DATA(unsigned char) _PyLong_DigitValue[256];
0119
0120 /* Format the object based on the format_spec, as defined in PEP 3101
0121    (Advanced String Formatting). */
0122 extern int _PyLong_FormatAdvancedWriter(
0123     _PyUnicodeWriter *writer,
0124     PyObject *obj,
0125     PyObject *format_spec,
0126     Py_ssize_t start,
0127     Py_ssize_t end);
0128
0129 extern int _PyLong_FormatWriter(
0130     _PyUnicodeWriter *writer,
0131     PyObject *obj,
0132     int base,
0133     int alternate);
0134
0135 extern char* _PyLong_FormatBytesWriter(
0136     _PyBytesWriter *writer,
0137     char *str,
0138     PyObject *obj,
0139     int base,
0140     int alternate);
0141
0142 // Argument converters used by Argument Clinic
0143
0144 // Export for 'select' shared extension (Argument Clinic code)
0145 PyAPI_FUNC(int) _PyLong_UnsignedShort_Converter(PyObject *, void *);
0146
0147 // Export for '_testclinic' shared extension (Argument Clinic code)
0148 PyAPI_FUNC(int) _PyLong_UnsignedInt_Converter(PyObject *, void *);
0149
0150 // Export for '_blake2' shared extension (Argument Clinic code)
0151 PyAPI_FUNC(int) _PyLong_UnsignedLong_Converter(PyObject *, void *);
0152
0153 // Export for '_blake2' shared extension (Argument Clinic code)
0154 PyAPI_FUNC(int) _PyLong_UnsignedLongLong_Converter(PyObject *, void *);
0155
0156 // Export for '_testclinic' shared extension (Argument Clinic code)
0157 PyAPI_FUNC(int) _PyLong_Size_t_Converter(PyObject *, void *);
0158
0159 /* Long value tag bits:
0160  * 0-1: Sign bits value = (1-sign), ie. negative=2, positive=0, zero=1.
0161  * 2: Reserved for immortality bit
0162  * 3+ Unsigned digit count
0163  */
0164 #define SIGN_MASK 3
0165 #define SIGN_ZERO 1
0166 #define SIGN_NEGATIVE 2
0167 #define NON_SIZE_BITS 3
0168
0169 /* The functions _PyLong_IsCompact and _PyLong_CompactValue are defined
0170  * in Include/cpython/longobject.h, since they need to be inline.
0171  *
0172  * "Compact" values have at least one bit to spare,
0173  * so that addition and subtraction can be performed on the values
0174  * without risk of overflow.
0175  *
0176  * The inline functions need tag bits.
0177  * For readability, rather than do `#define SIGN_MASK _PyLong_SIGN_MASK`
0178  * we define them to the numbers in both places and then assert that
0179  * they're the same.
0180  */
0181 #if SIGN_MASK != _PyLong_SIGN_MASK
0182 #  error "SIGN_MASK does not match _PyLong_SIGN_MASK"
0183 #endif
0184 #if NON_SIZE_BITS != _PyLong_NON_SIZE_BITS
0185 #  error "NON_SIZE_BITS does not match _PyLong_NON_SIZE_BITS"
0186 #endif
0187
0188 /* All *compact" values are guaranteed to fit into
0189  * a Py_ssize_t with at least one bit to spare.
0190  * In other words, for 64 bit machines, compact
0191  * will be signed 63 (or fewer) bit values
0192  */
0193
0194 /* Return 1 if the argument is compact int */
0195 static inline int
0196 _PyLong_IsNonNegativeCompact(const PyLongObject* op) {
0197     assert(PyLong_Check(op));
0198     return op->long_value.lv_tag <= (1 << NON_SIZE_BITS);
0199 }
0200
0201
0202 static inline int
0203 _PyLong_BothAreCompact(const PyLongObject* a, const PyLongObject* b) {
0204     assert(PyLong_Check(a));
0205     assert(PyLong_Check(b));
0206     return (a->long_value.lv_tag | b->long_value.lv_tag) < (2 << NON_SIZE_BITS);
0207 }
0208
0209 static inline bool
0210 _PyLong_IsZero(const PyLongObject *op)
0211 {
0212     return (op->long_value.lv_tag & SIGN_MASK) == SIGN_ZERO;
0213 }
0214
0215 static inline bool
0216 _PyLong_IsNegative(const PyLongObject *op)
0217 {
0218     return (op->long_value.lv_tag & SIGN_MASK) == SIGN_NEGATIVE;
0219 }
0220
0221 static inline bool
0222 _PyLong_IsPositive(const PyLongObject *op)
0223 {
0224     return (op->long_value.lv_tag & SIGN_MASK) == 0;
0225 }
0226
0227 static inline Py_ssize_t
0228 _PyLong_DigitCount(const PyLongObject *op)
0229 {
0230     assert(PyLong_Check(op));
0231     return op->long_value.lv_tag >> NON_SIZE_BITS;
0232 }
0233
0234 /* Equivalent to _PyLong_DigitCount(op) * _PyLong_NonCompactSign(op) */
0235 static inline Py_ssize_t
0236 _PyLong_SignedDigitCount(const PyLongObject *op)
0237 {
0238     assert(PyLong_Check(op));
0239     Py_ssize_t sign = 1 - (op->long_value.lv_tag & SIGN_MASK);
0240     return sign * (Py_ssize_t)(op->long_value.lv_tag >> NON_SIZE_BITS);
0241 }
0242
0243 static inline int
0244 _PyLong_CompactSign(const PyLongObject *op)
0245 {
0246     assert(PyLong_Check(op));
0247     assert(_PyLong_IsCompact(op));
0248     return 1 - (op->long_value.lv_tag & SIGN_MASK);
0249 }
0250
0251 static inline int
0252 _PyLong_NonCompactSign(const PyLongObject *op)
0253 {
0254     assert(PyLong_Check(op));
0255     assert(!_PyLong_IsCompact(op));
0256     return 1 - (op->long_value.lv_tag & SIGN_MASK);
0257 }
0258
0259 /* Do a and b have the same sign? */
0260 static inline int
0261 _PyLong_SameSign(const PyLongObject *a, const PyLongObject *b)
0262 {
0263     return (a->long_value.lv_tag & SIGN_MASK) == (b->long_value.lv_tag & SIGN_MASK);
0264 }
0265
0266 #define TAG_FROM_SIGN_AND_SIZE(sign, size) ((1 - (sign)) | ((size) << NON_SIZE_BITS))
0267
0268 static inline void
0269 _PyLong_SetSignAndDigitCount(PyLongObject *op, int sign, Py_ssize_t size)
0270 {
0271     assert(size >= 0);
0272     assert(-1 <= sign && sign <= 1);
0273     assert(sign != 0 || size == 0);
0274     op->long_value.lv_tag = TAG_FROM_SIGN_AND_SIZE(sign, (size_t)size);
0275 }
0276
0277 static inline void
0278 _PyLong_SetDigitCount(PyLongObject *op, Py_ssize_t size)
0279 {
0280     assert(size >= 0);
0281     op->long_value.lv_tag = (((size_t)size) << NON_SIZE_BITS) | (op->long_value.lv_tag & SIGN_MASK);
0282 }
0283
0284 #define NON_SIZE_MASK ~((1 << NON_SIZE_BITS) - 1)
0285
0286 static inline void
0287 _PyLong_FlipSign(PyLongObject *op) {
0288     unsigned int flipped_sign = 2 - (op->long_value.lv_tag & SIGN_MASK);
0289     op->long_value.lv_tag &= NON_SIZE_MASK;
0290     op->long_value.lv_tag |= flipped_sign;
0291 }
0292
0293 #define _PyLong_DIGIT_INIT(val) \
0294     { \
0295         .ob_base = _PyObject_HEAD_INIT(&PyLong_Type), \
0296         .long_value  = { \
0297             .lv_tag = TAG_FROM_SIGN_AND_SIZE( \
0298                 (val) == 0 ? 0 : ((val) < 0 ? -1 : 1), \
0299                 (val) == 0 ? 0 : 1), \
0300             { ((val) >= 0 ? (val) : -(val)) }, \
0301         } \
0302     }
0303
0304 #define _PyLong_FALSE_TAG TAG_FROM_SIGN_AND_SIZE(0, 0)
0305 #define _PyLong_TRUE_TAG TAG_FROM_SIGN_AND_SIZE(1, 1)
0306
0307 #ifdef __cplusplus
0308 }
0309 #endif
0310 #endif /* !Py_INTERNAL_LONG_H */