Package org.apache.datasketches.common

# Class Util

java.lang.Object
org.apache.datasketches.common.Util

public final class Util extends Object
Common utility functions.

Author:
  Lee Rhodes

## Field Summary

Fields
Modifier and Type
Field
Description
`static final double`
`INVERSE_GOLDEN`
The inverse golden ratio as a fraction.
`static final long`
`INVERSE_GOLDEN_U64`
The inverse golden ratio as an unsigned long.
`static final double`
`LOG2`
The natural logarithm of 2.0.
`static final double`
`LONG_MAX_VALUE_AS_DOUBLE`
Long.MAX_VALUE as a double.
`static final String`
`LS`
The java line separator character as a String.
`static final char`
`TAB`
The tab character

## Method Summary

Modifier and Type
Method
Description
`static final int`
`bitAt(long number, int bitPos)`
Returns a one if the bit at bitPos is a one, otherwise zero.
`static int`
`bytesToInt(byte[] arr)`
Returns an int extracted from a Little-Endian byte array.
`static long`
`bytesToLong(byte[] arr)`
Returns a long extracted from a Little-Endian byte array.
`static String`
`bytesToString(byte[] arr, boolean signed, boolean littleEndian, String sep)`
Returns a string view of a byte array
`static double`
`ceilingPowerBaseOfDouble(double base, double n)`
Returns the ceiling of a given n given a base, where the ceiling is an integral power of the base.
`static int`
`ceilingPowerOf2(int n)`
Computes the int ceiling power of 2 within the range [1, 2^30].
`static long`
`ceilingPowerOf2(long n)`
Computes the long ceiling power of 2 within the range [1, 2^62].
`static String`
`characterPad(String s, int fieldLength, char padChar, boolean postpend)`
Prepend or postpend the given string with the given character to fill the given field length.
`static void`
`checkBounds(long reqOff, long reqLen, long allocSize)`
Check the requested offset and length against the allocated size.
`static void`
`checkIfMultipleOf8AndGT0(long v, String argName)`
Checks if parameter v is a multiple of 8 and greater than zero.
`static void`
`checkIfPowerOf2(long n, String argName)`
Checks the given long argument if it is a positive integer power of 2.
`static void`
`checkProbability(double p, String argName)`
Checks the given parameter to make sure it is positive and between 0.0 inclusive and 1.0 inclusive.
`static int`
`exactLog2OfInt(int powerOf2)`
Returns the log2 of the given int value if it is an exact power of 2 and greater than zero.
`static int`
`exactLog2OfInt(int powerOf2, String argName)`
Returns the log2 of the given int value if it is an exact power of 2 and greater than zero.
`static int`
`exactLog2OfLong(long powerOf2)`
Returns the log2 of the given long value if it is an exact power of 2 and greater than zero.
`static int`
`exactLog2OfLong(long powerOf2, String argName)`
Returns the log2 of the given long value if it is an exact power of 2 and greater than zero.
`static double`
`floorPowerBaseOfDouble(double base, double n)`
Computes the floor of a given n given base, where the floor is an integral power of the base.
`static int`
`floorPowerOf2(int n)`
Computes the floor power of 2 given n is in the range [1, 2^31-1].
`static long`
`floorPowerOf2(long n)`
Computes the floor power of 2 given n is in the range [1, 2^63-1].
`static byte[]`
`intToBytes(int v, byte[] arr)`
Returns a Little-Endian byte array extracted from the given int.
`static double`
`invPow2(int e)`
Computes the inverse integer power of 2: 1/(2^e) = 2^(-e).
`static boolean`
`isEven(long n)`
Returns true if given n is even.
`static boolean`
`isLessThanUnsigned(long n1, long n2)`
Unsigned compare with longs.
`static boolean`
`isMultipleOf8AndGT0(long v)`
Returns true if v is a multiple of 8 and greater than zero
`static boolean`
`isOdd(long n)`
Returns true if given n is odd.
`static boolean`
`isPowerOf2(long n)`
Returns true if given long argument is exactly a positive power of 2.
`static <T> boolean`
`le(Object item1, Object item2, Comparator<? super T> c)`
Is item1 Less-Than-Or-Equal-To item2
`static double`
`log2(double value)`
The log2(value)
`static double`
`logBaseOfX(double base, double x)`
Returns the logbase(x).
`static byte[]`
`longToBytes(long v, byte[] arr)`
Returns a Little-Endian byte array extracted from the given long.
`static String`
`longToFixedLengthString(long number, int length)`
Converts the given number to a string prepended with spaces, if necessary, to match the given length.
`static String`
`longToHexBytes(long v)`
Returns a string of spaced hex bytes in Big-Endian order.
`static <T> boolean`
`lt(Object item1, Object item2, Comparator<? super T> c)`
Is item1 Less-Than item2
`static <T> Object`
`maxT(Object item1, Object item2, Comparator<? super T> c)`
Finds the maximum of two generic items
`static String`
`milliSecToString(long mS)`
Returns the given time in milliseconds formatted as Hours:Min:Sec.mSec
`static <T> Object`
`minT(Object item1, Object item2, Comparator<? super T> c)`
Finds the minimum of two generic items
`static String`
`nanoSecToString(long nS)`
Returns the given time in nanoseconds formatted as Sec.mSec_uSec_nSec
`static int`
`numberOfLeadingOnes(long v)`
Returns the number of one bits preceding the highest-order ("leftmost") zero-bit in the two's complement binary representation of the specified long value, or 64 if the value is equal to minus one.
`static int`
`numberOfTrailingOnes(long v)`
Returns the number of one bits following the lowest-order ("rightmost") zero-bit in the two's complement binary representation of the specified long value, or 64 if the value is equal to minus one.
`static int`
`numDigits(long n)`
Computes the number of decimal digits of the number n
`static double`
`powerSeriesNextDouble(int ppb, double curPoint, boolean roundToLong, double logBase)`
Computes the next larger double in the power series point = logBase( i / ppb ) given the current point in the series.
`static long`
`pwr2SeriesNext(int ppo, long curPoint)`
Computes the next larger integer point in the power series point = 2( i / ppo ) given the current point in the series.
`static int`
`pwr2SeriesPrev(int ppo, int curPoint)`
Computes the previous, smaller integer point in the power series point = 2( i / ppo ) given the current point in the series.
`static String`
`zeroPad(String s, int fieldLength)`
Prepend the given string with zeros.

### Methods inherited from class java.lang.Object

`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### LS

public static final String LS
The java line separator character as a String.

### TAB

public static final char TAB
The tab character

See Also:
  - Constant Field Values

### LOG2

public static final double LOG2
The natural logarithm of 2.0.

### INVERSE_GOLDEN_U64

public static final long INVERSE_GOLDEN_U64
The inverse golden ratio as an unsigned long.

See Also:
  - Constant Field Values

### INVERSE_GOLDEN

public static final double INVERSE_GOLDEN
The inverse golden ratio as a fraction. This has more precision than using the formula: (Math.sqrt(5.0) - 1.0) / 2.0.

See Also:
  - Constant Field Values

### LONG_MAX_VALUE_AS_DOUBLE

public static final double LONG_MAX_VALUE_AS_DOUBLE
Long.MAX_VALUE as a double.

See Also:
  - Constant Field Values

## Method Details

### bytesToInt

public static int bytesToInt(byte[] arr)
Returns an int extracted from a Little-Endian byte array.

Parameters:
  `arr` - the given byte array
Returns:
  an int extracted from a Little-Endian byte array.

### bytesToLong

public static long bytesToLong(byte[] arr)
Returns a long extracted from a Little-Endian byte array.

Parameters:
  `arr` - the given byte array
Returns:
  a long extracted from a Little-Endian byte array.

### intToBytes

public static byte[] intToBytes(int v, byte[] arr)
Returns a Little-Endian byte array extracted from the given int.

Parameters:
  `v` - the given int
  `arr` - a given array of 4 bytes that will be returned with the data
Returns:
  a Little-Endian byte array extracted from the given int.

### longToBytes

public static byte[] longToBytes(long v, byte[] arr)
Returns a Little-Endian byte array extracted from the given long.

Parameters:
  `v` - the given long
  `arr` - a given array of 8 bytes that will be returned with the data
Returns:
  a Little-Endian byte array extracted from the given long.

### longToHexBytes

public static String longToHexBytes(long v)
Returns a string of spaced hex bytes in Big-Endian order.

Parameters:
  `v` - the given long
Returns:
  string of spaced hex bytes in Big-Endian order.

### bytesToString

public static String bytesToString(byte[] arr, boolean signed, boolean littleEndian, String sep)
Returns a string view of a byte array

Parameters:
  `arr` - the given byte array
  `signed` - set true if you want the byte values signed.
  `littleEndian` - set true if you want Little-Endian order
  `sep` - the separator string between bytes
Returns:
  a string view of a byte array

### nanoSecToString

public static String nanoSecToString(long nS)
Returns the given time in nanoseconds formatted as Sec.mSec_uSec_nSec

Parameters:
  `nS` - the given nanoseconds
Returns:
  the given time in nanoseconds formatted as Sec.mSec_uSec_nSec

### milliSecToString

public static String milliSecToString(long mS)
Returns the given time in milliseconds formatted as Hours:Min:Sec.mSec

Parameters:
  `mS` - the given milliseconds
Returns:
  the given time in milliseconds formatted as Hours:Min:Sec.mSec

### zeroPad

public static String zeroPad(String s, int fieldLength)
Prepend the given string with zeros. If the given string is equal or greater than the given field length, it will be returned without modification.

Parameters:
  `s` - the given string
  `fieldLength` - desired total field length including the given string
Returns:
  the given string prepended with zeros.

### characterPad

public static String characterPad(String s, int fieldLength, char padChar, boolean postpend)
Prepend or postpend the given string with the given character to fill the given field length. If the given string is equal to or greater than the given field length, it will be returned without modification.

Parameters:
  `s` - the given string
  `fieldLength` - the desired field length
  `padChar` - the desired pad character
  `postpend` - if true append the pacCharacters to the end of the string.
Returns:
  prepended or postpended given string with the given character to fill the given field length.

### checkIfMultipleOf8AndGT0

public static void checkIfMultipleOf8AndGT0(long v, String argName)
Checks if parameter v is a multiple of 8 and greater than zero.

Parameters:
  `v` - The parameter to check
  `argName` - This name will be part of the error message if the check fails.

### isMultipleOf8AndGT0

public static boolean isMultipleOf8AndGT0(long v)
Returns true if v is a multiple of 8 and greater than zero

Parameters:
  `v` - The parameter to check
Returns:
  true if v is a multiple of 8 and greater than zero

### isPowerOf2

public static boolean isPowerOf2(long n)
Returns true if given long argument is exactly a positive power of 2.

Parameters:
  `n` - The input argument.
Returns:
  true if argument is exactly a positive power of 2.

### checkIfPowerOf2

public static void checkIfPowerOf2(long n, String argName)
Checks the given long argument if it is a positive integer power of 2. If not, it throws an exception with the user supplied local argument name, if not null.

Parameters:
  `n` - The input long argument must be a positive integer power of 2.
  `argName` - Used in the thrown exception. It may be null.
Throws:
  `SketchesArgumentException` - if not a positive integer power of 2.

### ceilingPowerOf2

public static int ceilingPowerOf2(int n)
Computes the int ceiling power of 2 within the range [1, 2^30]. This is the smallest positive power of 2 that is equal to or greater than the given n and a positive integer.

For:

- n ≤ 1: returns 1
- 2^30 ≤ n ≤ 2^31 -1 : returns 2^30
- n == an exact power of 2 : returns n
- otherwise returns the smallest power of 2 ≥ n and equal to a positive integer

Parameters:
  `n` - The input int argument.
Returns:
  the ceiling power of 2.

### ceilingPowerOf2

public static long ceilingPowerOf2(long n)
Computes the long ceiling power of 2 within the range [1, 2^62]. This is the smallest positive power of 2 that is equal to or greater than the given n and a positive long.

For:

- n ≤ 1: returns 1
- 2^62 ≤ n ≤ 2^63 -1 : returns 2^62
- n == an exact power of 2 : returns n
- otherwise returns the smallest power of 2 ≥ n and equal to a positive long

Parameters:
  `n` - The input long argument.
Returns:
  the ceiling power of 2.

### floorPowerOf2

public static int floorPowerOf2(int n)
Computes the floor power of 2 given n is in the range [1, 2^31-1]. This is the largest positive power of 2 that equal to or less than the given n and equal to a positive integer.

For:

- n ≤ 1: returns 1
- 2^30 ≤ n ≤ 2^31 -1 : returns 2^30
- n == a power of 2 : returns n
- otherwise returns the largest power of 2 less than n and equal to a mathematical integer.

Parameters:
  `n` - The given int argument.
Returns:
  the floor power of 2 as an int.

### floorPowerOf2

public static long floorPowerOf2(long n)
Computes the floor power of 2 given n is in the range [1, 2^63-1]. This is the largest positive power of 2 that is equal to or less than the given n and equal to a positive integer.

For:

- n ≤ 1: returns 1
- 2^62 ≤ n ≤ 2^63 -1 : returns 2^62
- n == a power of 2 : returns n
- otherwise returns the largest power of 2 less than n and equal to a mathematical integer.

Parameters:
  `n` - The given long argument.
Returns:
  the floor power of 2 as a long

### invPow2

public static double invPow2(int e)
Computes the inverse integer power of 2: 1/(2^e) = 2^(-e).

Parameters:
  `e` - a positive value between 0 and 1023 inclusive
Returns:
  the inverse integer power of 2: 1/(2^e) = 2^(-e)

### pwr2SeriesNext

public static long pwr2SeriesNext(int ppo, long curPoint)
Computes the next larger integer point in the power series point = 2( i / ppo ) given the current point in the series. For illustration, this can be used in a loop as follows:

         int maxP = 1024;
         int minP = 1;
         int ppo = 2;

         for (int p = minP; p <= maxP; p = pwr2LawNext(ppo, p)) {
           System.out.print(p + " ");
         }
         //generates the following series:
         //1 2 3 4 6 8 11 16 23 32 45 64 91 128 181 256 362 512 724 1024

Parameters:
  `ppo` - Points-Per-Octave, or the number of points per integer powers of 2 in the series.
  `curPoint` - the current point of the series. Must be ≥ 1.
Returns:
  the next point in the power series.

### pwr2SeriesPrev

public static int pwr2SeriesPrev(int ppo, int curPoint)
Computes the previous, smaller integer point in the power series point = 2( i / ppo ) given the current point in the series. For illustration, this can be used in a loop as follows:

         int maxP = 1024;
         int minP = 1;
         int ppo = 2;

         for (int p = maxP; p >= minP; p = pwr2LawPrev(ppo, p)) {
           System.out.print(p + " ");
         }
         //generates the following series:
         //1024 724 512 362 256 181 128 91 64 45 32 23 16 11 8 6 4 3 2 1

Parameters:
  `ppo` - Points-Per-Octave, or the number of points per integer powers of 2 in the series.
  `curPoint` - the current point of the series. Must be ≥ 1.
Returns:
  the previous, smaller point in the power series. A returned value of zero terminates the series.

### powerSeriesNextDouble

public static double powerSeriesNextDouble(int ppb, double curPoint, boolean roundToLong, double logBase)
Computes the next larger double in the power series point = logBase( i / ppb ) given the current point in the series. For illustration, this can be used in a loop as follows:

         double maxP = 1024.0;
         double minP = 1.0;
         int ppb = 2;
         double logBase = 2.0;

         for (double p = minP; p <= maxP; p = powerSeriesNextDouble(ppb, p, true, logBase)) {
           System.out.print(p + " ");
         }
         //generates the following series:
         //1 2 3 4 6 8 11 16 23 32 45 64 91 128 181 256 362 512 724 1024

Parameters:
  `ppb` - Points-Per-Base, or the number of points per integer powers of base in the series.
  `curPoint` - the current point of the series. Must be ≥ 1.0.
  `roundToLong` - if true the output will be rounded to the nearest long.
  `logBase` - the desired base of the logarithms
Returns:
  the next point in the power series.

### ceilingPowerBaseOfDouble

public static double ceilingPowerBaseOfDouble(double base, double n)
Returns the ceiling of a given n given a base, where the ceiling is an integral power of the base. This is the smallest positive power of base that is equal to or greater than the given n and equal to a mathematical integer. The result of this function is consistent with `ceilingPowerOf2(int)` for values less than one. I.e., if n < 1, the result is 1.

The formula is: baseceiling(logbase(x))

Parameters:
  `base` - The number in the expression ⌈basen⌉.
  `n` - The input argument.
Returns:
  the ceiling power of base as a double and equal to a mathematical integer.

### floorPowerBaseOfDouble

public static double floorPowerBaseOfDouble(double base, double n)
Computes the floor of a given n given base, where the floor is an integral power of the base. This is the largest positive power of base that is equal to or less than the given n and equal to a mathematical integer. The result of this function is consistent with `floorPowerOf2(int)` for values less than one. I.e., if n < 1, the result is 1.

The formula is: basefloor(logbase(x))

Parameters:
  `base` - The number in the expression ⌊basen⌋.
  `n` - The input argument.
Returns:
  the floor power of 2 and equal to a mathematical integer.

### log2

public static double log2(double value)
The log2(value)

Parameters:
  `value` - the given value
Returns:
  log2(value)

### logBaseOfX

public static double logBaseOfX(double base, double x)
Returns the logbase(x). Example, if base = 2.0: logB(2.0, x) = log(x) / log(2.0).

Parameters:
  `base` - The number in the expression log(x) / log(base).
  `x` - the given value
Returns:
  the logbase(x)

### numberOfTrailingOnes

public static int numberOfTrailingOnes(long v)
Returns the number of one bits following the lowest-order ("rightmost") zero-bit in the two's complement binary representation of the specified long value, or 64 if the value is equal to minus one.

Parameters:
  `v` - the value whose number of trailing ones is to be computed.
Returns:
  the number of one bits following the lowest-order ("rightmost") zero-bit in the two's complement binary representation of the specified long value, or 64 if the value is equal to minus one.

### numberOfLeadingOnes

public static int numberOfLeadingOnes(long v)
Returns the number of one bits preceding the highest-order ("leftmost") zero-bit in the two's complement binary representation of the specified long value, or 64 if the value is equal to minus one.

Parameters:
  `v` - the value whose number of leading ones is to be computed.
Returns:
  the number of one bits preceding the lowest-order ("rightmost") zero-bit in the two's complement binary representation of the specified long value, or 64 if the value is equal to minus one.

### exactLog2OfInt

public static int exactLog2OfInt(int powerOf2, String argName)
Returns the log2 of the given int value if it is an exact power of 2 and greater than zero. If not, it throws an exception with the user supplied local argument name.

Parameters:
  `powerOf2` - must be a power of 2 and greater than zero.
  `argName` - the argument name used in the exception if thrown.
Returns:
  the log2 of the given value if it is an exact power of 2 and greater than zero.
Throws:
  `SketchesArgumentException` - if not a power of 2 nor greater than zero.

### exactLog2OfLong

public static int exactLog2OfLong(long powerOf2, String argName)
Returns the log2 of the given long value if it is an exact power of 2 and greater than zero. If not, it throws an exception with the user supplied local argument name.

Parameters:
  `powerOf2` - must be a power of 2 and greater than zero.
  `argName` - the argument name used in the exception if thrown.
Returns:
  the log2 of the given value if it is an exact power of 2 and greater than zero.
Throws:
  `SketchesArgumentException` - if not a power of 2 nor greater than zero.

### exactLog2OfInt

public static int exactLog2OfInt(int powerOf2)
Returns the log2 of the given int value if it is an exact power of 2 and greater than zero. If not, it throws an exception.

Parameters:
  `powerOf2` - must be a power of 2 and greater than zero.
Returns:
  the log2 of the given int value if it is an exact power of 2 and greater than zero.

### exactLog2OfLong

public static int exactLog2OfLong(long powerOf2)
Returns the log2 of the given long value if it is an exact power of 2 and greater than zero. If not, it throws an exception.

Parameters:
  `powerOf2` - must be a power of 2 and greater than zero.
Returns:
  the log2 of the given long value if it is an exact power of 2 and greater than zero.

### checkBounds

public static void checkBounds(long reqOff, long reqLen, long allocSize)
Check the requested offset and length against the allocated size. The invariants equation is: `0 <= reqOff <= reqLen <= reqOff + reqLen <= allocSize`. If this equation is violated an `SketchesArgumentException` will be thrown.

Parameters:
  `reqOff` - the requested offset
  `reqLen` - the requested length
  `allocSize` - the allocated size.

### checkProbability

public static void checkProbability(double p, String argName)
Checks the given parameter to make sure it is positive and between 0.0 inclusive and 1.0 inclusive.

Parameters:
  `p` - See Sampling Probability, p
  `argName` - Used in the thrown exception.

### isLessThanUnsigned

public static boolean isLessThanUnsigned(long n1, long n2)
Unsigned compare with longs.

Parameters:
  `n1` - A long to be treated as if unsigned.
  `n2` - A long to be treated as if unsigned.
Returns:
  true if n1 > n2.

### isEven

public static boolean isEven(long n)
Returns true if given n is even.

Parameters:
  `n` - the given n
Returns:
  true if given n is even.

### isOdd

public static boolean isOdd(long n)
Returns true if given n is odd.

Parameters:
  `n` - the given n
Returns:
  true if given n is odd.

### bitAt

public static final int bitAt(long number, int bitPos)
Returns a one if the bit at bitPos is a one, otherwise zero.

Parameters:
  `number` - the number to examine
  `bitPos` - the given zero-based bit position, where the least significant bit is at position zero.
Returns:
  a one if the bit at bitPos is a one, otherwise zero.

### numDigits

public static int numDigits(long n)
Computes the number of decimal digits of the number n

Parameters:
  `n` - the given number
Returns:
  the number of decimal digits of the number n

### longToFixedLengthString

public static String longToFixedLengthString(long number, int length)
Converts the given number to a string prepended with spaces, if necessary, to match the given length.

For example, assume a sequence of integers from 1 to 1000. The largest value has four decimal digits. Convert the entire sequence of strings to the form " 1" to "1000". When these strings are sorted they will be in numerical sequence: " 1", " 2", ... "1000".

Parameters:
  `number` - the given number
  `length` - the desired string length.
Returns:
  the given number to a string prepended with spaces

### minT

public static <T> Object minT(Object item1, Object item2, Comparator<? super T> c)
Finds the minimum of two generic items

Type Parameters:
  `T` - the type
Parameters:
  `item1` - item one
  `item2` - item two
  `c` - the given comparator
Returns:
  the minimum value

### maxT

public static <T> Object maxT(Object item1, Object item2, Comparator<? super T> c)
Finds the maximum of two generic items

Type Parameters:
  `T` - the type
Parameters:
  `item1` - item one
  `item2` - item two
  `c` - the given comparator
Returns:
  the maximum value

### lt

public static <T> boolean lt(Object item1, Object item2, Comparator<? super T> c)
Is item1 Less-Than item2

Type Parameters:
  `T` - the type
Parameters:
  `item1` - item one
  `item2` - item two
  `c` - the given comparator
Returns:
  true if item1 Less-Than item2

### le

public static <T> boolean le(Object item1, Object item2, Comparator<? super T> c)
Is item1 Less-Than-Or-Equal-To item2

Type Parameters:
  `T` - the type
Parameters:
  `item1` - item one
  `item2` - item two
  `c` - the given comparator
Returns:
  true if item1 Less-Than-Or-Equal-To item2