org.cryptimeleon.math.structures.rings

Interface RingElement

All Superinterfaces:

Element, Representable, UniqueByteRepresentable

All Known Subinterfaces:

FieldElement

All Known Implementing Classes:

BooleanElement, ExtensionFieldElement, IntegerElement, PolynomialRing.Polynomial, ProductRingElement, Zn.ZnElement, Zp.ZpElement

public interface RingElement
extends Element

Immutable objects representing a ring element.

Method Summary

Modifier and Type	Method and Description
RingElement	add(Element e) Computes \(\text{this} + e\).
default java.math.BigInteger	asInteger() Interprets this element as an integer.
default RingElement	div(Element e) Computes \(\text{this} / e = \text{this} \cdot e^{-1}\).
boolean	divides(RingElement e) Returns true iff there exists an \(x\) in the ring such that \(\text{this} \cdot x = e\).
RingElement[]	divideWithRemainder(RingElement e) Divides this by e with remainder, returning both quotient and remainder.
java.math.BigInteger	getRank() Implements the euclidean function of a euclidean domain.
Ring	getStructure() Returns the Structure that this Element belongs to.
RingElement	inv() Computes the multiplicative inverse of this element.
default boolean	isOne() Returns true iff this is the one element of the ring.
default boolean	isUnit() Determines whether an element has a multiplicative inverse.
default boolean	isZero() Returns true iff this is the zero element of the ring.
default RingElement	mul(java.math.BigInteger k) Computes \(\text{this} \cdot k\) (equivalent to \(\text{this} + \text{this} + \cdots\) k-times).
RingElement	mul(Element e) Computes \(\text{this} \cdot e\).
default RingElement	mul(long k) Computes \(\text{this} \cdot k\) (equivalent to \(\text{this} + \text{this} + \cdots\) k-times).
RingElement	neg() Computes the additive inverse of this element.
default RingElement	pow(java.math.BigInteger k) Calculates \(\text{this}^k\).
default RingElement	pow(long k) Calculates \(\text{this}^k\).
default RingElement	square() Computes \(\text{this}^2\).
default RingElement	sub(Element e) Computes \(\text{this} - e\).
default GroupElement	toAdditiveGroupElement() Interprets this element as an element of this rings additive group.
default GroupElement	toUnitGroupElement() Interprets this element as an element of this ring's unit group.

Methods inherited from interface org.cryptimeleon.math.structures.Element

equals, hashCode

Methods inherited from interface org.cryptimeleon.math.serialization.Representable

getRepresentation

Methods inherited from interface org.cryptimeleon.math.hash.UniqueByteRepresentable

getUniqueByteRepresentation, updateAccumulator

Method Detail

getStructure

Ring getStructure()

Description copied from interface: Element

Returns the Structure that this Element belongs to.

Specified by:

getStructure in interface Element

toUnitGroupElement

default GroupElement toUnitGroupElement()

Interprets this element as an element of this ring's unit group.

toAdditiveGroupElement

default GroupElement toAdditiveGroupElement()

Interprets this element as an element of this rings additive group.

add

RingElement add(Element e)

Computes \(\text{this} + e\).

Parameters:

e - the addend

Returns:

the result

neg

RingElement neg()

Computes the additive inverse of this element.

Returns:

the result

sub

default RingElement sub(Element e)

Computes \(\text{this} - e\).

Parameters:

e - the subtrahend

Returns:

the result

mul

RingElement mul(Element e)

Computes \(\text{this} \cdot e\).

Parameters:

e - the factor

Returns:

the result

mul

default RingElement mul(java.math.BigInteger k)

Computes \(\text{this} \cdot k\) (equivalent to \(\text{this} + \text{this} + \cdots\) k-times).

Parameters:

k - the factor

Returns:

the result

mul

default RingElement mul(long k)

Computes \(\text{this} \cdot k\) (equivalent to \(\text{this} + \text{this} + \cdots\) k-times).

Parameters:

k - the factor

Returns:

the result

pow

default RingElement pow(java.math.BigInteger k)

Calculates \(\text{this}^k\).

Note that \(a^0 = 1\) for any \(a\) in the ring, particularly \(0^0 = 1\).

pow

default RingElement pow(long k)

Calculates \(\text{this}^k\).

Note that \(a^0 = 1\) for any \(a\) in the ring, particularly \(0^0 = 1\).

inv

RingElement inv()
         throws java.lang.UnsupportedOperationException

Computes the multiplicative inverse of this element.

Returns:

the result

Throws:

java.lang.UnsupportedOperationException - if this is not a unit

isUnit

default boolean isUnit()

Determines whether an element has a multiplicative inverse.

Returns:

true if the element has a multiplicative inverse, else false.

div

default RingElement div(Element e)
                 throws java.lang.IllegalArgumentException

Computes \(\text{this} / e = \text{this} \cdot e^{-1}\).

Parameters:

e - the divisor

Returns:

the result

Throws:

java.lang.IllegalArgumentException - if e is not a unit

divides

boolean divides(RingElement e)
         throws java.lang.UnsupportedOperationException

Returns true iff there exists an \(x\) in the ring such that \(\text{this} \cdot x = e\).

Throws:

java.lang.UnsupportedOperationException - if this cannot be decided (efficiently)

divideWithRemainder

RingElement[] divideWithRemainder(RingElement e)
                           throws java.lang.UnsupportedOperationException,
                                  java.lang.IllegalArgumentException

Divides this by e with remainder, returning both quotient and remainder.

Specifically, returns an array result such that the first entry contains the quotient and the second entry the remainder. Furthermore, result[1].getRank() < e.getRank() or result[1] = 0.

This definition implies that the remainder is zero if and only if e divides this element.

Throws:

java.lang.UnsupportedOperationException - if the ring is not a euclidean domain

java.lang.IllegalArgumentException - if e is zero

getRank

java.math.BigInteger getRank()
                      throws java.lang.UnsupportedOperationException

Implements the euclidean function of a euclidean domain.

The euclidean function is a function from \(R \setminus \{0\}\) to \(\mathbb{N}_0\) such that

• a.getRank() >= 0 for any a in the ring
• a.mul(b).getRank() >= a.getRank() for any a, b != 0
• the remainder rank after divideWithRemainder is less than the divisor's rank

For example, for a polynomial ring this corresponds to the degree of the polynomial.

The rank of the zero element is undefined (no guarantee as to what this method returns in that case).

Throws:

java.lang.UnsupportedOperationException - if the ring is not a euclidean domain

isZero

default boolean isZero()

Returns true iff this is the zero element of the ring.

isOne

default boolean isOne()

Returns true iff this is the one element of the ring.

square

default RingElement square()

Computes \(\text{this}^2\).

Useful if the ring allows squaring to be more efficiently implemented than general exponentiation.

asInteger

default java.math.BigInteger asInteger()
                                throws java.lang.UnsupportedOperationException

Interprets this element as an integer.

Result will be between 0 and the ring's characteristic.

Formally, this method shall return the inverse of Ring.getElement(BigInteger), i.e. x.getStructure().getElement(x.asInteger()).equals(x) (if asInteger() doesn't throw an exception).

Returns:

the integer corresponding to this element

Throws:

java.lang.UnsupportedOperationException - if no such element exists or cannot be efficiently computed