/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.commons.math3;

import org.apache.commons.math3.exception.DimensionMismatchException;

Interface representing a real
field.
Type parameters:
<T> – the type of the field elements
See Also:
FieldElement
Since:
3.2/**
 * Interface representing a <a href="http://mathworld.wolfram.com/RealNumber.html">real</a>
 * <a href="http://mathworld.wolfram.com/Field.html">field</a>.
 * @param <T> the type of the field elements
 * @see FieldElement
 * @since 3.2
 */
public interface RealFieldElement<T> extends FieldElement<T> {

    
Get the real value of the number.
Returns:
real value/** Get the real value of the number.
     * @return real value
     */
    double getReal();

    
'+' operator.
Params:
a – right hand side parameter of the operator
Returns:
this+a/** '+' operator.
     * @param a right hand side parameter of the operator
     * @return this+a
     */
    T add(double a);

    
'-' operator.
Params:
a – right hand side parameter of the operator
Returns:
this-a/** '-' operator.
     * @param a right hand side parameter of the operator
     * @return this-a
     */
    T subtract(double a);

    
'×' operator.
Params:
a – right hand side parameter of the operator
Returns:
this×a/** '&times;' operator.
     * @param a right hand side parameter of the operator
     * @return this&times;a
     */
    T multiply(double a);

    
'÷' operator.
Params:
a – right hand side parameter of the operator
Returns:
this÷a/** '&divide;' operator.
     * @param a right hand side parameter of the operator
     * @return this&divide;a
     */
    T divide(double a);

    
IEEE remainder operator.
Params:
a – right hand side parameter of the operator
Returns:
this - n × a where n is the closest integer to this/a
(the even integer is chosen for n if this/a is halfway between two integers)/** IEEE remainder operator.
     * @param a right hand side parameter of the operator
     * @return this - n &times; a where n is the closest integer to this/a
     * (the even integer is chosen for n if this/a is halfway between two integers)
     */
    T remainder(double a);

    
IEEE remainder operator.
Params:
a – right hand side parameter of the operator
Throws:
DimensionMismatchException – if number of free parameters or orders are inconsistent
Returns:
this - n × a where n is the closest integer to this/a
(the even integer is chosen for n if this/a is halfway between two integers)/** IEEE remainder operator.
     * @param a right hand side parameter of the operator
     * @return this - n &times; a where n is the closest integer to this/a
     * (the even integer is chosen for n if this/a is halfway between two integers)
     * @exception DimensionMismatchException if number of free parameters or orders are inconsistent
     */
    T remainder(T a)
        throws DimensionMismatchException;

    
absolute value.
Returns:
abs(this)/** absolute value.
     * @return abs(this)
     */
    T abs();

    
Get the smallest whole number larger than instance.
Returns:
ceil(this)/** Get the smallest whole number larger than instance.
     * @return ceil(this)
     */
    T ceil();

    
Get the largest whole number smaller than instance.
Returns:
floor(this)/** Get the largest whole number smaller than instance.
     * @return floor(this)
     */
    T floor();

    
Get the whole number that is the nearest to the instance, or the even one if x is exactly half way between two integers.
Returns:
a double number r such that r is an integer r - 0.5 ≤ this ≤ r + 0.5/** Get the whole number that is the nearest to the instance, or the even one if x is exactly half way between two integers.
     * @return a double number r such that r is an integer r - 0.5 &le; this &le; r + 0.5
     */
    T rint();

    
Get the closest long to instance value.
Returns:
closest long to getReal()/** Get the closest long to instance value.
     * @return closest long to {@link #getReal()}
     */
    long round();

    
Compute the signum of the instance.
The signum is -1 for negative numbers, +1 for positive numbers and 0 otherwise
Returns:
-1.0, -0.0, +0.0, +1.0 or NaN depending on sign of a/** Compute the signum of the instance.
     * The signum is -1 for negative numbers, +1 for positive numbers and 0 otherwise
     * @return -1.0, -0.0, +0.0, +1.0 or NaN depending on sign of a
     */
    T signum();

    
Returns the instance with the sign of the argument. A NaN sign argument is treated as positive. 
Params:
sign – the sign for the returned value
Returns:
the instance with the same sign as the sign argument/**
     * Returns the instance with the sign of the argument.
     * A NaN {@code sign} argument is treated as positive.
     *
     * @param sign the sign for the returned value
     * @return the instance with the same sign as the {@code sign} argument
     */
    T copySign(T sign);

    
Returns the instance with the sign of the argument. A NaN sign argument is treated as positive. 
Params:
sign – the sign for the returned value
Returns:
the instance with the same sign as the sign argument/**
     * Returns the instance with the sign of the argument.
     * A NaN {@code sign} argument is treated as positive.
     *
     * @param sign the sign for the returned value
     * @return the instance with the same sign as the {@code sign} argument
     */
    T copySign(double sign);

    
Multiply the instance by a power of 2.
Params:
n – power of 2
Returns:
this × 2n/**
     * Multiply the instance by a power of 2.
     * @param n power of 2
     * @return this &times; 2<sup>n</sup>
     */
    T scalb(int n);

    
Returns the hypotenuse of a triangle with sides this and y - sqrt(this2 +y2)
avoiding intermediate overflow or underflow.

 If either argument is infinite, then the result is positive infinity.
 else, if either argument is NaN then the result is NaN.

Params:
y – a value
Throws:
DimensionMismatchException – if number of free parameters or orders are inconsistent
Returns:
sqrt(this2 +y2)/**
     * Returns the hypotenuse of a triangle with sides {@code this} and {@code y}
     * - sqrt(<i>this</i><sup>2</sup>&nbsp;+<i>y</i><sup>2</sup>)
     * avoiding intermediate overflow or underflow.
     *
     * <ul>
     * <li> If either argument is infinite, then the result is positive infinity.</li>
     * <li> else, if either argument is NaN then the result is NaN.</li>
     * </ul>
     *
     * @param y a value
     * @return sqrt(<i>this</i><sup>2</sup>&nbsp;+<i>y</i><sup>2</sup>)
     * @exception DimensionMismatchException if number of free parameters or orders are inconsistent
     */
    T hypot(T y)
        throws DimensionMismatchException;

    
{@inheritDoc} /** {@inheritDoc} */
    T reciprocal();

    
Square root.
Returns:
square root of the instance/** Square root.
     * @return square root of the instance
     */
    T sqrt();

    
Cubic root.
Returns:
cubic root of the instance/** Cubic root.
     * @return cubic root of the instance
     */
    T cbrt();

    
Nth root.
Params:
n – order of the root
Returns:
nth root of the instance/** N<sup>th</sup> root.
     * @param n order of the root
     * @return n<sup>th</sup> root of the instance
     */
    T rootN(int n);

    
Power operation.
Params:
p – power to apply
Returns:
thisp/** Power operation.
     * @param p power to apply
     * @return this<sup>p</sup>
     */
    T pow(double p);

    
Integer power operation.
Params:
n – power to apply
Returns:
thisn/** Integer power operation.
     * @param n power to apply
     * @return this<sup>n</sup>
     */
    T pow(int n);

    
Power operation.
Params:
e – exponent
Throws:
DimensionMismatchException – if number of free parameters or orders are inconsistent
Returns:
thise/** Power operation.
     * @param e exponent
     * @return this<sup>e</sup>
     * @exception DimensionMismatchException if number of free parameters or orders are inconsistent
     */
    T pow(T e)
        throws DimensionMismatchException;

    
Exponential.
Returns:
exponential of the instance/** Exponential.
     * @return exponential of the instance
     */
    T exp();

    
Exponential minus 1.
Returns:
exponential minus one of the instance/** Exponential minus 1.
     * @return exponential minus one of the instance
     */
    T expm1();

    
Natural logarithm.
Returns:
logarithm of the instance/** Natural logarithm.
     * @return logarithm of the instance
     */
    T log();

    
Shifted natural logarithm.
Returns:
logarithm of one plus the instance/** Shifted natural logarithm.
     * @return logarithm of one plus the instance
     */
    T log1p();

//    TODO: add this method in 4.0, as it is not possible to do it in 3.2
//          due to incompatibility of the return type in the Dfp class
//    /** Base 10 logarithm.
//     * @return base 10 logarithm of the instance
//     */
//    T log10();

    
Cosine operation.
Returns:
cos(this)/** Cosine operation.
     * @return cos(this)
     */
    T cos();

    
Sine operation.
Returns:
sin(this)/** Sine operation.
     * @return sin(this)
     */
    T sin();

    
Tangent operation.
Returns:
tan(this)/** Tangent operation.
     * @return tan(this)
     */
    T tan();

    
Arc cosine operation.
Returns:
acos(this)/** Arc cosine operation.
     * @return acos(this)
     */
    T acos();

    
Arc sine operation.
Returns:
asin(this)/** Arc sine operation.
     * @return asin(this)
     */
    T asin();

    
Arc tangent operation.
Returns:
atan(this)/** Arc tangent operation.
     * @return atan(this)
     */
    T atan();

    
Two arguments arc tangent operation.
Params:
x – second argument of the arc tangent
Throws:
DimensionMismatchException – if number of free parameters or orders are inconsistent
Returns:
atan2(this, x)/** Two arguments arc tangent operation.
     * @param x second argument of the arc tangent
     * @return atan2(this, x)
     * @exception DimensionMismatchException if number of free parameters or orders are inconsistent
     */
    T atan2(T x)
        throws DimensionMismatchException;

    
Hyperbolic cosine operation.
Returns:
cosh(this)/** Hyperbolic cosine operation.
     * @return cosh(this)
     */
    T cosh();

    
Hyperbolic sine operation.
Returns:
sinh(this)/** Hyperbolic sine operation.
     * @return sinh(this)
     */
    T sinh();

    
Hyperbolic tangent operation.
Returns:
tanh(this)/** Hyperbolic tangent operation.
     * @return tanh(this)
     */
    T tanh();

    
Inverse hyperbolic cosine operation.
Returns:
acosh(this)/** Inverse hyperbolic cosine operation.
     * @return acosh(this)
     */
    T acosh();

    
Inverse hyperbolic sine operation.
Returns:
asin(this)/** Inverse hyperbolic sine operation.
     * @return asin(this)
     */
    T asinh();

    
Inverse hyperbolic  tangent operation.
Returns:
atanh(this)/** Inverse hyperbolic  tangent operation.
     * @return atanh(this)
     */
    T atanh();

    
Compute a linear combination.
Params:
a – Factors.
b – Factors.
Throws:
DimensionMismatchException – if arrays dimensions don't match
Returns:
Σi ai bi.
Since:
3.2/**
     * Compute a linear combination.
     * @param a Factors.
     * @param b Factors.
     * @return <code>&Sigma;<sub>i</sub> a<sub>i</sub> b<sub>i</sub></code>.
     * @throws DimensionMismatchException if arrays dimensions don't match
     * @since 3.2
     */
    T linearCombination(T[] a, T[] b)
        throws DimensionMismatchException;

    
Compute a linear combination.
Params:
a – Factors.
b – Factors.
Throws:
DimensionMismatchException – if arrays dimensions don't match
Returns:
Σi ai bi.
Since:
3.2/**
     * Compute a linear combination.
     * @param a Factors.
     * @param b Factors.
     * @return <code>&Sigma;<sub>i</sub> a<sub>i</sub> b<sub>i</sub></code>.
     * @throws DimensionMismatchException if arrays dimensions don't match
     * @since 3.2
     */
    T linearCombination(double[] a, T[] b)
        throws DimensionMismatchException;

    
Compute a linear combination.
Params:
a1 – first factor of the first term
b1 – second factor of the first term
a2 – first factor of the second term
b2 – second factor of the second term
See Also:
linearCombination(Object, Object, Object, Object, Object, Object)
linearCombination(Object, Object, Object, Object, Object, Object, Object, Object)
Returns:
a1×b1 +
a2×b2
Since:
3.2/**
     * Compute a linear combination.
     * @param a1 first factor of the first term
     * @param b1 second factor of the first term
     * @param a2 first factor of the second term
     * @param b2 second factor of the second term
     * @return a<sub>1</sub>&times;b<sub>1</sub> +
     * a<sub>2</sub>&times;b<sub>2</sub>
     * @see #linearCombination(Object, Object, Object, Object, Object, Object)
     * @see #linearCombination(Object, Object, Object, Object, Object, Object, Object, Object)
     * @since 3.2
     */
    T linearCombination(T a1, T b1, T a2, T b2);

    
Compute a linear combination.
Params:
a1 – first factor of the first term
b1 – second factor of the first term
a2 – first factor of the second term
b2 – second factor of the second term
See Also:
linearCombination(double, Object, double, Object, double, Object)
linearCombination(double, Object, double, Object, double, Object, double, Object)
Returns:
a1×b1 +
a2×b2
Since:
3.2/**
     * Compute a linear combination.
     * @param a1 first factor of the first term
     * @param b1 second factor of the first term
     * @param a2 first factor of the second term
     * @param b2 second factor of the second term
     * @return a<sub>1</sub>&times;b<sub>1</sub> +
     * a<sub>2</sub>&times;b<sub>2</sub>
     * @see #linearCombination(double, Object, double, Object, double, Object)
     * @see #linearCombination(double, Object, double, Object, double, Object, double, Object)
     * @since 3.2
     */
    T linearCombination(double a1, T b1, double a2, T b2);

    
Compute a linear combination.
Params:
a1 – first factor of the first term
b1 – second factor of the first term
a2 – first factor of the second term
b2 – second factor of the second term
a3 – first factor of the third term
b3 – second factor of the third term
See Also:
linearCombination(Object, Object, Object, Object)
linearCombination(Object, Object, Object, Object, Object, Object, Object, Object)
Returns:
a1×b1 +
a2×b2 + a3×b3
Since:
3.2/**
     * Compute a linear combination.
     * @param a1 first factor of the first term
     * @param b1 second factor of the first term
     * @param a2 first factor of the second term
     * @param b2 second factor of the second term
     * @param a3 first factor of the third term
     * @param b3 second factor of the third term
     * @return a<sub>1</sub>&times;b<sub>1</sub> +
     * a<sub>2</sub>&times;b<sub>2</sub> + a<sub>3</sub>&times;b<sub>3</sub>
     * @see #linearCombination(Object, Object, Object, Object)
     * @see #linearCombination(Object, Object, Object, Object, Object, Object, Object, Object)
     * @since 3.2
     */
    T linearCombination(T a1, T b1, T a2, T b2, T a3, T b3);

    
Compute a linear combination.
Params:
a1 – first factor of the first term
b1 – second factor of the first term
a2 – first factor of the second term
b2 – second factor of the second term
a3 – first factor of the third term
b3 – second factor of the third term
See Also:
linearCombination(double, Object, double, Object)
linearCombination(double, Object, double, Object, double, Object, double, Object)
Returns:
a1×b1 +
a2×b2 + a3×b3
Since:
3.2/**
     * Compute a linear combination.
     * @param a1 first factor of the first term
     * @param b1 second factor of the first term
     * @param a2 first factor of the second term
     * @param b2 second factor of the second term
     * @param a3 first factor of the third term
     * @param b3 second factor of the third term
     * @return a<sub>1</sub>&times;b<sub>1</sub> +
     * a<sub>2</sub>&times;b<sub>2</sub> + a<sub>3</sub>&times;b<sub>3</sub>
     * @see #linearCombination(double, Object, double, Object)
     * @see #linearCombination(double, Object, double, Object, double, Object, double, Object)
     * @since 3.2
     */
    T linearCombination(double a1, T b1,  double a2, T b2, double a3, T b3);

    
Compute a linear combination.
Params:
a1 – first factor of the first term
b1 – second factor of the first term
a2 – first factor of the second term
b2 – second factor of the second term
a3 – first factor of the third term
b3 – second factor of the third term
a4 – first factor of the third term
b4 – second factor of the third term
See Also:
linearCombination(Object, Object, Object, Object)
linearCombination(Object, Object, Object, Object, Object, Object)
Returns:
a1×b1 +
a2×b2 + a3×b3 +
a4×b4
Since:
3.2/**
     * Compute a linear combination.
     * @param a1 first factor of the first term
     * @param b1 second factor of the first term
     * @param a2 first factor of the second term
     * @param b2 second factor of the second term
     * @param a3 first factor of the third term
     * @param b3 second factor of the third term
     * @param a4 first factor of the third term
     * @param b4 second factor of the third term
     * @return a<sub>1</sub>&times;b<sub>1</sub> +
     * a<sub>2</sub>&times;b<sub>2</sub> + a<sub>3</sub>&times;b<sub>3</sub> +
     * a<sub>4</sub>&times;b<sub>4</sub>
     * @see #linearCombination(Object, Object, Object, Object)
     * @see #linearCombination(Object, Object, Object, Object, Object, Object)
     * @since 3.2
     */
    T linearCombination(T a1, T b1, T a2, T b2, T a3, T b3, T a4, T b4);

    
Compute a linear combination.
Params:
a1 – first factor of the first term
b1 – second factor of the first term
a2 – first factor of the second term
b2 – second factor of the second term
a3 – first factor of the third term
b3 – second factor of the third term
a4 – first factor of the third term
b4 – second factor of the third term
See Also:
linearCombination(double, Object, double, Object)
linearCombination(double, Object, double, Object, double, Object)
Returns:
a1×b1 +
a2×b2 + a3×b3 +
a4×b4
Since:
3.2/**
     * Compute a linear combination.
     * @param a1 first factor of the first term
     * @param b1 second factor of the first term
     * @param a2 first factor of the second term
     * @param b2 second factor of the second term
     * @param a3 first factor of the third term
     * @param b3 second factor of the third term
     * @param a4 first factor of the third term
     * @param b4 second factor of the third term
     * @return a<sub>1</sub>&times;b<sub>1</sub> +
     * a<sub>2</sub>&times;b<sub>2</sub> + a<sub>3</sub>&times;b<sub>3</sub> +
     * a<sub>4</sub>&times;b<sub>4</sub>
     * @see #linearCombination(double, Object, double, Object)
     * @see #linearCombination(double, Object, double, Object, double, Object)
     * @since 3.2
     */
    T linearCombination(double a1, T b1, double a2, T b2, double a3, T b3, double a4, T b4);

}