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: base^{ceiling(log_base(x))}

Parameters:

base - The number in the expression ⌈baseⁿ⌉.

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: base^{floor(log_base(x))}

Parameters:

base - The number in the expression ⌊baseⁿ⌋.

n - The input argument.

Returns:

the floor power of 2 and equal to a mathematical integer.

log2

public static double log2(double value)

The log₂(value)

Parameters:

value - the given value

Returns:

log₂(value)

logBaseOfX

public static double logBaseOfX(double base,
 double x)

Returns the log_base(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 log_base(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