.. _reference.calculators: =========== Calculators =========== .. php:namespace:: Ramsey\Uuid\Math .. php:interface:: CalculatorInterface Provides functionality for performing mathematical calculations. .. php:method:: add($augend, ...$addends) :param Ramsey\\Uuid\\Type\\NumberInterface $augend: The first addend (the integer being added to) :param Ramsey\\Uuid\\Type\\NumberInterface ...$addends: The additional integers to a add to the augend :returns: The sum of all the parameters :returntype: Ramsey\\Uuid\\Type\\NumberInterface .. php:method:: subtract($minuend, ...$subtrahends) :param Ramsey\\Uuid\\Type\\NumberInterface $minuend: The integer being subtracted from :param Ramsey\\Uuid\\Type\\NumberInterface ...$subtrahends: The integers to subtract from the minuend :returns: The difference after subtracting all parameters :returntype: Ramsey\\Uuid\\Type\\NumberInterface .. php:method:: multiply($multiplicand, ...$multipliers) :param Ramsey\\Uuid\\Type\\NumberInterface $multiplicand: The integer to be multiplied :param Ramsey\\Uuid\\Type\\NumberInterface ...$multipliers: The factors by which to multiply the multiplicand :returns: The product of multiplying all the provided parameters :returntype: Ramsey\\Uuid\\Type\\NumberInterface .. php:method:: divide($roundingMode, $scale, $dividend, ...$divisors) :param int $roundingMode: The strategy for rounding the quotient; one of the :php:class:`Ramsey\\Uuid\\Math\\RoundingMode` constants :param int $scale: The scale to use for the operation :param Ramsey\\Uuid\\Type\\NumberInterface $dividend: The integer to be divided :param Ramsey\\Uuid\\Type\\NumberInterface ...$divisors: The integers to divide ``$dividend`` by, in the order in which the division operations should take place (left-to-right) :returns: The quotient of dividing the provided parameters left-to-right :returntype: Ramsey\\Uuid\\Type\\NumberInterface .. php:method:: fromBase($value, $base) Converts a value from an arbitrary base to a base-10 integer value. :param string $value: The value to convert :param int $base: The base to convert from (i.e., 2, 16, 32, etc.) :returns: The base-10 integer value of the converted value :returntype: Ramsey\\Uuid\\Type\\Integer .. php:method:: toBase($value, $base) Converts a base-10 integer value to an arbitrary base. :param Ramsey\\Uuid\\Type\\Integer $value: The integer value to convert :param int $base: The base to convert to (i.e., 2, 16, 32, etc.) :returns: The value represented in the specified base :returntype: ``string`` .. php:method:: toHexadecimal($value) Converts an Integer instance to a Hexadecimal instance. :param Ramsey\\Uuid\\Type\\Integer $value: The Integer to convert to Hexadecimal :returntype: Ramsey\\Uuid\\Type\\Hexadecimal .. php:method:: toInteger($value) Converts a Hexadecimal instance to an Integer instance. :param Ramsey\\Uuid\\Type\\Hexadecimal $value: The Hexadecimal to convert to Integer :returntype: Ramsey\\Uuid\\Type\\Integer .. php:class:: RoundingMode .. php:const:: UNNECESSARY Asserts that the requested operation has an exact result, hence no rounding is necessary. .. php:const:: UP Rounds away from zero. Always increments the digit prior to a nonzero discarded fraction. Note that this rounding mode never decreases the magnitude of the calculated value. .. php:const:: DOWN Rounds towards zero. Never increments the digit prior to a discarded fraction (i.e., truncates). Note that this rounding mode never increases the magnitude of the calculated value. .. php:const:: CEILING Rounds towards positive infinity. If the result is positive, behaves as for :php:const:`UP <Ramsey\\Uuid\\Math\\RoundingMode::UP>`; if negative, behaves as for :php:const:`DOWN <Ramsey\\Uuid\\Math\\RoundingMode::DOWN>`. Note that this rounding mode never decreases the calculated value. .. php:const:: FLOOR Rounds towards negative infinity. If the result is positive, behave as for :php:const:`DOWN <Ramsey\\Uuid\\Math\\RoundingMode::DOWN>`; if negative, behave as for :php:const:`UP <Ramsey\\Uuid\\Math\\RoundingMode::UP>`. Note that this rounding mode never increases the calculated value. .. php:const:: HALF_UP Rounds towards "nearest neighbor" unless both neighbors are equidistant, in which case round up. Behaves as for :php:const:`UP <Ramsey\\Uuid\\Math\\RoundingMode::UP>` if the discarded fraction is >= 0.5; otherwise, behaves as for :php:const:`DOWN <Ramsey\\Uuid\\Math\\RoundingMode::DOWN>`. Note that this is the rounding mode commonly taught at school. .. php:const:: HALF_DOWN Rounds towards "nearest neighbor" unless both neighbors are equidistant, in which case round down. Behaves as for :php:const:`UP <Ramsey\\Uuid\\Math\\RoundingMode::UP>` if the discarded fraction is > 0.5; otherwise, behaves as for :php:const:`DOWN <Ramsey\\Uuid\\Math\\RoundingMode::DOWN>`. .. php:const:: HALF_CEILING Rounds towards "nearest neighbor" unless both neighbors are equidistant, in which case round towards positive infinity. If the result is positive, behaves as for :php:const:`HALF_UP <Ramsey\\Uuid\\Math\\RoundingMode::HALF_UP>`; if negative, behaves as for :php:const:`HALF_DOWN <Ramsey\\Uuid\\Math\\RoundingMode::HALF_DOWN>`. .. php:const:: HALF_FLOOR Rounds towards "nearest neighbor" unless both neighbors are equidistant, in which case round towards negative infinity. If the result is positive, behaves as for :php:const:`HALF_DOWN <Ramsey\\Uuid\\Math\\RoundingMode::HALF_DOWN>`; if negative, behaves as for :php:const:`HALF_UP <Ramsey\\Uuid\\Math\\RoundingMode::HALF_UP>`. .. php:const:: HALF_EVEN Rounds towards the "nearest neighbor" unless both neighbors are equidistant, in which case rounds towards the even neighbor. Behaves as for :php:const:`HALF_UP <Ramsey\\Uuid\\Math\\RoundingMode::HALF_UP>` if the digit to the left of the discarded fraction is odd; behaves as for :php:const:`HALF_DOWN <Ramsey\\Uuid\\Math\\RoundingMode::HALF_DOWN>` if it's even. Note that this is the rounding mode that statistically minimizes cumulative error when applied repeatedly over a sequence of calculations. It is sometimes known as "Banker's rounding", and is chiefly used in the USA.