Ring (rings 2.2 API)

Type Parameters:

E - the type of objects that may be operated by this ring

All Superinterfaces:

Comparator<E>, ElementParser<E>, Iterable<E>, Serializable, ToStringSupport<E>

All Known Subinterfaces:

IPolynomialRing<Poly>

All Known Implementing Classes:

ARing, FiniteField, Integers, IntegersZp, MultivariateRing, Rationals, UnivariateRing
```
public interface Ring<E>
extends Comparator<E>, Iterable<E>, ToStringSupport<E>, ElementParser<E>, Serializable
```
Ring of elements. Mathematical operations defined in Ring interface include all field operations, though the particular implementations may represent a more restricted rings (general rings, Euclidean rings etc.), in which case some field operations (e.g. reciprocal) are not applicable (will throw exception).

Since:

1.0

Field Summary
- Fields inherited from interface cc.redberry.rings.ToStringSupport
  plain

Method Summary

All Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`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(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[]`	`createArray(int length)` Creates generic array of ring elements of specified length
`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`	`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`	`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 {@code valueOf(1) * valueOf(2) * ....
`default FactorDecomposition<E>`	`factorSquareFree(E element)` Square-free factorization of specified element
`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 a, E b)` Returns the least common multiple of two elements
`default E`	`multiply(E... elements)` Multiplies the array of elements
`E`	`multiply(E a, E b)` Multiplies two 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, BigInteger exponent)` Returns `base` in a power of `exponent` (non negative)
`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`	`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`	`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`
`default String`	`toString(E element)` Gives string representation of specified element
`E`	`valueOf(E val)` Converts a value from other ring to this ring.
`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`	`valueOfBigInteger(BigInteger val)` Returns ring element associated with specified integer

Methods inherited from interface java.util.Comparator
compare, comparing, comparing, comparingDouble, comparingInt, comparingLong, equals, naturalOrder, nullsFirst, nullsLast, reversed, reverseOrder, thenComparing, thenComparing, thenComparing, thenComparingDouble, thenComparingInt, thenComparingLong

Methods inherited from interface java.lang.Iterable
forEach, spliterator

Methods inherited from interface cc.redberry.rings.ToStringSupport
plain, withVariables

- 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... 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
  - 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
  - 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
  - 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
  - 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
  - factor
```
default FactorDecomposition<E> factor(E element)
```
    Factor 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.
    
    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
  - parse
```
default E parse(String string)
```
    Parse string into ring element
    
    Specified by:
    
    parse in interface ElementParser<E>
    
    Parameters:
    
    string - string
    
    Returns:
    
    ring element
  - 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
  - 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
  - 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
  - toString
```
default String toString(E element)
```
    Description copied from interface: ToStringSupport
    
    Gives string representation of specified element
    
    Specified by:
    
    toString in interface ToStringSupport<E>
    
    Parameters:
    
    element - the element
    
    Returns:
    
    string representation

Interface Ring<E>

Field Summary

Fields inherited from interface cc.redberry.rings.ToStringSupport

Method Summary

Methods inherited from interface java.util.Comparator

Methods inherited from interface java.lang.Iterable

Methods inherited from interface cc.redberry.rings.ToStringSupport

Method Detail

isField

isEuclideanRing

isFinite

isFiniteField

cardinality

characteristic

isPerfectPower

perfectPowerBase

perfectPowerExponent

add

add

increment

decrement

subtract

multiply

multiply

negate

addMutable

subtractMutable

multiplyMutable

negateMutable

copy

signum

divideAndRemainder

quotient

remainder

divideOrNull

divideExact

reciprocal

gcd

extendedGCD

lcm

gcd

gcd

factorSquareFree

factor

getZero

getOne

getNegativeOne

isZero

isOne

isUnit

isUnitOrZero

isMinusOne

valueOf

valueOfBigInteger

valueOf

valueOf

setToValueOf

parse

createArray

createArray2d

createArray2d

createZeroesArray

createArray

createArray

createArray

pow

pow

pow

factorial

iterator

randomElement

randomElement

randomNonZeroElement

toString