Package org.apache.datasketches.common

Class 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 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 int ceilingIntPowerOf2​(int n)
      Computes the int ceiling power of 2 within the range [1, 2^30].
      static long ceilingLongPowerOf2​(long n)
      Computes the long ceiling power of 2 within the range [1, 2^30].
      static double ceilingPowerBaseOfDouble​(double base, double n)
      Computes the ceiling power of given base and n as doubles.
      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 checkIfIntPowerOf2​(int powerOf2, String argName)
      Checks the given int argument to make sure it is a positive power of 2 and greater than zero.
      static void checkIfLongPowerOf2​(long powerOf2, String argName)
      Checks the given long argument to make sure it is a positive power of 2 and greater than zero.
      static void checkIfMultipleOf8AndGT0​(long v, String argName)
      Checks if parameter v is a multiple of 8 and greater than zero.
      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 power of given base and n as doubles.
      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 String intToFixedLengthString​(int number, int length)
      Converts the given number to a string prepended with spaces, if necessary, to match the given length.
      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 isIntPowerOf2​(int powerOf2)
      Returns true if given int argument is exactly a positive power of 2 and greater than zero.
      static boolean isLessThanUnsigned​(long n1, long n2)
      Unsigned compare with longs.
      static boolean isLongPowerOf2​(long powerOf2)
      Returns true if given long argument is exactly a positive power of 2 and greater than zero.
      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 <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 log base 2 of the value
      static double logBaseOfX​(double logBase, double x)
      Returns the logarithm_logBase of x.
      static byte[] longToBytes​(long v, byte[] arr)
      Returns a Little-Endian byte array extracted from the given long.
      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​(int 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.

    • Field Detail

      • LS

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

      • 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 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 nanoseconds
        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 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

      • isIntPowerOf2

        public static boolean isIntPowerOf2​(int powerOf2)
        Returns true if given int argument is exactly a positive power of 2 and greater than zero.
        Parameters:
        powerOf2 - The input argument.
        Returns:
        true if argument is exactly a positive power of 2 and greater than zero.

      • isLongPowerOf2

        public static boolean isLongPowerOf2​(long powerOf2)
        Returns true if given long argument is exactly a positive power of 2 and greater than zero.
        Parameters:
        powerOf2 - The input argument.
        Returns:
        true if argument is exactly a positive power of 2 and greater than zero.

      • checkIfIntPowerOf2

        public static void checkIfIntPowerOf2​(int powerOf2,
                                      String argName)
        Checks the given int argument to make sure it is a positive power of 2 and greater than zero. If not it throws an exception with the user supplied local argument name.
        Parameters:
        powerOf2 - The input int argument must be a power of 2 and greater than zero.
        argName - Used in the thrown exception.
        Throws:
        SketchesArgumentException - if not a power of 2 nor greater than zero.

      • checkIfLongPowerOf2

        public static void checkIfLongPowerOf2​(long powerOf2,
                                       String argName)
        Checks the given long argument to make sure it is a positive power of 2 and greater than zero. If not, it throws an exception with the user supplied local argument name.
        Parameters:
        powerOf2 - The input long argument must be a power of 2 and greater than zero.
        argName - Used in the thrown exception.
        Throws:
        SketchesArgumentException - if not a power of 2 nor greater than zero.

      • ceilingIntPowerOf2

        public static int ceilingIntPowerOf2​(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 mathematical 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 mathematical integer
        Parameters:
        n - The input int argument.
        Returns:
        the ceiling power of 2.

      • ceilingLongPowerOf2

        public static long ceilingLongPowerOf2​(long n)
        Computes the long 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 mathematical integer.

        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 mathematical integer
        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 mathematical 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 mathematical 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)
        Computes the ceiling power of given base and n as doubles. This is the smallest positive power of base that equal to or greater than the given n and equal to a mathematical integer. The result of this function is consistent with ceilingIntPowerOf2(int) for values less than one. I.e., if n < 1, the result is 1.
        Parameters:
        base - The base 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 power of given base and n as doubles. This is the largest positive power of base that 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.
        Parameters:
        base - The base 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 log base 2 of the value
        Parameters:
        value - the given value
        Returns:
        The log base 2 of the value

      • logBaseOfX

        public static double logBaseOfX​(double logBase,
                                double x)
        Returns the logarithm_logBase of x. Example: logB(2.0, x) = log(x) / log(2.0).
        Parameters:
        logBase - the base of the logarithm used
        x - the given value
        Returns:
        the logarithm_logBase of x: Example: logB(2.0, x) = log(x) / log(2.0).

      • 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.

      • numDigits

        public static int numDigits​(int 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

      • intToFixedLengthString

        public static String intToFixedLengthString​(int 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