package org.bouncycastle.pqc.math.linearalgebra;

import java.math.BigInteger;


This interface defines a finite field element. It is implemented by the class GF2nElement. 
See Also:
GF2nElement/**
 * This interface defines a finite field element. It is implemented by the
 * class {@link GF2nElement}.
 *
 * @see GF2nElement
 */
public interface GFElement
{

    
Returns:
a copy of this GFElement/**
     * @return a copy of this GFElement
     */
    Object clone();

    // /////////////////////////////////////////////////////////////////
    // comparison
    // /////////////////////////////////////////////////////////////////

    
Compare this curve with another object.
Params:
other – the other object
Returns:
the result of the comparison/**
     * Compare this curve with another object.
     *
     * @param other the other object
     * @return the result of the comparison
     */
    boolean equals(Object other);

    
Returns:
the hash code of this element/**
     * @return the hash code of this element
     */
    int hashCode();

    
Checks whether this element is zero.
Returns:
true if this is the zero element/**
     * Checks whether this element is zero.
     *
     * @return <tt>true</tt> if <tt>this</tt> is the zero element
     */
    boolean isZero();

    
Checks whether this element is one.
Returns:
true if this is the one element/**
     * Checks whether this element is one.
     *
     * @return <tt>true</tt> if <tt>this</tt> is the one element
     */
    boolean isOne();

    // /////////////////////////////////////////////////////////////////////
    // arithmetic
    // /////////////////////////////////////////////////////////////////////

    
Compute the sum of this element and the addend.
Params:
addend – the addend
Returns:
this + other (newly created)/**
     * Compute the sum of this element and the addend.
     *
     * @param addend the addend
     * @return <tt>this + other</tt> (newly created)
     */
    GFElement add(GFElement addend)
        throws RuntimeException;

    
Compute the sum of this element and the addend, overwriting this element.
Params:
addend – the addend/**
     * Compute the sum of this element and the addend, overwriting this element.
     *
     * @param addend the addend
     */
    void addToThis(GFElement addend)
        throws RuntimeException;

    
Compute the difference of this element and minuend.
Params:
minuend – the minuend
Returns:
this - minuend (newly created)/**
     * Compute the difference of this element and <tt>minuend</tt>.
     *
     * @param minuend the minuend
     * @return <tt>this - minuend</tt> (newly created)
     */
    GFElement subtract(GFElement minuend)
        throws RuntimeException;

    
Compute the difference of this element and minuend,
overwriting this element.
Params:
minuend – the minuend/**
     * Compute the difference of this element and <tt>minuend</tt>,
     * overwriting this element.
     *
     * @param minuend the minuend
     */
    void subtractFromThis(GFElement minuend);

    
Compute the product of this element and factor.
Params:
factor – the factor
Returns:
this * factor (newly created)/**
     * Compute the product of this element and <tt>factor</tt>.
     *
     * @param factor the factor
     * @return <tt>this * factor</tt> (newly created)
     */
    GFElement multiply(GFElement factor)
        throws RuntimeException;

    
Compute this * factor (overwrite this).
Params:
factor – the factor/**
     * Compute <tt>this * factor</tt> (overwrite <tt>this</tt>).
     *
     * @param factor the factor
     */
    void multiplyThisBy(GFElement factor)
        throws RuntimeException;

    
Compute the multiplicative inverse of this element.
Throws:
ArithmeticException – if this is the zero element.
Returns:
this-1 (newly created)/**
     * Compute the multiplicative inverse of this element.
     *
     * @return <tt>this<sup>-1</sup></tt> (newly created)
     * @throws ArithmeticException if <tt>this</tt> is the zero element.
     */
    GFElement invert()
        throws ArithmeticException;

    // /////////////////////////////////////////////////////////////////////
    // conversion
    // /////////////////////////////////////////////////////////////////////

    
Returns this element as FlexiBigInt. The conversion is P1363-conform.
Returns:
this element as BigInt/**
     * Returns this element as FlexiBigInt. The conversion is <a
     * href="http://grouper.ieee.org/groups/1363/">P1363</a>-conform.
     *
     * @return this element as BigInt
     */
    BigInteger toFlexiBigInt();

    
Returns this element as byte array. The conversion is P1363-conform.
Returns:
this element as byte array/**
     * Returns this element as byte array. The conversion is <a href =
     * "http://grouper.ieee.org/groups/1363/">P1363</a>-conform.
     *
     * @return this element as byte array
     */
    byte[] toByteArray();

    
Return a String representation of this element.
Returns:
String representation of this element/**
     * Return a String representation of this element.
     *
     * @return String representation of this element
     */
    String toString();

    
Return a String representation of this element. radix
specifies the radix of the String representation.
Params:
radix – specifies the radix of the String representation
Returns:
String representation of this element with the specified radix/**
     * Return a String representation of this element. <tt>radix</tt>
     * specifies the radix of the String representation.
     *
     * @param radix specifies the radix of the String representation
     * @return String representation of this element with the specified radix
     */
    String toString(int radix);

}