php-uuid/docs/reference/calculators.rst

.. _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.