package jsci.maths;

/**
 * The extra math library.
 * Provides extra functions not in java.lang.Math class.
 * This class cannot be subclassed or instantiated because all methods are static.
 * @version 1.2
 * @author Mark Hale
 */
public final class ExtraMath extends AbstractMath {
    private ExtraMath() {}
    
    /**
     * Rounds a number to so many significant figures.
     * @param x a number to be rounded.
     * @param significant number of significant figures to round to.
     */
    public static double round(final double x, final int significant) {
        if(x == 0.0)
            return x;
        else if(significant == 0)
            return 0.0;
        final double signedExp = log10(Math.abs(x)) - significant;
        if(signedExp < 0.0) {
            // keep the exponent positive so factor is representable
            final double factor = Math.pow(10.0, Math.floor(-signedExp));
            return Math.round(x*factor)/factor;
        } else {
            final double factor = Math.pow(10.0, Math.ceil(signedExp));
            return Math.round(x/factor)*factor;
        }
    }
    /**
     * Returns a random number within a specified range.
     */
    public static double random(double min, double max) {
        return (max-min)*Math.random()+min;
    }
    /**
     * Returns the sign of a number.
     * @return 1 if x>0.0, -1 if x<0.0, else 0.
     */
    public static int sign(double x) {
        if(x > 0.0)
            return 1;
        else if(x < 0.0)
            return -1;
        else
            return 0;
    }
    /**
     * Returns sqrt(x2+y2).
     */
    public static double hypot(final double x,final double y) {
        final double xAbs=Math.abs(x);
        final double yAbs=Math.abs(y);
        if(xAbs==0.0 && yAbs==0.0)
            return 0.0;
        else if(xAbsb.
     * @param a an integer.
     * @param b a positive integer.
     */
    public static int pow(int a, int b) {
        if(b < 0) {
            throw new IllegalArgumentException(b+" must be a positive integer.");
        } else if(b == 0) {
            return 1;
        } else {
            if(a == 0) {
                return 0;
            } else if(a == 1) {
                return 1;
            } else if(a == 2) {
                return 1<a.
     * @param a a positive integer.
     */
    public static int pow2(int a) {
        return 1<double value.
     * 
The identity is:
     * 
coth(x) = (ex + e-x)/(ex - e-x),
    
     * in other words, {@linkplain Math#cosh cosh(x)}/{@linkplain Math#sinh sinh(x)}.
     * 
Special cases:
     * 

     * 
If the argument is NaN, then the result is NaN.
     * 
If the argument is zero, then the result is an infinity with the same sign as the argument.
     * 
If the argument is positive infinity, then the result is +1.0.
     * 
If the argument is negative infinity, then the result is -1.0.
     * 
     * @param x The number whose hyperbolic cotangent is sought
     * @return The hyperbolic cotangent of x
     */
    public static double
            coth(double x) {
        return 1.0D/tanh(x);
    } //coth
    
    /**
     * Returns the hyperbolic cosecant of a double value.
     * 
The identity is:
     * 
csch(x) = (2/(ex - e-x),
     * in other words, 1/{@linkplain Math#sinh sinh(x)}.
     * 
Special cases:
     * 

     * 
If the argument is NaN, then the result is NaN.
     * 
If the argument is zero, then the result is an infinity with the same sign as the argument.
     * 
If the argument is positive infinity, then the result is +0.0.
     * 
If the argument is negative infinity, then the result is -0.0.
     * 
     * @param x The number whose hyperbolic cosecant is sought
     * @return The hyperbolic cosecant of x
     */
    public static double
            csch(double x) {
        return 1.0D/sinh(x);
    } //csch
    
    /**
     * Returns the hyperbolic secant of a double value.
     * 
The identity is:
     * 
sech(x) = (2/(ex + e-x),
     * in other words, 1/{@linkplain Math#cosh cosh(x)}.
     * 
Special cases:
     * 

     * 
If the argument is NaN, then the result is NaN.
     * 
If the argument is an infinity (positive or negative), then the result is +0.0.
     * 
     * @param x The number whose hyperbolic secant is sought
     * @return The hyperbolic secant of x
     */
    public static double
            sech(double x) {
        return 1.0D/cosh(x);
    } //sech
    
    /**
     * Returns the inverse hyperbolic sine of a double value.
     * 
The identity is:
     * 
asinh(x) = ln(x + sqrt(x2 + 1))
     * 
Special cases:
     * 

     * 
If the argument is NaN, then the result is NaN.
     * 
If the argument is infinite, then the result is an infinity with the same sign as the argument.
     * 
If the argument is zero, then the result is a zero with the same sign as the argument.
     * 
     * @param x The number whose inverse hyperbolic sine is sought
     * @return The inverse hyperbolic sine of x
     */
    public static double
            asinh(double x) {
        //Math.hypot(Double.NEGATIVE_INFINITY, 1.0D) is Double.POSITIVE_INFINITY
        //return Double.isInfinite(x) ? x : (x == 0.0) ? x : Math.log(x + Math.hypot(x, 1.0D));
        return Double.isInfinite(x) ? x : (x == 0.0) ? x : Math.log(x+Math.sqrt(x*x+1.0));
    } //asinh
    
    /**
     * Returns the inverse hyperbolic cosine of a double value.
     * Note that cosh(+/-acosh(x)) = x; this function arbitrarily returns the positive branch.
     * 
The identity is:
     * 
acosh(x) = ln(x +/- sqrt(x2 - 1))
     * 
Special cases:
     * 

     * 
If the argument is NaN or less than one, then the result is NaN.
     * 
If the argument is a positive infinity, then the result is (positive) infinity.
     * 
If the argument is one, then the result is (positive) zero.
     * 
     * @param x The number whose inverse hyperbolic cosine is sought
     * @return The inverse hyperbolic cosine of x
     */
    public static double
            acosh(double x) {
        return Math.log(x + Math.sqrt(x*x - 1.0D));
    } //acosh
    
    /**
     * Returns the inverse hyperbolic tangent of a double value.
     * 
The identity is:
     * 
atanh(x) = (1/2)*ln((1 + x)/(1 - x))
     * 
Special cases:
     * 

     * 
If the argument is NaN, an infinity, or has a modulus of greater than one, then the result is NaN.
     * 
If the argument is plus or minus one, then the result is infinity with the same sign as the argument.
     * 
If the argument is zero, then the result is a zero with the same sign as the argument.
     * 
     * @param x A double specifying the value whose inverse hyperbolic tangent is sought
     * @return A double specifying the inverse hyperbolic tangent of x
     */
    public static double
            atanh(double x) {
        //return (Math.log1p(x) - Math.log1p(-x))/2.0D;
        return (x != 0.0) ? (Math.log(1.0D + x)-Math.log(1.0D - x))/2.0D : x;
    } //atanh
    
    /**
     * Returns the inverse hyperbolic cotangent of a double value.
     * 
The identity is:
     * 
acoth(x) = (1/2)*ln((x + 1)/(x - 1))
     * 
Special cases:
     * 

     * 
If the argument is NaN or a modulus of less than one, then the result is NaN.
     * 
If the argument is an infinity, then the result is zero with the same sign as the argument.
     * 
If the argument is plus or minus one, then the result is infinity with the same sign as the argument.
     * 
     * @param x The number whose inverse hyperbolic cotangent is sought
     * @return  The inverse hyperbolic cotangent of x
     */
    public static double
            acoth(double x) {
//    return (Math.log1p(x) - Math.log(x - 1.0D))/2.0D; // Difference of two same-sign infinities is NaN
        if (Double.isInfinite(x)) return (x < 0.0) ? -0.0D : +0.0D;
        //return (x == -1.0D) ? Double.NEGATIVE_INFINITY : (Math.log1p(x) - Math.log(x - 1.0D))/2.0D;
        return (x == -1.0D) ? Double.NEGATIVE_INFINITY : (Math.log(x+1.0) - Math.log(x - 1.0D))/2.0D;
    } //acoth
    
    /**
     * Returns the inverse hyperbolic cosecant of a double value.
     * 
The identity is:
     * 
acsch(x) = ln((1 - sqrt(1 + x2))/x) for x < 0;
     * 
acsch(x) = ln((1 + sqrt(1 + x2))/x) for x > 0.
     * 
Special cases:
     * 

     * 
If the argument is NaN, then the result is NaN.
     * 
If the argument is an infinity, then the result is zero with the same sign as the argument.
     * 
If the argument is zero, then the result is infinity with the same sign as the argument.
     * 
     * @param x The number whose inverse hyperbolic cosecant is sought
     * @return The inverse hyperbolic cosecant of x
     */
    public static double
            acsch(double x) {
//    return (x < 0) ? Math.log((1.0D - Math.sqrt(Math.hypot(1.0, x)))/x) : Math.log((1.0D + Math.sqrt(1.0, x))/x);
        
        if (Double.isInfinite(x)) return (x < 0.0) ? -0.0D : +0.0D;
        //log(+infinity) is +infinity, but log(-infinity) is NaN
        return (x == 0.0D) ? 1.0/x : Math.log((1.0D + sign(x)*Math.sqrt(x*x+1.0))/x);
    } //acsch
    
    /**
     * Returns the inverse hyperbolic secant of a double value.
     * Note that sech(+/-asech(x)) = x; this function arbitrarily returns the positive branch.
     * 
The identity is:
     * 
asech(x) = ln((1 + sqrt(1 - x2))/x).
     * 
Special cases:
     * 

     * 
If the argument is NaN, less than zero, or greater than one, then the result is NaN.
     * 
If the argument is zero, then the result is infinity with the same sign as the argument.
     * 
     * @param x The number whose hyperbolic secant is sought
     * @return The hyperbolic secant of x
     */
    public static double
            asech(double x) {
        //log(+infinity) is +infinity, but log(-infinity) is NaN
        return (x == 0.0D) ? 1.0/x : Math.log((1.0D + Math.sqrt(1.0D - x*x))/x);
    } //asech
}