MathUtils (tektosyne API)

java.lang.Object
- org.kynosarges.tektosyne.MathUtils

public final class MathUtils
extends java.lang.Object

Provides general mathematical utility methods.

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static int`	`compare(double a, double b, double epsilon)` Compares two `Double` numbers numerically, given the specified epsilon.
`static int`	`compare(float a, float b, float epsilon)` Compares two `Float` numbers numerically, given the specified epsilon.
`static boolean`	`equals(double a, double b, double epsilon)` Compares two `Double` numbers for equality, given the specified epsilon.
`static boolean`	`equals(float a, float b, float epsilon)` Compares two `Float` numbers for equality, given the specified epsilon.
`static <T> T`	`getAny(java.util.Collection<T> collection)` Gets a random element from the specified `Collection`.
`static <T> T`	`getAny(java.util.List<T> list)` Gets a random element from the specified `List`.
`static <T> T`	`getAny(T[] array)` Gets a random element from the specified array.
`static boolean`	`isPrime(int candidate)` Determines whether the specified `Integer` number is prime.
`static double`	`normalize(double[] array)` Normalizes the specified array of non-negative `Double` numbers.
`static float`	`normalize(float[] array)` Normalizes the specified array of non-negative `Float` numbers.
`static double`	`restrict(double a, double min, double max)` Restricts the specified `Double` number to the specified range.
`static float`	`restrict(float a, float min, float max)` Restricts the specified `Float` number to the specified range.
`static int`	`restrict(int a, int min, int max)` Restricts the specified `Integer` number to the specified range.
`static long`	`restrict(long a, long min, long max)` Restricts the specified `Long` number to the specified range.
`static int`	`toIntExact(double value)` Casts the specified `Double` value to `Integer`, throwing an exception on overflow.
`static int`	`toIntExact(float value)` Casts the specified `Float` value to `Integer`, throwing an exception on overflow.
`static long`	`toLongExact(double value)` Casts the specified `Double` value to `Long`, throwing an exception on overflow.
`static long`	`toLongExact(float value)` Casts the specified `Float` value to `Long`, throwing an exception on overflow.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - compare
```
public static int compare(double a,
                          double b,
                          double epsilon)
```
    Compares two Double numbers numerically, given the specified epsilon.
    
    Parameters:
    
    a - the first Double number to compare
    
    b - the second Double number to compare
    
    epsilon - the maximum absolute difference where a and b are considered equal
    
    Returns:
    
    zero if the absolute difference between a and b is no greater than epsilon, otherwise a value less or greater than zero if a is less or greater than b, respectively
    
    Throws:
    
    java.lang.IllegalArgumentException - if epsilon is less than zero
  - compare
```
public static int compare(float a,
                          float b,
                          float epsilon)
```
    Compares two Float numbers numerically, given the specified epsilon.
    
    Parameters:
    
    a - the first Float number to compare
    
    b - the second Float number to compare
    
    epsilon - the maximum absolute difference where a and b are considered equal
    
    Returns:
    
    zero if the absolute difference between a and b is no greater than epsilon, otherwise a value less or greater than zero if a is less or greater than b, respectively
    
    Throws:
    
    java.lang.IllegalArgumentException - if epsilon is less than zero
  - equals
```
public static boolean equals(double a,
                             double b,
                             double epsilon)
```
    Compares two Double numbers for equality, given the specified epsilon.
    
    Parameters:
    
    a - the first Double number to compare
    
    b - the second Double number to compare
    
    epsilon - the maximum absolute difference where a and b are considered equal
    
    Returns:
    
    true if the absolute difference between a and b is no greater than epsilon, else false
    
    Throws:
    
    java.lang.IllegalArgumentException - if epsilon is less than zero
  - equals
```
public static boolean equals(float a,
                             float b,
                             float epsilon)
```
    Compares two Float numbers for equality, given the specified epsilon.
    
    Parameters:
    
    a - the first Float number to compare
    
    b - the second Float number to compare
    
    epsilon - the maximum absolute difference where a and b are considered equal
    
    Returns:
    
    true if the absolute difference between a and b is no greater than epsilon, else false
    
    Throws:
    
    java.lang.IllegalArgumentException - if epsilon is less than zero
  - getAny
```
public static <T> T getAny(T[] array)
```
    Gets a random element from the specified array. Returns the array element at a random index between zero (inclusive) and length (exclusive). This is an O(1) operation.
    
    Type Parameters:
    
    T - the type of all elements in the array
    
    Parameters:
    
    array - the array providing the elements
    
    Returns:
    
    a random element from array
    
    Throws:
    
    java.lang.IllegalArgumentException - if array is empty
    
    java.lang.NullPointerException - if array is null
  - getAny
```
public static <T> T getAny(java.util.Collection<T> collection)
```
    Gets a random element from the specified Collection. Iterates through collection for a random number of steps, between zero (inclusive) to Collection.size() (exclusive). This is an O(n) operation.
    
    Type Parameters:
    
    T - the type of all elements in the Collection
    
    Parameters:
    
    collection - the Collection providing the elements
    
    Returns:
    
    a random element from collection
    
    Throws:
    
    java.lang.IllegalArgumentException - if collection is empty
    
    java.lang.NullPointerException - if collection is null
  - getAny
```
public static <T> T getAny(java.util.List<T> list)
```
    Gets a random element from the specified List. Returns the list element at a random index between zero (inclusive) and List.size() (exclusive). This is usually an O(1) operation.
    
    Type Parameters:
    
    T - the type of all elements in the List
    
    Parameters:
    
    list - the List providing the elements
    
    Returns:
    
    a random element from list
    
    Throws:
    
    java.lang.IllegalArgumentException - if list is empty
    
    java.lang.NullPointerException - if list is null
  - isPrime
```
public static boolean isPrime(int candidate)
```
    Determines whether the specified Integer number is prime. Performs trial divisions of the specified candidate against any number between two and the square root of candidate.
    
    Parameters:
    
    candidate - the Integer number to examine
    
    Returns:
    
    true if candidate is prime, else false
    
    Throws:
    
    java.lang.IllegalArgumentException - if candidate is not positive
  - normalize
```
public static double normalize(double[] array)
```
    Normalizes the specified array of non-negative Double numbers. Divides all array elements by the sum of all elements (which is also returned), thus normalizing their values to a partitioning of the standard interval [0, 1]. If the sum of all elements is zero, all elements are instead set to 1.0/length where length is the number of array elements.
    
    Parameters:
    
    array - the array of non-negative Double numbers to normalize
    
    Returns:
    
    the sum of all array elements before normalization
    
    Throws:
    
    java.lang.NullPointerException - if array is null
    
    java.lang.IllegalArgumentException - if array contains a negative number
  - normalize
```
public static float normalize(float[] array)
```
    Normalizes the specified array of non-negative Float numbers. Divides all array elements by the sum of all elements (which is also returned), thus normalizing their values to a partitioning of the standard interval [0, 1]. If the sum of all elements is zero, all elements are instead set to 1f/length where length is the number of array elements.
    
    Parameters:
    
    array - the array of non-negative Float numbers to normalize
    
    Returns:
    
    the sum of all array elements before normalization
    
    Throws:
    
    java.lang.NullPointerException - if array is null
    
    java.lang.IllegalArgumentException - if array contains a negative number
  - restrict
```
public static double restrict(double a,
                              double min,
                              double max)
```
    Restricts the specified Double number to the specified range.
    
    Parameters:
    
    a - the Double number to restrict
    
    min - the smallest permissible Double value for a
    
    max - the greatest permissible Double value for a
    
    Returns:
    
    min or max if a is less or greater than min or max, respectively, otherwise a itself
  - restrict
```
public static float restrict(float a,
                             float min,
                             float max)
```
    Restricts the specified Float number to the specified range.
    
    Parameters:
    
    a - the Float number to restrict
    
    min - the smallest permissible Float value for a
    
    max - the greatest permissible Float value for a
    
    Returns:
    
    min or max if a is less or greater than min or max, respectively, otherwise a itself
  - restrict
```
public static int restrict(int a,
                           int min,
                           int max)
```
    Restricts the specified Integer number to the specified range.
    
    Parameters:
    
    a - the Integer number to restrict
    
    min - the smallest permissible Integer value for a
    
    max - the greatest permissible Integer value for a
    
    Returns:
    
    min or max if a is less or greater than min or max, respectively, otherwise a itself
  - restrict
```
public static long restrict(long a,
                            long min,
                            long max)
```
    Restricts the specified Long number to the specified range.
    
    Parameters:
    
    a - the Long number to restrict
    
    min - the smallest permissible Long value for a
    
    max - the greatest permissible Long value for a
    
    Returns:
    
    min or max if a is less or greater than min or max, respectively, otherwise a itself
  - toIntExact
```
public static int toIntExact(double value)
```
    Casts the specified Double value to Integer, throwing an exception on overflow.
    
    Parameters:
    
    value - the Double value to convert to Integer
    
    Returns:
    
    the result of casting value to Integer
    
    Throws:
    
    java.lang.ArithmeticException - if value overflows Integer
  - toIntExact
```
public static int toIntExact(float value)
```
    Casts the specified Float value to Integer, throwing an exception on overflow.
    
    Parameters:
    
    value - the Float value to convert to Integer
    
    Returns:
    
    the result of casting value to Integer
    
    Throws:
    
    java.lang.ArithmeticException - if value overflows Integer
  - toLongExact
```
public static long toLongExact(double value)
```
    Casts the specified Double value to Long, throwing an exception on overflow.
    
    Parameters:
    
    value - the Double value to convert to Long
    
    Returns:
    
    the result of casting value to Long
    
    Throws:
    
    java.lang.ArithmeticException - if value overflows Long
  - toLongExact
```
public static long toLongExact(float value)
```
    Casts the specified Float value to Long, throwing an exception on overflow.
    
    Parameters:
    
    value - the Float value to convert to Long
    
    Returns:
    
    the result of casting value to Long
    
    Throws:
    
    java.lang.ArithmeticException - if value overflows Long

Class MathUtils

Method Summary

Methods inherited from class java.lang.Object

Method Detail

compare

compare

equals

equals

getAny

getAny

getAny

isPrime

normalize

normalize

restrict

restrict

restrict

restrict

toIntExact

toIntExact

toLongExact

toLongExact