GF2nElement (Bouncy Castle Library 1.54 API Specification)
Date: 2015-12-29

org.bouncycastle.pqc.math.linearalgebra

## Class GF2nElement

- java.lang.Object
- - org.bouncycastle.pqc.math.linearalgebra.GF2nElement

- All Implemented Interfaces:
    GFElement
  Direct Known Subclasses:
    GF2nONBElement, GF2nPolynomialElement

      public abstract class GF2nElement
      extends java.lang.Object
      implements GFElement

  This abstract class implements an element of the finite field GF(2)n in either optimal normal basis representation (ONB) or in polynomial representation. It is extended by the classes `GF2nONBElement` and `GF2nPolynomialElement` .
  See Also:
    `GF2nPolynomialElement`, `GF2nONBElement`, `GF2nONBField`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected int` | `mDegree` holds the extension degree n of this element's corresponding field.
    `protected GF2nField` | `mField` holds a pointer to this element's corresponding field.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `GF2nElement()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract java.lang.Object` | `clone()`
    `GF2nElement` | `convert(GF2nField basis)` Performs a basis transformation of this element to the given GF2nField `basis`.
    `GF2nField` | `getField()` Returns the field of this element.
    `abstract GF2nElement` | `increase()` Returns `this` element + 1.
    `abstract void` | `increaseThis()` Increases this element by one.
    `abstract GF2nElement` | `solveQuadraticEquation()` Solves a quadratic equation.
    `abstract GF2nElement` | `square()` Returns `this` element to the power of 2.
    `abstract GF2nElement` | `squareRoot()` Compute the square root of this element and return the result in a new `GF2nElement`.
    `abstract void` | `squareRootThis()` Compute the square root of this element.
    `abstract void` | `squareThis()` Squares `this` element.
    `GFElement` | `subtract(GFElement minuend)` Compute the difference of this element and `minuend`.
    `void` | `subtractFromThis(GFElement minuend)` Compute the difference of this element and `minuend`, overwriting this element.
    `abstract boolean` | `testRightmostBit()` Returns whether the rightmost bit of the bit representation is set.
    `abstract int` | `trace()` Returns the trace of this element.

    - ### Methods inherited from class java.lang.Object

      `equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface org.bouncycastle.pqc.math.linearalgebra.GFElement

      `add, addToThis, equals, hashCode, invert, isOne, isZero, multiply, multiplyThisBy, toByteArray, toFlexiBigInt, toString, toString`

- - ### Field Detail

    - #### mField

          protected GF2nField mField

      holds a pointer to this element's corresponding field.

    - #### mDegree

          protected int mDegree

      holds the extension degree n of this element's corresponding field.

  - ### Constructor Detail

    - #### GF2nElement

          public GF2nElement()

  - ### Method Detail

    - #### clone

          public abstract java.lang.Object clone()

      Specified by:
        `clone` in interface `GFElement`
      Overrides:
        `clone` in class `java.lang.Object`
      Returns:
        a copy of this GF2nElement

    - #### testRightmostBit

          public abstract boolean testRightmostBit()

      Returns whether the rightmost bit of the bit representation is set. This is needed for data conversion according to 1363.
      Returns:
        true if the rightmost bit of this element is set

    - #### getField

          public final GF2nField getField()

      Returns the field of this element.
      Returns:
        the field of this element

    - #### increase

          public abstract GF2nElement increase()

      Returns `this` element + 1.
      Returns:
        `this` + 1

    - #### increaseThis

          public abstract void increaseThis()

      Increases this element by one.

    - #### subtract

          public final GFElement subtract(GFElement minuend)
                                   throws java.lang.RuntimeException

      Compute the difference of this element and `minuend`.
      Specified by:
        `subtract` in interface `GFElement`
      Parameters:
        `minuend` - the minuend
      Returns:
        `this - minuend` (newly created)
      Throws:
        `DifferentFieldsException` - if the elements are of different fields.
        `java.lang.RuntimeException`

    - #### subtractFromThis

          public final void subtractFromThis(GFElement minuend)

      Compute the difference of this element and `minuend`, overwriting this element.
      Specified by:
        `subtractFromThis` in interface `GFElement`
      Parameters:
        `minuend` - the minuend
      Throws:
        `DifferentFieldsException` - if the elements are of different fields.

    - #### square

          public abstract GF2nElement square()

      Returns `this` element to the power of 2.
      Returns:
        `this`2

    - #### squareThis

          public abstract void squareThis()

      Squares `this` element.

    - #### squareRoot

          public abstract GF2nElement squareRoot()

      Compute the square root of this element and return the result in a new `GF2nElement`.
      Returns:
        `this1/2` (newly created)

    - #### squareRootThis

          public abstract void squareRootThis()

      Compute the square root of this element.

    - #### convert

          public final GF2nElement convert(GF2nField basis)
                                    throws java.lang.RuntimeException

      Performs a basis transformation of this element to the given GF2nField `basis`.
      Parameters:
        `basis` - the GF2nField representation to transform this element to
      Returns:
        this element in the representation of `basis`
      Throws:
        `DifferentFieldsException` - if `this` cannot be converted according to `basis`.
        `java.lang.RuntimeException`

    - #### trace

          public abstract int trace()

      Returns the trace of this element.
      Returns:
        the trace of this element

    - #### solveQuadraticEquation

          public abstract GF2nElement solveQuadraticEquation()
                                                      throws java.lang.RuntimeException

      Solves a quadratic equation.
      Let z2 + z = `this`. Then this method returns z.
      Returns:
        z with z2 + z = `this`
      Throws:
        `NoSolutionException` - if z2 + z = `this` does not have a solution
        `java.lang.RuntimeException`