Maths (OpenHFT/Chronicle-Core 2026.5 API)

java.lang.Object
- net.openhft.chronicle.core.Maths

```
public final class Maths
extends Object
```

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static double`	`add(long a, long b, long c)` return a + b / c as a double
`static long`	`agitate(long l)` Performs a series of bit operations on a long value to "agitate" the bits.
`static double`	`asDouble(long value, int exponent, boolean negative, int decimalPlaces)` Convert the components `(-1)^negative * value * 2^exponent * 10^-decimalPlaces` to a double.
`static double`	`ceilN(double d, double digits)` Rounds up the given value to the nearest higher number with specified decimal places.
`static double`	`ceilN(double d, int digits)` Rounds up the given double value to the nearest higher number, accurate to the specified number of decimal places.
`static int`	`digits(long num)` Returns the number of digits in the given number.
`static long`	`divideRoundUp(long dividend, long divisor)` Divide `dividend` by divisor, if division is not integral the result is rounded up.
`static long`	`fives(int decimalPlaces)` Returns the power of five for the given decimal places.
`static double`	`floorN(double d, double digits)` Rounds down the given value to the nearest lower number with specified decimal places.
`static double`	`floorN(double d, int digits)` Rounds down the given double value to the nearest lower number, accurate to the specified number of decimal places.
`static int`	`hash(Object o)`
`static int`	`hash(Object o1, Object o2)`
`static int`	`hash(Object o1, Object o2, Object o3)`
`static int`	`hash(Object o1, Object o2, Object o3, Object o4)`
`static int`	`hash(Object o1, Object o2, Object o3, Object o4, Object o5)`
`static long`	`hash64(@Nullable CharSequence cs)`
`static long`	`hash64(long l0)` A simple hashing algorithm for a 64-bit value
`static long`	`hash64(@NotNull String s)` Computes a 64-bit hash value for the given string.
`static long`	`hash64(@NotNull StringBuilder s)` Computes a 64-bit hash value for the given StringBuilder.
`static int`	`intLog2(long num)` Returns rounded down log₂`num`, e.
`static boolean`	`isPowerOf2(long n)` Checks if a number is a power of two.
`static int`	`nextPower2(int n, int min)` Returns the next power of two greater than or equal to the given number, with a specified minimum.
`static long`	`nextPower2(long n, long min)` Returns the next power of two greater than or equal to the given number, with a specified minimum.
`static double`	`round1(double d)` Rounds to one decimal place.
`static double`	`round1up(double d)` Performs a round which is accurate to within 1 ulp.
`static double`	`round2(double d)` Rounds to two decimal places.
`static double`	`round2up(double d)` Performs a round which is accurate to within 1 ulp.
`static double`	`round3(double d)` Performs a round which is accurate to within 1 ulp.
`static double`	`round3up(double d)` Performs a round which is accurate to within 1 ulp.
`static double`	`round4(double d)` Performs a round which is accurate to within 1 ulp.
`static double`	`round4up(double d)` Performs a round which is accurate to within 1 ulp.
`static double`	`round5(double d)` Performs a round which is accurate to within 1 ulp.
`static double`	`round5up(double d)` Performs a round which is accurate to within 1 ulp.
`static double`	`round6(double d)` Performs a round which is accurate to within 1 ulp.
`static double`	`round6up(double d)` Performs a round which is accurate to within 1 ulp.
`static double`	`round7(double d)` Performs a round which is accurate to within 1 ulp.
`static double`	`round7up(double d)` Performs a round which is accurate to within 1 ulp.
`static double`	`round8(double d)` Performs a round which is accurate to within 1 ulp.
`static double`	`round8up(double d)` Performs a round which is accurate to within 1 ulp.
`static long`	`roundingFactor(double digits)`
`static long`	`roundingFactor(int digits)`
`static double`	`roundN(double d, double digits)` Rounds the value using a fractional number of decimal places.
`static double`	`roundN(double d, int digits)` Rounds the value to a fixed number of decimal places.
`static double`	`roundNup(double d, int digits)` Performs a round which is accurate to within 1 ulp.
`static boolean`	`same(double a, double b)` Checks if two double values are the same.
`static boolean`	`same(float a, float b)` Checks if two float values are the same.
`static long`	`tens(int decimalPlaces)` Returns the power of ten for the given decimal places.
`static short`	`toInt16(long value)` Returns the value of the `long` argument; throwing an exception if the value overflows a `short`.
`static int`	`toInt32(long value)` Returns the value of the `long` argument; throwing an exception if the value overflows an `int`.
`static int`	`toInt32(long value, @NotNull String msg)` Returns the value of the `long` argument; throwing an exception if the value overflows an `int`.
`static byte`	`toInt8(long value)` Returns the value of the `long` argument; throwing an exception if the value overflows a `byte`.
`static int`	`toUInt16(long value)` Returns the value of the `long` argument; throwing an exception if the value overflows an unsigned short (0xFFFF).
`static int`	`toUInt31(long value)` Returns the value of the `long` argument; throwing an exception if the value overflows an unsigned 31 bit value (0x7FFFFFFFL).
`static long`	`toUInt32(long value)` Returns the value of the `long` argument; throwing an exception if the value overflows an unsigned int (0xFFFFFFFFL).
`static short`	`toUInt8(long value)` Returns the value of the `long` argument; throwing an exception if the value overflows an unsigned byte (0xFF).

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

- Method Detail
  - roundN
```
public static double roundN(double d,
                            int digits)
```
    Rounds the value to a fixed number of decimal places. The result is within one ulp of the mathematical rounding and may round values very close to 0.5 either way for speed.
    
    Parameters:
    
    d - value to round
    
    digits - precision from 0 to 18 digits
    
    Returns:
    
    rounded value
  - roundNup
```
public static double roundNup(double d,
                              int digits)
```
    Performs a round which is accurate to within 1 ulp. The value 0.5 should round up however the value one ulp less might round up or down. This is a pragmatic choice for performance reasons as it is assumed you are not working on the edge of the precision of double.
    
    Parameters:
    
    d - value to round
    
    Returns:
    
    rounded value
  - roundingFactor
```
public static long roundingFactor(int digits)
```
  - roundingFactor
```
public static long roundingFactor(double digits)
```
  - ceilN
```
public static double ceilN(double d,
                           int digits)
```
    Rounds up the given double value to the nearest higher number, accurate to the specified number of decimal places.
    
    Parameters:
    
    d - The double value to be rounded up.
    
    digits - The number of decimal places to which the value is to be rounded.
    
    Returns:
    
    The value rounded up to the nearest higher number.
  - floorN
```
public static double floorN(double d,
                            int digits)
```
    Rounds down the given double value to the nearest lower number, accurate to the specified number of decimal places.
    
    Parameters:
    
    d - The double value to be rounded down.
    
    digits - The number of decimal places to which the value is to be rounded.
    
    Returns:
    
    The value rounded down to the nearest lower number.
  - roundN
```
public static double roundN(double d,
                            double digits)
```
    Rounds the value using a fractional number of decimal places. Behaviour matches roundN(double, int) when digits is an integer.
    
    Parameters:
    
    d - value to round
    
    digits - fractional digits of precision
    
    Returns:
    
    rounded value
  - ceilN
```
public static double ceilN(double d,
                           double digits)
```
    Rounds up the given value to the nearest higher number with specified decimal places.
    
    Parameters:
    
    d - the value to ceil
    
    digits - number of decimal places
    
    Returns:
    
    the ceiled value
  - floorN
```
public static double floorN(double d,
                            double digits)
```
    Rounds down the given value to the nearest lower number with specified decimal places.
    
    Parameters:
    
    d - the value to floor
    
    digits - number of decimal places
    
    Returns:
    
    the floored value
  - round1
```
public static double round1(double d)
```
    Rounds to one decimal place. Accuracy is within one ulp so values close to 0.5 may round either way.
    
    Parameters:
    
    d - value to round
    
    Returns:
    
    rounded value
  - round1up
```
public static double round1up(double d)
```
    Performs a round which is accurate to within 1 ulp. The value 0.5 should round up however the value one ulp less might round up or down. This is a pragmatic choice for performance reasons as it is assumed you are not working on the edge of the precision of double.
    
    Parameters:
    
    d - value to round
    
    Returns:
    
    rounded value
  - round2
```
public static double round2(double d)
```
    Rounds to two decimal places. Accuracy is within one ulp so values close to 0.5 may round either way.
    
    Parameters:
    
    d - value to round
    
    Returns:
    
    rounded value
  - round2up
```
public static double round2up(double d)
```
    Performs a round which is accurate to within 1 ulp. The value 0.5 should round up however the value one ulp less might round up or down. This is a pragmatic choice for performance reasons as it is assumed you are not working on the edge of the precision of double.
    
    Parameters:
    
    d - value to round
    
    Returns:
    
    rounded value
  - round3
```
public static double round3(double d)
```
    Performs a round which is accurate to within 1 ulp. i.e. for values very close to 0.5 it might be rounded up or down. This is a pragmatic choice for performance reasons as it is assumed you are not working on the edge of the precision of double.
    
    Parameters:
    
    d - value to round
    
    Returns:
    
    rounded value
  - round3up
```
public static double round3up(double d)
```
    Performs a round which is accurate to within 1 ulp. The value 0.5 should round up however the value one ulp less might round up or down. This is a pragmatic choice for performance reasons as it is assumed you are not working on the edge of the precision of double.
    
    Parameters:
    
    d - value to round
    
    Returns:
    
    rounded value
  - round4
```
public static double round4(double d)
```
    Performs a round which is accurate to within 1 ulp. i.e. for values very close to 0.5 it might be rounded up or down. This is a pragmatic choice for performance reasons as it is assumed you are not working on the edge of the precision of double.
    
    Parameters:
    
    d - value to round
    
    Returns:
    
    rounded value
  - round4up
```
public static double round4up(double d)
```
    Performs a round which is accurate to within 1 ulp. The value 0.5 should round up however the value one ulp less might round up or down. This is a pragmatic choice for performance reasons as it is assumed you are not working on the edge of the precision of double.
    
    Parameters:
    
    d - value to round
    
    Returns:
    
    rounded value
  - round5
```
public static double round5(double d)
```
    Performs a round which is accurate to within 1 ulp. i.e. for values very close to 0.5 it might be rounded up or down. This is a pragmatic choice for performance reasons as it is assumed you are not working on the edge of the precision of double.
    
    Parameters:
    
    d - value to round
    
    Returns:
    
    rounded value
  - round5up
```
public static double round5up(double d)
```
    Performs a round which is accurate to within 1 ulp. The value 0.5 should round up however the value one ulp less might round up or down. This is a pragmatic choice for performance reasons as it is assumed you are not working on the edge of the precision of double.
    
    Parameters:
    
    d - value to round
    
    Returns:
    
    rounded value
  - round6
```
public static double round6(double d)
```
    Performs a round which is accurate to within 1 ulp. The value 0.5 should round up however the value one ulp less might round up or down. This is a pragmatic choice for performance reasons as it is assumed you are not working on the edge of the precision of double.
    
    Parameters:
    
    d - value to round
    
    Returns:
    
    rounded value
  - round6up
```
public static double round6up(double d)
```
    Performs a round which is accurate to within 1 ulp. The value 0.5 should round up however the value one ulp less might round up or down. This is a pragmatic choice for performance reasons as it is assumed you are not working on the edge of the precision of double.
    
    Parameters:
    
    d - value to round
    
    Returns:
    
    rounded value
  - round7
```
public static double round7(double d)
```
    Performs a round which is accurate to within 1 ulp. i.e. for values very close to 0.5 it might be rounded up or down. This is a pragmatic choice for performance reasons as it is assumed you are not working on the edge of the precision of double.
    
    Parameters:
    
    d - value to round
    
    Returns:
    
    rounded value
  - round7up
```
public static double round7up(double d)
```
    Performs a round which is accurate to within 1 ulp. The value 0.5 should round up however the value one ulp less might round up or down. This is a pragmatic choice for performance reasons as it is assumed you are not working on the edge of the precision of double.
    
    Parameters:
    
    d - value to round
    
    Returns:
    
    rounded value
  - round8
```
public static double round8(double d)
```
    Performs a round which is accurate to within 1 ulp. i.e. for values very close to 0.5 it might be rounded up or down. This is a pragmatic choice for performance reasons as it is assumed you are not working on the edge of the precision of double.
    
    Parameters:
    
    d - value to round
    
    Returns:
    
    rounded value
  - round8up
```
public static double round8up(double d)
```
    Performs a round which is accurate to within 1 ulp. The value 0.5 should round up however the value one ulp less might round up or down. This is a pragmatic choice for performance reasons as it is assumed you are not working on the edge of the precision of double.
    
    Parameters:
    
    d - value to round
    
    Returns:
    
    rounded value
  - nextPower2
```
public static int nextPower2(int n,
                             int min)
                      throws IllegalArgumentException
```
    Returns the next power of two greater than or equal to the given number, with a specified minimum.
    
    Parameters:
    
    n - the number to find the next power of two for
    
    min - the minimum power of two to return if n is less than min
    
    Returns:
    
    the next power of two greater than or equal to n, but at least min
    
    Throws:
    
    IllegalArgumentException - if the provided min value is not a positive power of two
  - nextPower2
```
public static long nextPower2(long n,
                              long min)
                       throws IllegalArgumentException
```
    Returns the next power of two greater than or equal to the given number, with a specified minimum.
    
    Parameters:
    
    n - the number to find the next power of two for
    
    min - the minimum power of two to return if n is less than min
    
    Returns:
    
    the next power of two greater than or equal to n, but at least min
    
    Throws:
    
    IllegalArgumentException - if the provided min value is not a positive power of two
  - isPowerOf2
```
public static boolean isPowerOf2(long n)
```
    Checks if a number is a power of two.
    
    Parameters:
    
    n - the number to check
    
    Returns:
    
    true if n is a positive power of two, false otherwise
  - hash64
```
public static long hash64(@Nullable
                          @Nullable CharSequence cs)
```
  - hash64
```
public static long hash64(@NotNull
                          @NotNull String s)
```
    Computes a 64-bit hash value for the given string. The hash function used is dependent on the Java version and the internal representation of the string. For Java 9 and later, if the string is represented as a byte array, each byte is incorporated into the hash. Otherwise, each character is incorporated into the hash. For Java 8 and earlier, each character is incorporated into the hash. The hash value is agitated using a function not shown in this code snippet.
    
    Parameters:
    
    s - the string to compute the hash for
    
    Returns:
    
    the 64-bit hash value
    
    Throws:
    
    IllegalArgumentException - if s is null
  - hash64
```
public static long hash64(@NotNull
                          @NotNull StringBuilder s)
```
    Computes a 64-bit hash value for the given StringBuilder. The hash function used is dependent on the Java version and the internal representation of the string. For Java 9 and later, if the string is represented as a byte array, each byte is incorporated into the hash. Otherwise, each character is incorporated into the hash. For Java 8 and earlier, each character is incorporated into the hash. The hash is then agitated using a function not shown in this code snippet.
    
    Parameters:
    
    s - the string to compute the hash for
    
    Returns:
    
    the 64-bit hash value
    
    Throws:
    
    IllegalArgumentException - if s is null
  - intLog2
```
public static int intLog2(long num)
                   throws IllegalArgumentException
```
    Returns rounded down log₂num, e. g.: intLog2(1) == 0, intLog2(2) == 1, intLog2(7) == 2, intLog2(8) == 3, etc.
    
    Throws:
    
    IllegalArgumentException - if the given number <= 0
  - toInt8
```
public static byte toInt8(long value)
                   throws ArithmeticException
```
    Returns the value of the long argument; throwing an exception if the value overflows a byte.
    
    Parameters:
    
    value - the long value
    
    Returns:
    
    the argument as a byte
    
    Throws:
    
    ArithmeticException - if the argument overflows a byte
  - toInt16
```
public static short toInt16(long value)
                     throws ArithmeticException
```
    Returns the value of the long argument; throwing an exception if the value overflows a short.
    
    Parameters:
    
    value - the long value
    
    Returns:
    
    the argument as a short
    
    Throws:
    
    ArithmeticException - if the argument overflows a short
  - toInt32
```
public static int toInt32(long value,
                          @NotNull
                          @NotNull String msg)
                   throws ArithmeticException
```
    Returns the value of the long argument; throwing an exception if the value overflows an int.
    
    Parameters:
    
    value - the long value
    
    msg - to use in a potential exception message
    
    Returns:
    
    the argument as an int
    
    Throws:
    
    ArithmeticException - if the argument overflows an int
  - toInt32
```
public static int toInt32(long value)
                   throws ArithmeticException
```
    Returns the value of the long argument; throwing an exception if the value overflows an int.
    
    Parameters:
    
    value - the long value
    
    Returns:
    
    the argument as an int
    
    Throws:
    
    ArithmeticException - if the argument overflows an int
  - toUInt8
```
public static short toUInt8(long value)
                     throws ArithmeticException
```
    Returns the value of the long argument; throwing an exception if the value overflows an unsigned byte (0xFF).
    
    Parameters:
    
    value - the long value
    
    Returns:
    
    the argument as a short
    
    Throws:
    
    ArithmeticException - if the argument overflows an unsigned byte
  - toUInt16
```
public static int toUInt16(long value)
                    throws ArithmeticException
```
    Returns the value of the long argument; throwing an exception if the value overflows an unsigned short (0xFFFF).
    
    Parameters:
    
    value - the long value
    
    Returns:
    
    the argument as an int
    
    Throws:
    
    ArithmeticException - if the argument overflows an unsigned short
  - toUInt31
```
public static int toUInt31(long value)
                    throws ArithmeticException
```
    Returns the value of the long argument; throwing an exception if the value overflows an unsigned 31 bit value (0x7FFFFFFFL).
    
    Parameters:
    
    value - the long value
    
    Returns:
    
    the argument as a long
    
    Throws:
    
    ArithmeticException - if the argument overflows an unsigned int
  - toUInt32
```
public static long toUInt32(long value)
                     throws ArithmeticException
```
    Returns the value of the long argument; throwing an exception if the value overflows an unsigned int (0xFFFFFFFFL).
    
    Parameters:
    
    value - the long value
    
    Returns:
    
    the argument as a long
    
    Throws:
    
    ArithmeticException - if the argument overflows an unsigned int
  - agitate
```
public static long agitate(long l)
```
    Performs a series of bit operations on a long value to "agitate" the bits. This includes a right shift, addition, and a right rotation with a bitwise XOR operation. The purpose of this method is to create a more evenly distributed set of bit patterns which can be useful in certain hashing or random number generation scenarios.
    
    Parameters:
    
    l - the long value to be agitated
    
    Returns:
    
    the agitated long value
  - hash64
```
public static long hash64(long l0)
```
    A simple hashing algorithm for a 64-bit value
    
    Parameters:
    
    l0 - to hash
    
    Returns:
    
    hash value.
  - divideRoundUp
```
public static long divideRoundUp(long dividend,
                                 long divisor)
```
    Divide dividend by divisor, if division is not integral the result is rounded up. Examples: divideRoundUp(10, 5) == 2, divideRoundUp(11, 5) == 3, divideRoundUp(-10, 5) == -2, divideRoundUp(-11, 5) == -3.
    
    Returns:
    
    the rounded up quotient
    
    Throws:
    
    ArithmeticException - if divisor is zero.
  - tens
```
public static long tens(int decimalPlaces)
```
    Returns the power of ten for the given decimal places.
    
    Parameters:
    
    decimalPlaces - the number of decimal places
    
    Returns:
    
    the power of ten corresponding to the decimal places
    
    Throws:
    
    IllegalArgumentException - if the decimal places are less than 0 or greater than or equal to 19
  - digits
```
public static int digits(long num)
```
    Returns the number of digits in the given number.
    
    Parameters:
    
    num - the number to count the digits of
    
    Returns:
    
    the number of digits in the given number
  - fives
```
public static long fives(int decimalPlaces)
```
    Returns the power of five for the given decimal places.
    
    Parameters:
    
    decimalPlaces - the number of decimal places
    
    Returns:
    
    the power of five corresponding to the decimal places
  - same
```
public static boolean same(double a,
                           double b)
```
    Checks if two double values are the same. Considers NaN values as equal.
    
    Parameters:
    
    a - the first double value
    
    b - the second double value
    
    Returns:
    
    true if both values are the same or both are NaN, false otherwise
  - same
```
public static boolean same(float a,
                           float b)
```
    Checks if two float values are the same. Considers NaN values as equal.
    
    Parameters:
    
    a - the first float value
    
    b - the second float value
    
    Returns:
    
    true if both values are the same or both are NaN, false otherwise
  - hash
```
public static int hash(Object o)
```
  - hash
```
public static int hash(Object o1,
                       Object o2)
```
  - hash
```
public static int hash(Object o1,
                       Object o2,
                       Object o3)
```
  - hash
```
public static int hash(Object o1,
                       Object o2,
                       Object o3,
                       Object o4)
```
  - hash
```
public static int hash(Object o1,
                       Object o2,
                       Object o3,
                       Object o4,
                       Object o5)
```
  - asDouble
```
public static double asDouble(long value,
                              int exponent,
                              boolean negative,
                              int decimalPlaces)
```
    Convert the components (-1)^negative * value * 2^exponent * 10^-decimalPlaces to a double.
    Accuracy. Within the Clinger fast-path domain this returns the correctly-rounded result — bit-identical to Double.parseDouble(String) of the same decimal. The domain is:
    - exponent == 0 (the mantissa was accumulated without binary shedding), and
    - value <= 2^53 (the mantissa is exactly representable — i.e. up to 15 significant decimal digits), and
    - -22 <= decimalPlaces <= 22 (10^22 is the largest exactly-representable power of ten).
    This covers essentially all realistic data: every finite magnitude in [1e-8, 1e15) carrying up to 15 significant digits, and modest-precision values up to 1e22. For such inputs the result is guaranteed exact (0 ULP).
    Deviation (extreme cases only). Outside that domain — a full-precision mantissa of 16–17 significant digits (value > 2^53), or |decimalPlaces| > 22 (magnitudes below ~1e-8 or very large values written to full precision) — the result is produced by an approximate reconstruction and may differ from the correctly-rounded value by up to 1 ULP (up to 2 ULP at the most extreme exponents). Round-half-to-even is not guaranteed there, so the error rate skews with the trailing decimal digit (odd last digits, which sit nearer a rounding boundary, miss more often). These cases do not arise on the common realistic data path; closing the gap fully would require a correctly-rounded big-integer / Eisel-Lemire step, traded off here against speed and code size.
    Parameters:
    
    value - The integer value (mantissa), >= 0
    
    exponent - The binary exponent (non-zero only when the mantissa overflowed a long)
    
    negative - Whether the result is negative
    
    decimalPlaces - The number of decimal places (net of any explicit power-of-ten exponent)
    
    Returns:
    
    The value as a double; correctly-rounded within the fast-path domain above, otherwise within 1 ULP (2 ULP at extreme exponents) of correctly-rounded
  - add
```
public static double add(long a,
                         long b,
                         long c)
```
    return a + b / c as a double

Class Maths

Method Summary

Methods inherited from class java.lang.Object

Method Detail

roundN

roundNup

roundingFactor

roundingFactor

ceilN

floorN

roundN

ceilN

floorN

round1

round1up

round2

round2up

round3

round3up

round4

round4up

round5

round5up

round6

round6up

round7

round7up

round8

round8up

nextPower2

nextPower2

isPowerOf2

hash64

hash64

hash64

intLog2

toInt8

toInt16

toInt32

toInt32

toUInt8

toUInt16

toUInt31

toUInt32

agitate

hash64

divideRoundUp

tens

digits

fives

same

same

hash

hash

hash

hash

hash

asDouble

add