Class Utility


  • public final class Utility
    extends Object
    • Constructor Summary

      Constructors 
      Constructor Description
      Utility()  
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static <T extends Appendable>
      T
      appendNumber​(T result, int n, int radix, int minDigits)
      Append a number to the given Appendable in the given radix.
      static void appendToRule​(StringBuffer rule, int c, boolean isLiteral, boolean escapeUnprintable, StringBuffer quoteBuf)
      Append a character to a rule that is being built up.
      static void appendToRule​(StringBuffer rule, UnicodeMatcher matcher, boolean escapeUnprintable, StringBuffer quoteBuf)
      Given a matcher reference, which may be null, append its pattern as a literal to the given rule.
      static void appendToRule​(StringBuffer rule, String text, boolean isLiteral, boolean escapeUnprintable, StringBuffer quoteBuf)
      Append the given string to the rule.
      static boolean arrayEquals​(byte[] source, Object target)  
      static boolean arrayEquals​(double[] source, Object target)
      Convenience utility to compare two double[]s Ought to be in System
      static boolean arrayEquals​(int[] source, Object target)
      Convenience utility to compare two int[]s Ought to be in System
      static boolean arrayEquals​(Object[] source, Object target)
      Convenience utility to compare two Object[]s.
      static boolean arrayEquals​(Object source, Object target)
      Convenience utility to compare two Object[]s Ought to be in System
      static boolean arrayRegionMatches​(byte[] source, int sourceStart, byte[] target, int targetStart, int len)  
      static boolean arrayRegionMatches​(char[] source, int sourceStart, char[] target, int targetStart, int len)
      Convenience utility to compare two Object[]s Ought to be in System.
      static boolean arrayRegionMatches​(double[] source, int sourceStart, double[] target, int targetStart, int len)
      Convenience utility to compare two arrays of doubles.
      static boolean arrayRegionMatches​(int[] source, int sourceStart, int[] target, int targetStart, int len)
      Convenience utility to compare two int[]s.
      static boolean arrayRegionMatches​(Object[] source, int sourceStart, Object[] target, int targetStart, int len)
      Convenience utility to compare two Object[]s Ought to be in System.
      static String arrayToRLEString​(byte[] a)
      Construct a string representing a byte array.
      static String arrayToRLEString​(char[] a)
      Construct a string representing a char array.
      static String arrayToRLEString​(int[] a)
      Construct a string representing an int array.
      static String arrayToRLEString​(short[] a)
      Construct a string representing a short array.
      static <T extends Comparable<T>>
      int
      checkCompare​(T a, T b)
      Convenience utility.
      static int checkHash​(Object a)
      Convenience utility.
      static int compareUnsigned​(int source, int target)
      Compares 2 unsigned integers
      static String escape​(String s)
      Convert characters outside the range U+0020 to U+007F to Unicode escapes, and convert backslash to a double backslash.
      static <T extends Appendable>
      boolean
      escapeUnprintable​(T result, int c)
      Escape unprintable characters using uxxxx notation for U+0000 to U+FFFF and Uxxxxxxxx for U+10000 and above.
      static String format1ForSource​(String s)
      Format a String for representation in a source file.
      static String formatForSource​(String s)
      Format a String for representation in a source file.
      static String fromHex​(String string, int minLength, String separator)
      Parse a list of hex numbers and return a string
      static String fromHex​(String string, int minLength, Pattern separator)
      Parse a list of hex numbers and return a string
      static String hex​(byte[] o, int start, int end, String separator)  
      static String hex​(long ch)
      Convert a char to 4 hex uppercase digits.
      static String hex​(long i, int places)
      Supplies a zero-padded hex representation of an integer (without 0x)
      static String hex​(CharSequence s)
      Convert a string to comma-separated groups of 4 hex uppercase digits.
      static <S extends CharSequence>
      String
      hex​(S s, int width, S separator)
      Convert a string to comma-separated groups of 4 hex uppercase digits.
      static <S extends CharSequence,​U extends CharSequence,​T extends Appendable>
      T
      hex​(S s, int width, U separator, boolean useCodePoints, T result)
      Convert a string to separated groups of hex uppercase digits.
      static byte highBit​(int n)
      Find the highest bit in a positive integer.
      static boolean isUnprintable​(int c)
      Return true if the character is NOT printable ASCII.
      static int lookup​(String source, String[] target)
      Look up a given string in a string array.
      static boolean objectEquals​(Object a, Object b)
      Convenience utility.
      static boolean parseChar​(String id, int[] pos, char ch)
      Parse a single non-whitespace character 'ch', optionally preceded by whitespace.
      static int parseInteger​(String rule, int[] pos, int limit)
      Parse an integer at pos, either of the form \d+ or of the form 0x[0-9A-Fa-f]+ or 0[0-7]+, that is, in standard decimal, hex, or octal format.
      static int parseNumber​(String text, int[] pos, int radix)
      Parse an unsigned 31-bit integer at the given offset.
      static int parsePattern​(String rule, int pos, int limit, String pattern, int[] parsedInts)
      Parse a pattern string starting at offset pos.
      static int parsePattern​(String pat, Replaceable text, int index, int limit)
      Parse a pattern string within the given Replaceable and a parsing pattern.
      static String parseUnicodeIdentifier​(String str, int[] pos)
      Parse a Unicode identifier from the given string at the given position.
      static int quotedIndexOf​(String text, int start, int limit, String setOfChars)
      Returns the index of the first character in a set, ignoring quoted text.
      static String repeat​(String s, int count)
      Utility to duplicate a string count times
      static byte[] RLEStringToByteArray​(String s)
      Construct an array of bytes from a run-length encoded string.
      static char[] RLEStringToCharArray​(String s)
      Construct an array of shorts from a run-length encoded string.
      static int[] RLEStringToIntArray​(String s)
      Construct an array of ints from a run-length encoded string.
      static short[] RLEStringToShortArray​(String s)
      Construct an array of shorts from a run-length encoded string.
      static String[] split​(String s, char divider)
      Split a string into pieces based on the given divider character
      static void split​(String s, char divider, String[] output)
      Split a string into pieces based on the given divider character
      static String[] splitString​(String src, String target)  
      static String[] splitWhitespace​(String src)
      Split the string at runs of ascii whitespace characters.
      static String unescape​(String s)
      Convert all escapes in a given string using unescapeAt().
      static int unescapeAt​(String s, int[] offset16)
      Convert an escape to a 32-bit code point value.
      static String unescapeLeniently​(String s)
      Convert all escapes in a given string using unescapeAt().
      static String valueOf​(int[] source)
      Utility method to take a int[] containing codepoints and return a string representation with code units.
    • Field Detail

      • LINE_SEPARATOR

        public static String LINE_SEPARATOR
    • Constructor Detail

      • Utility

        public Utility()
    • Method Detail

      • arrayEquals

        public static final boolean arrayEquals​(Object[] source,
                                                Object target)
        Convenience utility to compare two Object[]s. Ought to be in System
      • arrayEquals

        public static final boolean arrayEquals​(int[] source,
                                                Object target)
        Convenience utility to compare two int[]s Ought to be in System
      • arrayEquals

        public static final boolean arrayEquals​(double[] source,
                                                Object target)
        Convenience utility to compare two double[]s Ought to be in System
      • arrayEquals

        public static final boolean arrayEquals​(byte[] source,
                                                Object target)
      • arrayEquals

        public static final boolean arrayEquals​(Object source,
                                                Object target)
        Convenience utility to compare two Object[]s Ought to be in System
      • arrayRegionMatches

        public static final boolean arrayRegionMatches​(Object[] source,
                                                       int sourceStart,
                                                       Object[] target,
                                                       int targetStart,
                                                       int len)
        Convenience utility to compare two Object[]s Ought to be in System.
        Parameters:
        len - the length to compare. The start indices and start+len must be valid.
      • arrayRegionMatches

        public static final boolean arrayRegionMatches​(char[] source,
                                                       int sourceStart,
                                                       char[] target,
                                                       int targetStart,
                                                       int len)
        Convenience utility to compare two Object[]s Ought to be in System.
        Parameters:
        len - the length to compare. The start indices and start+len must be valid.
      • arrayRegionMatches

        public static final boolean arrayRegionMatches​(int[] source,
                                                       int sourceStart,
                                                       int[] target,
                                                       int targetStart,
                                                       int len)
        Convenience utility to compare two int[]s.
        Parameters:
        len - the length to compare. The start indices and start+len must be valid. Ought to be in System
      • arrayRegionMatches

        public static final boolean arrayRegionMatches​(double[] source,
                                                       int sourceStart,
                                                       double[] target,
                                                       int targetStart,
                                                       int len)
        Convenience utility to compare two arrays of doubles.
        Parameters:
        len - the length to compare. The start indices and start+len must be valid. Ought to be in System
      • arrayRegionMatches

        public static final boolean arrayRegionMatches​(byte[] source,
                                                       int sourceStart,
                                                       byte[] target,
                                                       int targetStart,
                                                       int len)
      • objectEquals

        public static final boolean objectEquals​(Object a,
                                                 Object b)
        Convenience utility. Does null checks on objects, then calls equals.
      • checkCompare

        public static <T extends Comparable<T>> int checkCompare​(T a,
                                                                 T b)
        Convenience utility. Does null checks on objects, then calls compare.
      • checkHash

        public static int checkHash​(Object a)
        Convenience utility. Does null checks on object, then calls hashCode.
      • arrayToRLEString

        public static final String arrayToRLEString​(int[] a)
        Construct a string representing an int array. Use run-length encoding. A character represents itself, unless it is the ESCAPE character. Then the following notations are possible: ESCAPE ESCAPE ESCAPE literal ESCAPE n c n instances of character c Since an encoded run occupies 3 characters, we only encode runs of 4 or more characters. Thus we have n > 0 and n != ESCAPE and n <= 0xFFFF. If we encounter a run where n == ESCAPE, we represent this as: c ESCAPE n-1 c The ESCAPE value is chosen so as not to collide with commonly seen values.
      • arrayToRLEString

        public static final String arrayToRLEString​(short[] a)
        Construct a string representing a short array. Use run-length encoding. A character represents itself, unless it is the ESCAPE character. Then the following notations are possible: ESCAPE ESCAPE ESCAPE literal ESCAPE n c n instances of character c Since an encoded run occupies 3 characters, we only encode runs of 4 or more characters. Thus we have n > 0 and n != ESCAPE and n <= 0xFFFF. If we encounter a run where n == ESCAPE, we represent this as: c ESCAPE n-1 c The ESCAPE value is chosen so as not to collide with commonly seen values.
      • arrayToRLEString

        public static final String arrayToRLEString​(char[] a)
        Construct a string representing a char array. Use run-length encoding. A character represents itself, unless it is the ESCAPE character. Then the following notations are possible: ESCAPE ESCAPE ESCAPE literal ESCAPE n c n instances of character c Since an encoded run occupies 3 characters, we only encode runs of 4 or more characters. Thus we have n > 0 and n != ESCAPE and n <= 0xFFFF. If we encounter a run where n == ESCAPE, we represent this as: c ESCAPE n-1 c The ESCAPE value is chosen so as not to collide with commonly seen values.
      • arrayToRLEString

        public static final String arrayToRLEString​(byte[] a)
        Construct a string representing a byte array. Use run-length encoding. Two bytes are packed into a single char, with a single extra zero byte at the end if needed. A byte represents itself, unless it is the ESCAPE_BYTE. Then the following notations are possible: ESCAPE_BYTE ESCAPE_BYTE ESCAPE_BYTE literal ESCAPE_BYTE n b n instances of byte b Since an encoded run occupies 3 bytes, we only encode runs of 4 or more bytes. Thus we have n > 0 and n != ESCAPE_BYTE and n <= 0xFF. If we encounter a run where n == ESCAPE_BYTE, we represent this as: b ESCAPE_BYTE n-1 b The ESCAPE_BYTE value is chosen so as not to collide with commonly seen values.
      • RLEStringToIntArray

        public static final int[] RLEStringToIntArray​(String s)
        Construct an array of ints from a run-length encoded string.
      • RLEStringToShortArray

        public static final short[] RLEStringToShortArray​(String s)
        Construct an array of shorts from a run-length encoded string.
      • RLEStringToCharArray

        public static final char[] RLEStringToCharArray​(String s)
        Construct an array of shorts from a run-length encoded string.
      • RLEStringToByteArray

        public static final byte[] RLEStringToByteArray​(String s)
        Construct an array of bytes from a run-length encoded string.
      • formatForSource

        public static final String formatForSource​(String s)
        Format a String for representation in a source file. This includes breaking it into lines and escaping characters using octal notation when necessary (control characters and double quotes).
      • format1ForSource

        public static final String format1ForSource​(String s)
        Format a String for representation in a source file. Like formatForSource but does not do line breaking.
      • escape

        public static final String escape​(String s)
        Convert characters outside the range U+0020 to U+007F to Unicode escapes, and convert backslash to a double backslash.
      • unescapeAt

        public static int unescapeAt​(String s,
                                     int[] offset16)
        Convert an escape to a 32-bit code point value. We attempt to parallel the icu4c unescapeAt() function.
        Parameters:
        offset16 - an array containing offset to the character after the backslash. Upon return offset16[0] will be updated to point after the escape sequence.
        Returns:
        character value from 0 to 10FFFF, or -1 on error.
      • unescapeLeniently

        public static String unescapeLeniently​(String s)
        Convert all escapes in a given string using unescapeAt(). Leave invalid escape sequences unchanged.
      • hex

        public static String hex​(long ch)
        Convert a char to 4 hex uppercase digits. E.g., hex('a') => "0041".
      • hex

        public static String hex​(long i,
                                 int places)
        Supplies a zero-padded hex representation of an integer (without 0x)
      • hex

        public static String hex​(CharSequence s)
        Convert a string to comma-separated groups of 4 hex uppercase digits. E.g., hex('ab') => "0041,0042".
      • hex

        public static <S extends CharSequence,​U extends CharSequence,​T extends Appendable> T hex​(S s,
                                                                                                             int width,
                                                                                                             U separator,
                                                                                                             boolean useCodePoints,
                                                                                                             T result)
        Convert a string to separated groups of hex uppercase digits. E.g., hex('ab'...) => "0041,0042". Append the output to the given Appendable.
      • hex

        public static String hex​(byte[] o,
                                 int start,
                                 int end,
                                 String separator)
      • hex

        public static <S extends CharSequenceString hex​(S s,
                                                          int width,
                                                          S separator)
        Convert a string to comma-separated groups of 4 hex uppercase digits. E.g., hex('ab') => "0041,0042".
      • split

        public static void split​(String s,
                                 char divider,
                                 String[] output)
        Split a string into pieces based on the given divider character
        Parameters:
        s - the string to split
        divider - the character on which to split. Occurrences of this character are not included in the output
        output - an array to receive the substrings between instances of divider. It must be large enough on entry to accomodate all output. Adjacent instances of the divider character will place empty strings into output. Before returning, output is padded out with empty strings.
      • split

        public static String[] split​(String s,
                                     char divider)
        Split a string into pieces based on the given divider character
        Parameters:
        s - the string to split
        divider - the character on which to split. Occurrences of this character are not included in the output
        Returns:
        output an array to receive the substrings between instances of divider. Adjacent instances of the divider character will place empty strings into output.
      • lookup

        public static int lookup​(String source,
                                 String[] target)
        Look up a given string in a string array. Returns the index at which the first occurrence of the string was found in the array, or -1 if it was not found.
        Parameters:
        source - the string to search for
        target - the array of zero or more strings in which to look for source
        Returns:
        the index of target at which source first occurs, or -1 if not found
      • parseChar

        public static boolean parseChar​(String id,
                                        int[] pos,
                                        char ch)
        Parse a single non-whitespace character 'ch', optionally preceded by whitespace.
        Parameters:
        id - the string to be parsed
        pos - INPUT-OUTPUT parameter. On input, pos[0] is the offset of the first character to be parsed. On output, pos[0] is the index after the last parsed character. If the parse fails, pos[0] will be unchanged.
        ch - the non-whitespace character to be parsed.
        Returns:
        true if 'ch' is seen preceded by zero or more whitespace characters.
      • parsePattern

        public static int parsePattern​(String rule,
                                       int pos,
                                       int limit,
                                       String pattern,
                                       int[] parsedInts)
        Parse a pattern string starting at offset pos. Keywords are matched case-insensitively. Spaces may be skipped and may be optional or required. Integer values may be parsed, and if they are, they will be returned in the given array. If successful, the offset of the next non-space character is returned. On failure, -1 is returned.
        Parameters:
        pattern - must only contain lowercase characters, which will match their uppercase equivalents as well. A space character matches one or more required spaces. A '~' character matches zero or more optional spaces. A '#' character matches an integer and stores it in parsedInts, which the caller must ensure has enough capacity.
        parsedInts - array to receive parsed integers. Caller must ensure that parsedInts.length is >= the number of '#' signs in 'pattern'.
        Returns:
        the position after the last character parsed, or -1 if the parse failed
      • parsePattern

        public static int parsePattern​(String pat,
                                       Replaceable text,
                                       int index,
                                       int limit)
        Parse a pattern string within the given Replaceable and a parsing pattern. Characters are matched literally and case-sensitively except for the following special characters: ~ zero or more Pattern_White_Space chars If end of pattern is reached with all matches along the way, pos is advanced to the first unparsed index and returned. Otherwise -1 is returned.
        Parameters:
        pat - pattern that controls parsing
        text - text to be parsed, starting at index
        index - offset to first character to parse
        limit - offset after last character to parse
        Returns:
        index after last parsed character, or -1 on parse failure.
      • parseInteger

        public static int parseInteger​(String rule,
                                       int[] pos,
                                       int limit)
        Parse an integer at pos, either of the form \d+ or of the form 0x[0-9A-Fa-f]+ or 0[0-7]+, that is, in standard decimal, hex, or octal format.
        Parameters:
        pos - INPUT-OUTPUT parameter. On input, the first character to parse. On output, the character after the last parsed character.
      • parseUnicodeIdentifier

        public static String parseUnicodeIdentifier​(String str,
                                                    int[] pos)
        Parse a Unicode identifier from the given string at the given position. Return the identifier, or null if there is no identifier.
        Parameters:
        str - the string to parse
        pos - INPUT-OUPUT parameter. On INPUT, pos[0] is the first character to examine. It must be less than str.length(), and it must not point to a whitespace character. That is, must have pos[0] < str.length(). On OUTPUT, the position after the last parsed character.
        Returns:
        the Unicode identifier, or null if there is no valid identifier at pos[0].
      • appendNumber

        public static <T extends Appendable> T appendNumber​(T result,
                                                            int n,
                                                            int radix,
                                                            int minDigits)
        Append a number to the given Appendable in the given radix. Standard digits '0'-'9' are used and letters 'A'-'Z' for radices 11 through 36.
        Parameters:
        result - the digits of the number are appended here
        n - the number to be converted to digits; may be negative. If negative, a '-' is prepended to the digits.
        radix - a radix from 2 to 36 inclusive.
        minDigits - the minimum number of digits, not including any '-', to produce. Values less than 2 have no effect. One digit is always emitted regardless of this parameter.
        Returns:
        a reference to result
      • parseNumber

        public static int parseNumber​(String text,
                                      int[] pos,
                                      int radix)
        Parse an unsigned 31-bit integer at the given offset. Use UCharacter.digit() to parse individual characters into digits.
        Parameters:
        text - the text to be parsed
        pos - INPUT-OUTPUT parameter. On entry, pos[0] is the offset within text at which to start parsing; it should point to a valid digit. On exit, pos[0] is the offset after the last parsed character. If the parse failed, it will be unchanged on exit. Must be >= 0 on entry.
        radix - the radix in which to parse; must be >= 2 and <= 36.
        Returns:
        a non-negative parsed number, or -1 upon parse failure. Parse fails if there are no digits, that is, if pos[0] does not point to a valid digit on entry, or if the number to be parsed does not fit into a 31-bit unsigned integer.
      • isUnprintable

        public static boolean isUnprintable​(int c)
        Return true if the character is NOT printable ASCII. The tab, newline and linefeed characters are considered unprintable.
      • escapeUnprintable

        public static <T extends Appendable> boolean escapeUnprintable​(T result,
                                                                       int c)
        Escape unprintable characters using uxxxx notation for U+0000 to U+FFFF and Uxxxxxxxx for U+10000 and above. If the character is printable ASCII, then do nothing and return FALSE. Otherwise, append the escaped notation and return TRUE.
      • quotedIndexOf

        public static int quotedIndexOf​(String text,
                                        int start,
                                        int limit,
                                        String setOfChars)
        Returns the index of the first character in a set, ignoring quoted text. For example, in the string "abc'hide'h", the 'h' in "hide" will not be found by a search for "h". Unlike String.indexOf(), this method searches not for a single character, but for any character of the string setOfChars.
        Parameters:
        text - text to be searched
        start - the beginning index, inclusive; 0 <= start <= limit.
        limit - the ending index, exclusive; start <= limit <= text.length().
        setOfChars - string with one or more distinct characters
        Returns:
        Offset of the first character in setOfChars found, or -1 if not found.
        See Also:
        String.indexOf(int)
      • appendToRule

        public static void appendToRule​(StringBuffer rule,
                                        int c,
                                        boolean isLiteral,
                                        boolean escapeUnprintable,
                                        StringBuffer quoteBuf)
        Append a character to a rule that is being built up. To flush the quoteBuf to rule, make one final call with isLiteral == true. If there is no final character, pass in (int)-1 as c.
        Parameters:
        rule - the string to append the character to
        c - the character to append, or (int)-1 if none.
        isLiteral - if true, then the given character should not be quoted or escaped. Usually this means it is a syntactic element such as > or $
        escapeUnprintable - if true, then unprintable characters should be escaped using escapeUnprintable(). These escapes will appear outside of quotes.
        quoteBuf - a buffer which is used to build up quoted substrings. The caller should initially supply an empty buffer, and thereafter should not modify the buffer. The buffer should be cleared out by, at the end, calling this method with a literal character (which may be -1).
      • appendToRule

        public static void appendToRule​(StringBuffer rule,
                                        String text,
                                        boolean isLiteral,
                                        boolean escapeUnprintable,
                                        StringBuffer quoteBuf)
        Append the given string to the rule. Calls the single-character version of appendToRule for each character.
      • appendToRule

        public static void appendToRule​(StringBuffer rule,
                                        UnicodeMatcher matcher,
                                        boolean escapeUnprintable,
                                        StringBuffer quoteBuf)
        Given a matcher reference, which may be null, append its pattern as a literal to the given rule.
      • compareUnsigned

        public static final int compareUnsigned​(int source,
                                                int target)
        Compares 2 unsigned integers
        Parameters:
        source - 32 bit unsigned integer
        target - 32 bit unsigned integer
        Returns:
        0 if equals, 1 if source is greater than target and -1 otherwise
      • highBit

        public static final byte highBit​(int n)
        Find the highest bit in a positive integer. This is done by doing a binary search through the bits.
        Parameters:
        n - is the integer
        Returns:
        the bit number of the highest bit, with 0 being the low order bit, or -1 if n is not positive
      • valueOf

        public static String valueOf​(int[] source)
        Utility method to take a int[] containing codepoints and return a string representation with code units.
      • repeat

        public static String repeat​(String s,
                                    int count)
        Utility to duplicate a string count times
        Parameters:
        s - String to be duplicated.
        count - Number of times to duplicate a string.
      • splitWhitespace

        public static String[] splitWhitespace​(String src)
        Split the string at runs of ascii whitespace characters.
      • fromHex

        public static String fromHex​(String string,
                                     int minLength,
                                     String separator)
        Parse a list of hex numbers and return a string
        Parameters:
        string - String of hex numbers.
        minLength - Minimal length.
        separator - Separator.
        Returns:
        A string from hex numbers.
      • fromHex

        public static String fromHex​(String string,
                                     int minLength,
                                     Pattern separator)
        Parse a list of hex numbers and return a string
        Parameters:
        string - String of hex numbers.
        minLength - Minimal length.
        separator - Separator.
        Returns:
        A string from hex numbers.