/*
 * Copyright (c) 2018, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package sun.security.util.math;

import java.math.BigInteger;

The base interface for integers modulo a prime value. Objects of this
type may be either mutable or immutable, and subinterfaces can be used
to specify that an object is mutable or immutable. This type should never
be used to declare local/member variables, but it may be used for
formal parameters of a method. None of the methods in this interface
modify the value of arguments or this.
The behavior of this interface depends on the particular implementation.
For example, some implementations only support a limited number of add
operations before each multiply operation. See the documentation of the
implementation for details.
See Also:
ImmutableIntegerModuloP
MutableIntegerModuloP/**
 * The base interface for integers modulo a prime value. Objects of this
 * type may be either mutable or immutable, and subinterfaces can be used
 * to specify that an object is mutable or immutable. This type should never
 * be used to declare local/member variables, but it may be used for
 * formal parameters of a method. None of the methods in this interface
 * modify the value of arguments or this.
 *
 * The behavior of this interface depends on the particular implementation.
 * For example, some implementations only support a limited number of add
 * operations before each multiply operation. See the documentation of the
 * implementation for details.
 *
 * @see ImmutableIntegerModuloP
 * @see MutableIntegerModuloP
 */
public interface IntegerModuloP {

    
Get the field associated with this element.
Returns:
the field/**
     * Get the field associated with this element.
     *
     * @return the field
     */
    IntegerFieldModuloP getField();

    
Get the canonical value of this element as a BigInteger. This value
will always be in the range [0, p), where p is the prime that defines
the field. This method performs reduction and other computation to
produce the result.
Returns:
the value as a BigInteger/**
     * Get the canonical value of this element as a BigInteger. This value
     * will always be in the range [0, p), where p is the prime that defines
     * the field. This method performs reduction and other computation to
     * produce the result.
     *
     * @return the value as a BigInteger
     */
    BigInteger asBigInteger();

    
Return this value as a fixed (immutable) element. This method will
copy the underlying representation if the object is mutable.
Returns:
a fixed element with the same value/**
     * Return this value as a fixed (immutable) element. This method will
     * copy the underlying representation if the object is mutable.
     *
     * @return a fixed element with the same value
     */
    ImmutableIntegerModuloP fixed();

    
Return this value as a mutable element. This method will always copy
the underlying representation.
Returns:
a mutable element with the same value/**
     * Return this value as a mutable element. This method will always copy
     * the underlying representation.
     *
     * @return a mutable element with the same value
     */
    MutableIntegerModuloP mutable();

    
Add this field element with the supplied element and return the result.
Params:
b – the sumand
Returns:
this + b/**
     * Add this field element with the supplied element and return the result.
     *
     * @param b the sumand
     * @return this + b
     */
    ImmutableIntegerModuloP add(IntegerModuloP b);

    
Compute the additive inverse of the field element
Returns:
the addditiveInverse (0 - this)/**
     * Compute the additive inverse of the field element
     * @return the addditiveInverse (0 - this)
     */
    ImmutableIntegerModuloP additiveInverse();

    
Multiply this field element with the supplied element and return the
result.
Params:
b – the multiplicand
Returns:
this * b/**
     * Multiply this field element with the supplied element and return the
     * result.
     *
     * @param b the multiplicand
     * @return this * b
     */
    ImmutableIntegerModuloP multiply(IntegerModuloP b);

    
Perform an addition modulo a power of two and return the little-endian
encoding of the result. The value is (this' + b') % 2^(8 * len),
where this' and b' are the canonical integer values equivalent to
this and b.
Params:
b – the sumand
len – the length of the desired array
Returns:
a byte array of length len containing the result/**
     * Perform an addition modulo a power of two and return the little-endian
     * encoding of the result. The value is (this' + b') % 2^(8 * len),
     * where this' and b' are the canonical integer values equivalent to
     * this and b.
     *
     * @param b the sumand
     * @param len the length of the desired array
     * @return a byte array of length len containing the result
     */
    byte[] addModPowerTwo(IntegerModuloP b, int len);

    
Perform an addition modulo a power of two and store the little-endian
encoding of the result in the supplied array. The value is
(this' + b') % 2^(8 * result.length), where this' and b' are the
canonical integer values equivalent to this and b.
Params:
b – the sumand
result – an array which stores the result upon return/**
     * Perform an addition modulo a power of two and store the little-endian
     * encoding of the result in the supplied array. The value is
     * (this' + b') % 2^(8 * result.length), where this' and b' are the
     * canonical integer values equivalent to this and b.
     *
     * @param b the sumand
     * @param result an array which stores the result upon return
     */
    void addModPowerTwo(IntegerModuloP b, byte[] result);

    
Returns the little-endian encoding of this' % 2^(8 * len), where this'
is the canonical integer value equivalent to this.
Params:
len – the length of the desired array
Returns:
a byte array of length len containing the result/**
     * Returns the little-endian encoding of this' % 2^(8 * len), where this'
     * is the canonical integer value equivalent to this.
     *
     * @param len the length of the desired array
     * @return a byte array of length len containing the result
     */
    byte[] asByteArray(int len);

    
Places the little-endian encoding of this' % 2^(8 * result.length)
into the supplied array, where this' is the canonical integer value
equivalent to this.
Params:
result – an array which stores the result upon return/**
     * Places the little-endian encoding of this' % 2^(8 * result.length)
     * into the supplied array, where this' is the canonical integer value
     * equivalent to this.
     *
     * @param result an array which stores the result upon return
     */
    void asByteArray(byte[] result);

    
Compute the multiplicative inverse of this field element.
Returns:
the multiplicative inverse (1 / this)/**
     * Compute the multiplicative inverse of this field element.
     *
     * @return the multiplicative inverse (1 / this)
     */
    ImmutableIntegerModuloP multiplicativeInverse();

    
Subtract the supplied element from this one and return the result.
Params:
b – the subtrahend
Returns:
the difference (this - b)/**
     * Subtract the supplied element from this one and return the result.
     * @param b the subtrahend
     *
     * @return the difference (this - b)
     */
    ImmutableIntegerModuloP subtract(IntegerModuloP b);

    
Calculate the square of this element and return the result. This method
should be used instead of a.multiply(a) because implementations may
include optimizations that only apply to squaring.
Returns:
the product (this * this)/**
     * Calculate the square of this element and return the result. This method
     * should be used instead of a.multiply(a) because implementations may
     * include optimizations that only apply to squaring.
     *
     * @return the product (this * this)
     */
    ImmutableIntegerModuloP square();

    
Calculate the power this^b and return the result.
Params:
b – the exponent
Returns:
the value of this^b/**
     * Calculate the power this^b and return the result.
     *
     * @param b the exponent
     * @return the value of this^b
     */
    ImmutableIntegerModuloP pow(BigInteger b);

}