phpcommon intmath

phpcommon intmath

Последняя версия: 1.0.0-бета.

Библиотека PHP 5.3+ для арифметических операций с целыми числами, которая переносится при переполнении.

Внимание

Эта библиотека не предназначена для правильного выполнения арифметических операций с целыми числами и не должна использоваться вместо собственных арифметических операторов или любой другой библиотеки, предназначенной для этой цели.

В отличие от других языков, которые переполняют большие положительные целые числа в большие отрицательные целые числа, PHP фактически переполняет целые числа в числа с плавающей запятой. В большинстве случаев арифметические переполнения следует рассматривать как необычные обстоятельства, требующие особого обращения. Однако в некоторых случаях такое циклическое поведение действительно полезно — например, с порядковыми номерами TCP или определенными алгоритмами, такими как вычисление хэша. Этот служебный класс предоставляет базовые арифметические функции, которые работают в соответствии с этим поведением.

Для иллюстрации рассмотрим следующий пример:

 // Output on 64-bit system: float(9.2233720368548E+18)
var_dump ( PHP_MAX_INT + 1 );

// Output on 64-bit system: int(-9223372036854775808)
var_dump (IntMath:: add ( PHP_MAX_INT , 1 ));

Как было показано ранее, добавление единицы к наибольшему целому числу, поддерживаемому с помощью собственных арифметических операторов, приведет к числу с плавающей запятой. Напротив, использование IntMath::add() вызовет переполнение, в результате чего будет получено наименьшее целое число, поддерживаемое в этой сборке PHP.

API подробно документирован в исходном коде. Кроме того, доступна HTML-версия для более удобного просмотра в браузере.

Установка

Используйте Composer для установки пакета:

$ composer require phpcommon/intmath

Операции

В настоящее время поддерживаются только четыре основных арифметических операции (сложение, вычитание, умножение и деление) и отрицание.

Отрицание

Для целочисленных значений отрицание аналогично вычитанию из нуля. Поскольку PHP использует представление целых чисел с дополнением до двух, а диапазон значений с дополнением до двух не симметричен, отрицание максимального отрицательного целого числа приводит к тому же самому максимальному отрицательному числу. Несмотря на то, что произошло переполнение, исключение не создается.

Для всех целых значений $a , -$a равно (~$a) + 1 .

Пример использования API:

 // Outputs int(-100)
var_dump (IntMath:: negate ( 100 ));

Добавление

Результатом сложения двух целых чисел являются младшие биты истинного математического результата, представленного в достаточно широком формате с дополнением до двух. Если происходит переполнение, то знак результата может не совпадать со знаком математической суммы двух значений. Несмотря на переполнение, в этом случае исключение не создается.

Пример использования API:

 // Outputs int(300)
var_dump (IntMath:: add ( 100 , 200 ));

Вычитание

Вычитание положительного числа дает тот же результат, что и сложение отрицательного числа равной величины. Более того, вычитание из нуля аналогично отрицанию. Результатом являются младшие биты истинного математического результата, представленные в достаточно широком формате с двумя дополнениями. Если происходит переполнение, то знак результата может не совпадать со знаком математической разницы двух значений. Несмотря на переполнение, в этом случае исключение не создается.

Пример использования API:

 // Outputs int(90)
IntMath:: subtract ( 100 , 10 );

Умножение

Результатом умножения двух целых чисел являются младшие биты истинного математического результата, представленного в достаточно широком формате с дополнением до двух. Если происходит переполнение, то знак результата может не совпадать со знаком математического произведения двух значений. Несмотря на переполнение, в этом случае исключение не создается.

Пример использования API:

 // Outputs int(200)
IntMath:: multiply ( 100 , 2 );

Разделение

Деление округляет результат в сторону нуля. Таким образом, абсолютное значение результата — это максимально возможное целое число, которое меньше или равно абсолютному значению частного двух операндов. Результат равен нулю или положительному значению, если два операнда имеют одинаковый знак, и нулю или отрицательному результату, если два операнда имеют противоположные знаки.

Есть один особый случай, который не удовлетворяет этому правилу: если делимое представляет собой отрицательное целое число наибольшей возможной величины для своего типа, а делитель равен -1 , то происходит переполнение целого числа и результат равен делимому. Несмотря на переполнение, в этом случае исключение не создается. С другой стороны, если значение делителя в целочисленном делении равно 0 , то генерируется исключение DivisionByZeroException .

Пример использования API:

 // Outputs int(50)
IntMath:: divide ( 100 , 2 );

Журнал изменений

Пожалуйста, посетите CHANGELOG для получения дополнительной информации о том, что изменилось за последнее время.

Тестирование

$ composer test

Для получения более подробной информации ознакомьтесь с тестовой документацией.

Содействие

Вклады в пакет всегда приветствуются!

• Сообщайте о любых ошибках или проблемах, которые вы обнаружите, в системе отслеживания проблем.
• Вы можете получить исходный код в репозитории пакета Git.

Подробную информацию см. в разделах ВКЛАД и ПОВЕДЕНИЕ.

Безопасность

Если вы обнаружите какие-либо проблемы, связанные с безопасностью, отправьте электронное письмо по адресу [email protected] вместо использования системы отслеживания проблем.

Кредиты

• Маркос Пассос

• Все участники

Лицензия

Все содержимое этого пакета лицензируется по лицензии MIT.