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 double
INVERSE_GOLDEN
The inverse golden ratio as a fraction.static long
INVERSE_GOLDEN_U64
The inverse golden ratio as an unsigned long.static double
LOG2
The natural logarithm of 2.0.static double
LONG_MAX_VALUE_AS_DOUBLE
Long.MAX_VALUE as a double.static String
LS
The java line separator character as a String.static char
TAB
The tab character
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static 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 arraystatic 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 zerostatic 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 item2static 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 item2static <T> Object
maxT(Object item1, Object item2, Comparator<? super T> c)
Finds the maximum of two generic itemsstatic String
milliSecToString(long mS)
Returns the given time in milliseconds formatted as Hours:Min:Sec.mSecstatic <T> Object
minT(Object item1, Object item2, Comparator<? super T> c)
Finds the minimum of two generic itemsstatic String
nanoSecToString(long nS)
Returns the given time in nanoseconds formatted as Sec.mSec_uSec_nSecstatic 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 nstatic 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.
-
-
-
Field Detail
-
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 Detail
-
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 intarr
- 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 longarr
- 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 arraysigned
- set true if you want the byte values signed.littleEndian
- set true if you want Little-Endian ordersep
- 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 stringfieldLength
- 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 stringfieldLength
- the desired field lengthpadChar
- the desired pad characterpostpend
- 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 checkargName
- 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 withceilingPowerOf2(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 withfloorPowerOf2(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 anSketchesArgumentException
will be thrown.- Parameters:
reqOff
- the requested offsetreqLen
- the requested lengthallocSize
- 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, pargName
- 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 examinebitPos
- 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 numberlength
- 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 oneitem2
- item twoc
- 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 oneitem2
- item twoc
- 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 oneitem2
- item twoc
- 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 oneitem2
- item twoc
- the given comparator- Returns:
- true if item1 Less-Than-Or-Equal-To item2
-
-