`number.md`

272 строк · 26.2 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/2.6/c-api/number.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Протокол чисел89**int `PyNumber_Check`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o*)**1011Возвращает1213`1`1415, если объект1617*o*1819предоставляет числовые протоколы, и false в противном случае. Эта функция всегда завершается успешно.2021**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_Add`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o2*)**2223*Возвращаемое значение: новая ссылка.*2425Возвращает результат сложения *o1* и *o2* или *NULL* в случае ошибки. Это эквивалент выражения Python `o1 + o2`.2627**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_Subtract`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o2*)**2829*Возвращаемое значение: новая ссылка.*3031Возвращает результат вычитания *o2* из *o1* или *NULL* в случае ошибки. Это эквивалент выражения Python `o1 - o2`.3233**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_Multiply`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o2*)**3435*Возвращаемое значение: новая ссылка.*3637Возвращает результат умножения *o1* и *o2* или *NULL* в случае ошибки. Это эквивалент выражения Python `o1 * o2`.3839**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_Divide`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o2*)**4041*Возвращаемое значение: новая ссылка.*4243Возвращает результат деления *o1* на *o2* или *NULL* в случае ошибки. Это эквивалент выражения Python `o1 / o2`.4445**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_FloorDivide`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o2*)**4647*Возвращаемое значение: новая ссылка.*4849Возвращает целую часть от деления *o1* на *o2* или *NULL* в случае ошибки. Эквивалентно «классическому» делению целых чисел.5051Новое в версии 2.2.5253**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_TrueDivide`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o2*)**5455*Возвращаемое значение: новая ссылка.*5657Возвращает разумное приближение математического значения от деления *o1* на *o2* или *NULL* в случае ошибки. Возвращаемое значение является «приблизительным», потому что числа с плавающей запятой в двоичном представлении приблизительны; невозможно представить все действительные числа в двоичной системе. Эта функция может вернуть значение с плавающей запятой, если ей переданы два целых числа.5859Новое в версии 2.2.6061**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_Remainder`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o2*)**6263*Возвращаемое значение: новая ссылка.*6465Возвращает остаток от деления *o1* на *o2* или *NULL* в случае ошибки. Это эквивалент выражения Python `o1 % o2`.6667**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_Divmod`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o2*)**6869*Возвращаемое значение: новая ссылка.*7071См. встроенную функцию [`divmod()`](https://python-all.ru/2.6/library/functions.html#divmod). Возвращает *NULL* в случае ошибки. Это эквивалент выражения Python `divmod(o1, o2)`.7273**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_Power`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o2*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o3*)**7475*Возвращаемое значение: новая ссылка.*7677См. встроенную функцию [`pow()`](https://python-all.ru/2.6/library/functions.html#pow). Возвращает *NULL* в случае ошибки. Это эквивалент выражения Python `pow(o1, o2, o3)`, где *o3* необязателен. Если *o3* нужно игнорировать, передайте [`Py_None`](https://python-all.ru/2.6/c-api/none.html#Py_None) вместо него (передача *NULL* для *o3* привела бы к недопустимому доступу к памяти).7879**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_Negative`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o*)**8081*Возвращаемое значение: новая ссылка.*8283Возвращает отрицание *o* в случае успеха или *NULL* в случае ошибки. Это эквивалент выражения Python `-o`.8485**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_Positive`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o*)**8687*Возвращаемое значение: новая ссылка.*8889Возвращает *o* в случае успеха или *NULL* в случае ошибки. Это эквивалент выражения Python `+o`.9091**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_Absolute`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o*)**9293*Возвращаемое значение: новая ссылка.*9495Возвращает абсолютное значение *o* или *NULL* в случае ошибки. Это эквивалент выражения Python `abs(o)`.9697**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_Invert`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o*)**9899*Возвращаемое значение: новая ссылка.*100101Возвращает побитовое отрицание *o* в случае успеха или *NULL* в случае ошибки. Это эквивалент выражения Python `~o`.102103**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_Lshift`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o2*)**104105*Возвращаемое значение: новая ссылка.*106107Возвращает результат сдвига *o1* влево на *o2* в случае успеха или *NULL* в случае ошибки. Это эквивалент выражения Python `o1 << o2`.108109**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_Rshift`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o2*)**110111*Возвращаемое значение: новая ссылка.*112113Возвращает результат сдвига *o1* вправо на *o2* в случае успеха или *NULL* в случае ошибки. Это эквивалент выражения Python `o1 >> o2`.114115**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_And`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o2*)**116117*Возвращаемое значение: новая ссылка.*118119Возвращает побитовое И (and) *o1* и *o2* в случае успеха или *NULL* в случае ошибки. Это эквивалент выражения Python `o1 & o2`.120121**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_Xor`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o2*)**122123*Возвращаемое значение: новая ссылка.*124125Возвращает побитовое исключающее ИЛИ (xor) *o1* и *o2* в случае успеха или *NULL* в случае ошибки. Это эквивалент выражения Python `o1 ^ o2`.126127**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_Or`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o2*)**128129*Возвращаемое значение: новая ссылка.*130131Возвращает «побитовое ИЛИ» *o1* и *o2* в случае успеха или *NULL* при ошибке. Это эквивалент выражения Python `o1 | o2`.132133**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_InPlaceAdd`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o2*)**134135*Возвращаемое значение: новая ссылка.*136137Возвращает результат сложения *o1* и *o2* или *NULL* при ошибке. Операция выполняется *на месте (in-place)*, если *o1* это поддерживает. Это эквивалент оператора Python `o1 += o2`.138139**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_InPlaceSubtract`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o2*)**140141*Возвращаемое значение: новая ссылка.*142143Возвращает результат вычитания *o2* из *o1* или *NULL* при ошибке. Операция выполняется *на месте (in-place)*, если *o1* это поддерживает. Это эквивалент оператора Python `o1 -= o2`.144145**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_InPlaceMultiply`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o2*)**146147*Возвращаемое значение: новая ссылка.*148149Возвращает результат умножения *o1* и *o2* или *NULL* при ошибке. Операция выполняется *на месте (in-place)*, если *o1* это поддерживает. Это эквивалент оператора Python `o1 *= o2`.150151**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_InPlaceDivide`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o2*)**152153*Возвращаемое значение: новая ссылка.*154155Возвращает результат деления *o1* на *o2* или *NULL* в случае ошибки. Операция выполняется *на месте*, если *o1* это поддерживает. Это эквивалент оператора Python `o1 /= o2`.156157**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_InPlaceFloorDivide`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o2*)**158159*Возвращаемое значение: новая ссылка.*160161Возвращает результат целочисленного деления с округлением вниз (floor) *o1* на *o2* или *NULL* при ошибке. Операция выполняется *на месте (in-place)*, если *o1* это поддерживает. Это эквивалент оператора Python `o1 //= o2`.162163Новое в версии 2.2.164165**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_InPlaceTrueDivide`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o2*)**166167*Возвращаемое значение: новая ссылка.*168169Возвращает разумное приближение математического значения от деления *o1* на *o2* или *NULL* в случае ошибки. Возвращаемое значение является «приблизительным», потому что числа с плавающей запятой в двоичном представлении приблизительны; невозможно представить все действительные числа в двоичной системе. Эта функция может вернуть значение с плавающей запятой, если ей переданы два целых числа. Операция выполняется *на месте*, если *o1* это поддерживает.170171Новое в версии 2.2.172173**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_InPlaceRemainder`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o2*)**174175*Возвращаемое значение: новая ссылка.*176177Возвращает остаток от деления *o1* на *o2* или *NULL* при ошибке. Операция выполняется *на месте (in-place)*, если *o1* это поддерживает. Это эквивалент оператора Python `o1 %= o2`.178179**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_InPlacePower`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o2*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o3*)**180181*Возвращаемое значение: новая ссылка.*182183См. встроенную функцию [`pow()`](https://python-all.ru/2.6/library/functions.html#pow). Возвращает *NULL* при ошибке. Операция выполняется *на месте (in-place)*, если *o1* это поддерживает. Это эквивалент оператора Python `o1 **= o2`, когда o3 равен [`Py_None`](https://python-all.ru/2.6/c-api/none.html#Py_None), или вариант на месте (in-place) для `pow(o1, o2, o3)` в противном случае. Если *o3* нужно игнорировать, передайте [`Py_None`](https://python-all.ru/2.6/c-api/none.html#Py_None) вместо него (передача *NULL* для *o3* приведет к недопустимому доступу к памяти).184185**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_InPlaceLshift`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o2*)**186187*Возвращаемое значение: новая ссылка.*188189Возвращает результат сдвига *o1* влево на *o2* в случае успеха или *NULL* при ошибке. Операция выполняется *на месте (in-place)*, если *o1* это поддерживает. Это эквивалент оператора Python `o1 <<= o2`.190191**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_InPlaceRshift`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o2*)**192193*Возвращаемое значение: новая ссылка.*194195Возвращает результат сдвига *o1* вправо на *o2* в случае успеха или *NULL* при ошибке. Операция выполняется *на месте (in-place)*, если *o1* это поддерживает. Это эквивалент оператора Python `o1 >>= o2`.196197**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_InPlaceAnd`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o2*)**198199*Возвращаемое значение: новая ссылка.*200201Возвращает результат побитового И (bitwise and) *o1* и *o2* в случае успеха или *NULL* при ошибке. Операция выполняется *на месте (in-place)*, если *o1* это поддерживает. Это эквивалент оператора Python `o1 &= o2`.202203**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_InPlaceXor`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o2*)**204205*Возвращаемое значение: новая ссылка.*206207Возвращает результат побитового исключающего ИЛИ (bitwise exclusive or) *o1* и *o2* в случае успеха или *NULL* при ошибке. Операция выполняется *на месте (in-place)*, если *o1* это поддерживает. Это эквивалент оператора Python `o1 ^= o2`.208209**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_InPlaceOr`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o1*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o2*)**210211*Возвращаемое значение: новая ссылка.*212213Возвращает «побитовое ИЛИ» *o1* и *o2* в случае успеха или *NULL* при ошибке. Операция выполняется *на месте (in-place)*, если *o1* это поддерживает. Это эквивалент оператора Python `o1 |= o2`.214215**int `PyNumber_Coerce`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*\*p1*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*\*p2*)**216217Эта функция принимает адреса двух переменных типа [`PyObject*`](https://python-all.ru/2.6/c-api/structures.html#PyObject). Если объекты, на которые указывают `*p1` и `*p2`, имеют один и тот же тип, увеличивает их счетчик ссылок и возвращает `0` (успех). Если объекты могут быть преобразованы к общему числовому типу, заменяет `*p1` и `*p2` на их преобразованные значения (с «новыми» счетчиками ссылок) и возвращает `0`. Если преобразование невозможно или произошла какая-либо другая ошибка, возвращает `-1` (неудача) и не увеличивает счетчики ссылок. Вызов `PyNumber_Coerce(&o1, &o2)` эквивалентен оператору Python `o1, o2 = coerce(o1, o2)`.218219**int `PyNumber_CoerceEx`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*\*p1*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*\*p2*)**220221Эта функция похожа на222223[`PyNumber_Coerce()`](https://python-all.ru/2.6/c-api/number.html#PyNumber_Coerce)224225, за исключением того, что возвращает226227`1`228229, когда преобразование невозможно и при этом не возникает ошибки. Счетчики ссылок в этом случае по-прежнему не увеличиваются.230231**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_Int`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o*)**232233*Возвращаемое значение: новая ссылка.*234235Возвращает *o*, преобразованный в целочисленный объект, в случае успеха, или *NULL* при неудаче. Если аргумент выходит за пределы диапазона целых чисел, вместо него будет возвращен объект long. Это эквивалент выражения Python `int(o)`.236237**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_Long`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o*)**238239*Возвращаемое значение: новая ссылка.*240241Возвращает *o*, преобразованный в объект длинного целого, в случае успеха, или *NULL* при неудаче. Это эквивалент выражения Python `long(o)`.242243**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_Float`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o*)**244245*Возвращаемое значение: новая ссылка.*246247Возвращает *o*, преобразованный в число с плавающей точкой (объект float) в случае успеха, или *NULL* при ошибке. Это эквивалент выражения Python `float(o)`.248249**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_Index`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o*)**250251Возвращает *o*, преобразованный в Python int или long, в случае успеха, или *NULL* с возбужденным исключением [`TypeError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.TypeError) при неудаче.252253Новое в версии 2.5.254255**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyNumber_ToBase`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*n*, int *base*)**256257Возвращает целое число *n*, преобразованное в строку в системе счисления *base* с префиксом `'0b'`, `'0o'` или `'0x'`, если применимо. Если *base* не равно 2, 8, 10 или 16, используется формат `'x#num'`, где x – это основание. Если *n* не является объектом int, он сначала преобразуется с помощью [`PyNumber_Index()`](https://python-all.ru/2.6/c-api/number.html#PyNumber_Index).258259Новое в версии 2.6.260261**Py\_ssize\_t `PyNumber_AsSsize_t`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*exc*)**262263Возвращает *o*, преобразованный в значение Py\_ssize\_t, если *o* можно интерпретировать как целое число. Если *o* может быть преобразован в Python int или long, но попытка преобразовать в значение Py\_ssize\_t приведет к возбуждению [`OverflowError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.OverflowError), то аргумент *exc* – это тип исключения, которое будет возбуждено (обычно [`IndexError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.IndexError) или [`OverflowError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.OverflowError)). Если *exc* равен *NULL*, то исключение очищается, а значение усекается до *PY\_SSIZE\_T\_MIN* для отрицательного целого или *PY\_SSIZE\_T\_MAX* для положительного целого.264265Новое в версии 2.5.266267**int `PyIndex_Check`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*o*)**268269Возвращает True, если *o* является индексным целым числом (т.е. имеет заполненный слот nb\_index в структуре tp\_as\_number).270271Новое в версии 2.5.272