Package cc.redberry.rings

Interface Ring<E>

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      default E abs​(E el)
      Returns the abs value of element (no copy)
      default E add​(E... elements)
      Total of the array of elements
      E add​(E a, E b)
      Add two elements
      default E addMutable​(E a, E b)
      Adds two elements and destroys the initial content of a.
      BigInteger cardinality()
      Returns the number of elements in this ring (cardinality) or null if ring is infinite
      BigInteger characteristic()
      Returns characteristic of this ring
      E copy​(E element)
      Makes a deep copy of the specified element (for immutable instances the same reference returned).
      default E[] createArray​(int length)
      Creates generic array of ring elements of specified length
      default E[] createArray​(E element)
      Creates generic array with single element
      default E[] createArray​(E a, E b)
      Creates generic array of {a, b}
      default E[] createArray​(E a, E b, E c)
      Creates generic array of {a, b, c}
      default E[][] createArray2d​(int length)
      Creates 2d array of ring elements of specified length
      default E[][] createArray2d​(int m, int n)
      Creates 2d array of ring elements of specified shape
      default E[] createZeroesArray​(int length)
      Creates array filled with zero elements
      default E[][] createZeroesArray2d​(int m, int n)
      Creates 2d array of ring elements of specified shape filled with zero elements
      default E decrement​(E element)
      Returns element - 1
      E[] divideAndRemainder​(E dividend, E divider)
      Returns quotient and remainder of dividend / divider
      default E divideExact​(E dividend, E divider)
      Divides dividend by divider or throws ArithmeticException if exact division is not possible
      default E divideExactMutable​(E dividend, E divider)
      Internal API
      default E divideOrNull​(E dividend, E divider)
      Divides dividend by divider or returns null if exact division is not possible
      default E[] extendedGCD​(E a, E b)
      Returns array of [gcd(a,b), s, t] such that s * a + t * b = gcd(a, b)
      default FactorDecomposition<E> factor​(E element)
      Factor specified element
      default E factorial​(long num)
      Gives a product of valueOf(1) * valueOf(2) * .... * valueOf(num)
      default FactorDecomposition<E> factorSquareFree​(E element)
      Square-free factorization of specified element
      default void fillZeros​(E[] array)
      Fills array with zeros
      default E[] firstBezoutCoefficient​(E a, E b)
      Returns array of [gcd(a,b), s] such that s * a + t * b = gcd(a, b)
      default E gcd​(E... elements)
      Returns greatest common divisor of specified elements
      default E gcd​(E a, E b)
      Returns the greatest common divisor of two elements
      default E gcd​(Iterable<E> elements)
      Returns greatest common divisor of specified elements
      default E getNegativeOne()
      Returns negative unit element of this ring (minus one)
      E getOne()
      Returns unit element of this ring (one)
      E getZero()
      Returns zero element of this ring
      default E increment​(E element)
      Returns element + 1
      boolean isEuclideanRing()
      Returns whether this ring is a Euclidean ring
      boolean isField()
      Returns whether this ring is a field
      default boolean isFinite()
      Returns whether this ring is finite
      default boolean isFiniteField()
      Returns whether this ring is a finite field
      default boolean isMinusOne​(E e)
      Tests whether specified element is minus one
      boolean isOne​(E element)
      Tests whether specified element is one (exactly)
      boolean isPerfectPower()
      Returns whether the cardinality is a perfect power (p^k with k > 1)
      boolean isUnit​(E element)
      Tests whether specified element is a ring unit
      default boolean isUnitOrZero​(E element)
      Tests whether specified element is a ring unit or zero
      boolean isZero​(E element)
      Tests whether specified element is zero
      Iterator<E> iterator()
      Returns iterator over ring elements (for finite rings, otherwise throws exception)
      default E lcm​(E... elements)
      Returns the least common multiple of two elements
      default E lcm​(E a, E b)
      Returns the least common multiple of two elements
      default E lcm​(Iterable<E> elements)
      Returns the least common multiple of two elements
      default E max​(E a, E b)
      Returns the max value (no copy)
      default E min​(E a, E b)
      Returns the min value (no copy)
      default E multiply​(E... elements)
      Multiplies the array of elements
      default E multiply​(E a, long b)
      Multiplies two elements
      E multiply​(E a, E b)
      Multiplies two elements
      default E multiply​(Iterable<E> elements)
      Multiplies the array of elements
      default E multiplyMutable​(E a, E b)
      Multiplies two elements and destroys the initial content of a
      E negate​(E element)
      Negates the given element
      default E negateMutable​(E element)
      Negates the given element and destroys the initial content of element
      default E parse​(String string)
      Parse string into ring element
      BigInteger perfectPowerBase()
      Returns base so that cardinality == base^exponent or null if cardinality is not finite
      BigInteger perfectPowerExponent()
      Returns exponent so that cardinality == base^exponent or null if cardinality is not finite
      default E pow​(E base, int exponent)
      Returns base in a power of exponent (non negative)
      default E pow​(E base, long exponent)
      Returns base in a power of exponent (non negative)
      default E pow​(E base, BigInteger exponent)
      Returns base in a power of exponent (non negative)
      default E quotient​(E dividend, E divider)
      Returns the quotient of dividend / divider
      default E randomElement()
      Returns a random element from this ring
      default E randomElement​(org.apache.commons.math3.random.RandomGenerator rnd)
      Returns a random element from this ring
      default E randomElementTree()
      If this ring has a complicated nested structure, this method guaranties that the resulting random element will reflect ring complicated structure, i.e.
      default E randomElementTree​(org.apache.commons.math3.random.RandomGenerator rnd)
      If this ring has a complicated nested structure, this method guaranties that the resulting random element will reflect ring complicated structure, i.e.
      default E randomNonZeroElement​(org.apache.commons.math3.random.RandomGenerator rnd)
      Returns a random non zero element from this ring
      E reciprocal​(E element)
      Gives the inverse element element ^ (-1)
      default E remainder​(E dividend, E divider)
      Returns the remainder of dividend / divider
      default void setToValueOf​(E[] elements)
      Applies valueOf(Object) inplace to the specified array
      default int signum​(E element)
      Returns -1 if element < 0, 0 if element == 0 and 1 if element > 0, where comparison is specified by Comparator.compare(Object, Object)
      E subtract​(E a, E b)
      Subtracts b from a
      default E subtractMutable​(E a, E b)
      Subtracts b from a and destroys the initial content of a
      E valueOf​(long val)
      Returns ring element associated with specified long
      default E[] valueOf​(long[] elements)
      Converts array of machine integers to ring elements via valueOf(long)
      E valueOf​(E val)
      Converts a value from other ring to this ring.
      E valueOfBigInteger​(BigInteger val)
      Returns ring element associated with specified integer

    • Method Detail

      • isField

        boolean isField()
        Returns whether this ring is a field
        Returns:
        whether this ring is a field

      • isEuclideanRing

        boolean isEuclideanRing()
        Returns whether this ring is a Euclidean ring
        Returns:
        whether this ring is a Euclidean ring

      • isFinite

        default boolean isFinite()
        Returns whether this ring is finite
        Returns:
        whether this ring is finite

      • isFiniteField

        default boolean isFiniteField()
        Returns whether this ring is a finite field
        Returns:
        whether this ring is a finite field

      • cardinality

        BigInteger cardinality()
        Returns the number of elements in this ring (cardinality) or null if ring is infinite
        Returns:
        the number of elements in this ring (cardinality) or null if ring is infinite

      • characteristic

        BigInteger characteristic()
        Returns characteristic of this ring
        Returns:
        characteristic of this ring

      • isPerfectPower

        boolean isPerfectPower()
        Returns whether the cardinality is a perfect power (p^k with k > 1)
        Returns:
        whether the cardinality is a perfect power (p^k with k > 1)

      • perfectPowerBase

        BigInteger perfectPowerBase()
        Returns base so that cardinality == base^exponent or null if cardinality is not finite
        Returns:
        base so that cardinality == base^exponent or null if cardinality is not finite

      • perfectPowerExponent

        BigInteger perfectPowerExponent()
        Returns exponent so that cardinality == base^exponent or null if cardinality is not finite
        Returns:
        exponent so that cardinality == base^exponent or null if cardinality is not finite

      • add

        E add​(E a,
      E b)
        Add two elements
        Parameters:
        a - the first element
        b - the second element
        Returns:
        a + b

      • add

        default E add​(E... elements)
        Total of the array of elements
        Parameters:
        elements - elements to sum
        Returns:
        sum of the array

      • increment

        default E increment​(E element)
        Returns element + 1
        Parameters:
        element - the element
        Returns:
        element + 1

      • decrement

        default E decrement​(E element)
        Returns element - 1
        Parameters:
        element - the element
        Returns:
        element - 1

      • subtract

        E subtract​(E a,
           E b)
        Subtracts b from a
        Parameters:
        a - the first element
        b - the second element
        Returns:
        a - b

      • multiply

        E multiply​(E a,
           E b)
        Multiplies two elements
        Parameters:
        a - the first element
        b - the second element
        Returns:
        a * b

      • multiply

        default E multiply​(E a,
                   long b)
        Multiplies two elements
        Parameters:
        a - the first element
        b - the second element
        Returns:
        a * b

      • multiply

        default E multiply​(E... elements)
        Multiplies the array of elements
        Parameters:
        elements - the elements
        Returns:
        product of the array

      • multiply

        default E multiply​(Iterable<E> elements)
        Multiplies the array of elements
        Parameters:
        elements - the elements
        Returns:
        product of the array

      • negate

        E negate​(E element)
        Negates the given element
        Parameters:
        element - the ring element
        Returns:
        -val

      • addMutable

        default E addMutable​(E a,
                     E b)
        Adds two elements and destroys the initial content of a.
        Parameters:
        a - the first element (may be destroyed)
        b - the second element
        Returns:
        a + b

      • subtractMutable

        default E subtractMutable​(E a,
                          E b)
        Subtracts b from a and destroys the initial content of a
        Parameters:
        a - the first element (may be destroyed)
        b - the second element
        Returns:
        a - b

      • multiplyMutable

        default E multiplyMutable​(E a,
                          E b)
        Multiplies two elements and destroys the initial content of a
        Parameters:
        a - the first element (may be destroyed)
        b - the second element
        Returns:
        a * b

      • negateMutable

        default E negateMutable​(E element)
        Negates the given element and destroys the initial content of element
        Parameters:
        element - the ring element (may be destroyed)
        Returns:
        -element

      • copy

        E copy​(E element)
        Makes a deep copy of the specified element (for immutable instances the same reference returned).
        Parameters:
        element - the element
        Returns:
        deep copy of specified element

      • signum

        default int signum​(E element)
        Returns -1 if element < 0, 0 if element == 0 and 1 if element > 0, where comparison is specified by Comparator.compare(Object, Object)
        Parameters:
        element - the element
        Returns:
        -1 if element < 0, 0 if element == 0 and 1 otherwise

      • abs

        default E abs​(E el)
        Returns the abs value of element (no copy)

      • max

        default E max​(E a,
              E b)
        Returns the max value (no copy)

      • min

        default E min​(E a,
              E b)
        Returns the min value (no copy)

      • divideAndRemainder

        E[] divideAndRemainder​(E dividend,
                       E divider)
        Returns quotient and remainder of dividend / divider
        Parameters:
        dividend - the dividend
        divider - the divider
        Returns:
        {quotient, remainder}

      • quotient

        default E quotient​(E dividend,
                   E divider)
        Returns the quotient of dividend / divider
        Parameters:
        dividend - the dividend
        divider - the divider
        Returns:
        the quotient of dividend / divider

      • remainder

        default E remainder​(E dividend,
                    E divider)
        Returns the remainder of dividend / divider
        Parameters:
        dividend - the dividend
        divider - the divider
        Returns:
        the remainder of dividend / divider

      • divideOrNull

        default E divideOrNull​(E dividend,
                       E divider)
        Divides dividend by divider or returns null if exact division is not possible
        Parameters:
        dividend - the dividend
        divider - the divider
        Returns:
        dividend / divider or null if exact division is not possible

      • divideExact

        default E divideExact​(E dividend,
                      E divider)
        Divides dividend by divider or throws ArithmeticException if exact division is not possible
        Parameters:
        dividend - the dividend
        divider - the divider
        Returns:
        dividend / divider
        Throws:
        ArithmeticException - if exact division is not possible

      • divideExactMutable

        default E divideExactMutable​(E dividend,
                             E divider)
        Internal API

      • reciprocal

        E reciprocal​(E element)
        Gives the inverse element element ^ (-1)
        Parameters:
        element - the element
        Returns:
        element ^ (-1)

      • gcd

        default E gcd​(E a,
              E b)
        Returns the greatest common divisor of two elements
        Parameters:
        a - the first element
        b - the second element
        Returns:
        gcd

      • extendedGCD

        default E[] extendedGCD​(E a,
                        E b)
        Returns array of [gcd(a,b), s, t] such that s * a + t * b = gcd(a, b)
        Throws:
        UnsupportedOperationException - if this is not the Euclidean ring and there is no special implementation provided by particular subtype

      • firstBezoutCoefficient

        default E[] firstBezoutCoefficient​(E a,
                                   E b)
        Returns array of [gcd(a,b), s] such that s * a + t * b = gcd(a, b)
        Parameters:
        a - the first ring element (for which the Bezout coefficient is computed)
        b - the second ring element
        Returns:
        array of [gcd(a,b), s] such that s * a + t * b = gcd(a, b)

      • lcm

        default E lcm​(E a,
              E b)
        Returns the least common multiple of two elements
        Parameters:
        a - the first element
        b - the second element
        Returns:
        lcm

      • lcm

        default E lcm​(E... elements)
        Returns the least common multiple of two elements
        Parameters:
        elements - the elements
        Returns:
        lcm

      • lcm

        default E lcm​(Iterable<E> elements)
        Returns the least common multiple of two elements
        Parameters:
        elements - the elements
        Returns:
        lcm

      • gcd

        default E gcd​(E... elements)
        Returns greatest common divisor of specified elements
        Parameters:
        elements - the elements
        Returns:
        gcd

      • gcd

        default E gcd​(Iterable<E> elements)
        Returns greatest common divisor of specified elements
        Parameters:
        elements - the elements
        Returns:
        gcd

      • factorSquareFree

        default FactorDecomposition<E> factorSquareFree​(E element)
        Square-free factorization of specified element

      • getZero

        E getZero()
        Returns zero element of this ring
        Returns:
        0

      • getOne

        E getOne()
        Returns unit element of this ring (one)
        Returns:
        1

      • getNegativeOne

        default E getNegativeOne()
        Returns negative unit element of this ring (minus one)
        Returns:
        -1

      • isZero

        boolean isZero​(E element)
        Tests whether specified element is zero
        Parameters:
        element - the ring element
        Returns:
        whether specified element is zero

      • isOne

        boolean isOne​(E element)
        Tests whether specified element is one (exactly)
        Parameters:
        element - the ring element
        Returns:
        whether specified element is exactly one
        See Also:
        isUnit(Object)

      • isUnit

        boolean isUnit​(E element)
        Tests whether specified element is a ring unit
        Parameters:
        element - the ring element
        Returns:
        whether specified element is a ring unit
        See Also:
        isOne(Object)

      • isUnitOrZero

        default boolean isUnitOrZero​(E element)
        Tests whether specified element is a ring unit or zero
        Parameters:
        element - the ring element
        Returns:
        whether specified element is a ring unit or zero

      • isMinusOne

        default boolean isMinusOne​(E e)
        Tests whether specified element is minus one
        Parameters:
        e - the ring element
        Returns:
        whether specified element is minus one

      • valueOf

        E valueOf​(long val)
        Returns ring element associated with specified long
        Parameters:
        val - machine integer
        Returns:
        ring element associated with specified long

      • valueOfBigInteger

        E valueOfBigInteger​(BigInteger val)
        Returns ring element associated with specified integer
        Parameters:
        val - integer
        Returns:
        ring element associated with specified integer

      • valueOf

        default E[] valueOf​(long[] elements)
        Converts array of machine integers to ring elements via valueOf(long)
        Parameters:
        elements - array of machine integers
        Returns:
        array of ring elements

      • valueOf

        E valueOf​(E val)
        Converts a value from other ring to this ring. The result is not guarantied to be a new instance (i.e. val == valueOf(val) is possible).
        Parameters:
        val - some element from any ring
        Returns:
        this ring element associated with specified val

      • setToValueOf

        default void setToValueOf​(E[] elements)
        Applies valueOf(Object) inplace to the specified array
        Parameters:
        elements - the array

      • createArray

        default E[] createArray​(int length)
        Creates generic array of ring elements of specified length
        Parameters:
        length - array length
        Returns:
        array of ring elements of specified length

      • createArray2d

        default E[][] createArray2d​(int length)
        Creates 2d array of ring elements of specified length
        Parameters:
        length - array length
        Returns:
        2d array of ring elements of specified length

      • createArray2d

        default E[][] createArray2d​(int m,
                            int n)
        Creates 2d array of ring elements of specified shape
        Parameters:
        m - result length
        n - length of each array in the result
        Returns:
        2d array E[m][n]

      • createZeroesArray

        default E[] createZeroesArray​(int length)
        Creates array filled with zero elements
        Parameters:
        length - array length
        Returns:
        array filled with zero elements of specified length

      • fillZeros

        default void fillZeros​(E[] array)
        Fills array with zeros

      • createZeroesArray2d

        default E[][] createZeroesArray2d​(int m,
                                  int n)
        Creates 2d array of ring elements of specified shape filled with zero elements
        Parameters:
        m - result length
        n - length of each array in the result
        Returns:
        2d array E[m][n] filled with zero elements

      • createArray

        default E[] createArray​(E a,
                        E b)
        Creates generic array of {a, b}
        Parameters:
        a - the first element of array
        b - the second element of array
        Returns:
        array {a,b}

      • createArray

        default E[] createArray​(E a,
                        E b,
                        E c)
        Creates generic array of {a, b, c}

      • createArray

        default E[] createArray​(E element)
        Creates generic array with single element
        Parameters:
        element - the element
        Returns:
        array with single specified element

      • pow

        default E pow​(E base,
              int exponent)
        Returns base in a power of exponent (non negative)
        Parameters:
        base - base
        exponent - exponent (non negative)
        Returns:
        base in a power of exponent

      • pow

        default E pow​(E base,
              long exponent)
        Returns base in a power of exponent (non negative)
        Parameters:
        base - base
        exponent - exponent (non negative)
        Returns:
        base in a power of exponent

      • pow

        default E pow​(E base,
              BigInteger exponent)
        Returns base in a power of exponent (non negative)
        Parameters:
        base - base
        exponent - exponent (non negative)
        Returns:
        base in a power of exponent

      • factorial

        default E factorial​(long num)
        Gives a product of valueOf(1) * valueOf(2) * .... * valueOf(num)
        Parameters:
        num - the number
        Returns:
        valueOf(1) * valueOf(2) * .... * valueOf(num)

      • iterator

        Iterator<E> iterator()
        Returns iterator over ring elements (for finite rings, otherwise throws exception)
        Specified by:
        iterator in interface Iterable<E>

      • randomElement

        default E randomElement()
        Returns a random element from this ring
        Returns:
        random element from this ring

      • randomElement

        default E randomElement​(org.apache.commons.math3.random.RandomGenerator rnd)
        Returns a random element from this ring
        Parameters:
        rnd - the source of randomness
        Returns:
        random element from this ring

      • randomElementTree

        default E randomElementTree​(org.apache.commons.math3.random.RandomGenerator rnd)
        If this ring has a complicated nested structure, this method guaranties that the resulting random element will reflect ring complicated structure, i.e. the result will be roughly as complicated as the ring is
        Returns:
        random element from this ring

      • randomElementTree

        default E randomElementTree()
        If this ring has a complicated nested structure, this method guaranties that the resulting random element will reflect ring complicated structure, i.e. the result will be roughly as complicated as the ring is
        Returns:
        random element from this ring

      • randomNonZeroElement

        default E randomNonZeroElement​(org.apache.commons.math3.random.RandomGenerator rnd)
        Returns a random non zero element from this ring
        Parameters:
        rnd - the source of randomness
        Returns:
        random non zero element from this ring

      • parse

        default E parse​(String string)
        Parse string into ring element
        Specified by:
        parse in interface IParser<E>
        Parameters:
        string - string
        Returns:
        ring element
        See Also:
        Coder