Package net.pwall.text

Class TextMatcher

  • public class TextMatcher
extends Object
    A text matching class to help with parsing text strings. It maintains a current pointer within a string and updates this pointer on a successful match.

    The TextMatcher has four main types of functions:

    Match functions
    These test the characters at the current index, and if successful, update the start index and the current index to reflect the matched characters
    Skip functions
    These advance the current pointer past one or more or a specified type of character (e.g. whitespace)
    GetResult functions
    These get the result of the last match in a number of forms
    General Get functions
    These get arbitrary data from the string
    Author:
    Peter Wall

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  TextMatcher.CharSeq
      An implementation of CharSequence to return data from TextMatcher.

    • Constructor Summary

      Constructors 
      Constructor Description
      TextMatcher​(String text)
      Construct a TextMatcher with the specified text.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static int convertDecDigit​(char ch)
      Convert a decimal digit to the integer value of the digit.
      static int convertHexDigit​(char ch)
      Convert a hexadecimal digit to the integer value of the digit.
      char getChar​(int index)
      Get the character at the nominated index.
      CharSequence getCharSeq​(int start, int end)
      Get a substring of the text as a CharSequence.
      int getHexInt​(int from, int to)
      Get an unsigned int from the text, treating the digits as hexadecimal.
      long getHexLong​(int from, int to)
      Get an unsigned long from the text, treating the digits as hexadecimal.
      int getIndex()
      Get the current index (the offset within the text).
      int getInt​(int from, int to)
      Get a positive int from the text.
      int getInt​(int from, int to, boolean negative)
      Get a signed int from the text.
      int getLength()
      Get the length of the entire text.
      long getLong​(int from, int to)
      Get a positive long from the text.
      long getLong​(int from, int to, boolean negative)
      Get a signed long from the text.
      String getResult()
      Get the result of the last match operation as a String.
      char getResultChar()
      Get the result of the last match operation (or the first character of a longer match) as a single character.
      CharSequence getResultCharSeq()
      Get the result of the last match operation as a CharSequence.
      int getResultHexInt()
      Get the result of the last match operation as an unsigned int, treating the digits as hexadecimal.
      long getResultHexLong()
      Get the result of the last match operation as an unsigned long, treating the digits as hexadecimal.
      int getResultInt()
      Get the result of the last match operation as an int.
      int getResultInt​(boolean negative)
      Get the result of the last match operation as an int.
      int getResultLength()
      Get the length of the result of the last match operation.
      long getResultLong()
      Get the result of the last match operation as a long.
      long getResultLong​(boolean negative)
      Get the result of the last match operation as a long.
      int getStart()
      Get the start index (the index of the start of the last matched sequence).
      String getString​(int start, int end)
      Get a substring of the text.
      boolean isAtEnd()
      Test whether the TextMatcher object is exhausted (the index has reached the end of the text).
      static boolean isDigit​(char ch)
      Test whether the given character is a digit.
      static boolean isHexDigit​(char ch)
      Test whether the given character is a hexadecimal digit.
      boolean match​(char ch)
      Match the current character in the text against a given character.
      boolean match​(CharSequence target)
      Match the characters at the index against a given CharSequence (String, StringBuilder etc.).
      boolean match​(CharPredicate comparison)
      Match the current character in the text using the specified comparison function.
      boolean matchAny​(String any)
      Match the current character in the text against any of the characters in a given String.
      boolean matchContinue​(int maxChars, int minChars, CharPredicate comparison)
      Match the characters at the index as a continuation using the specified comparison function, with a given minimum number of characters and an optional maximum, but do not set the start index on success, and on fail, set the index back to the start index (as if the original match had failed).
      boolean matchContinue​(int maxChars, CharPredicate comparison)
      Match the characters at the index as a continuation using the specified comparison function, with no minimum number of characters and an optional maximum, but do not set the start index on success, and on fail, set the index back to the start index (as if the original match had failed).
      boolean matchContinue​(CharPredicate comparison)
      Match the characters at the index as a continuation using the specified comparison function, with no minimum or maximum number of characters, but do not set the start index on success, and on fail, set the index back to the start index (as if the original match had failed).
      boolean matchDec()
      Match the characters at the index as decimal digits, with a minimum of 1 digit and no maximum.
      boolean matchDec​(int maxDigits)
      Match the characters at the index as decimal digits, with a minimum of 1 digit and an optional maximum.
      boolean matchDec​(int maxDigits, int minDigits)
      Match the characters at the index as decimal digits, with a given minimum number of digits and an optional maximum.
      boolean matchHex()
      Match the characters at the index as hexadecimal digits, with a minimum of 1 digit and no maximum.
      boolean matchHex​(int maxDigits)
      Match the characters at the index as hexadecimal digits, with a minimum of 1 digit and an optional maximum.
      boolean matchHex​(int maxDigits, int minDigits)
      Match the characters at the index as hexadecimal digits, with a given minimum number of digits and an optional maximum.
      boolean matchSeq​(int maxChars, int minChars, CharPredicate comparison)
      Match the characters at the index using the specified comparison function, with a given minimum number of characters and an optional maximum.
      boolean matchSeq​(int maxChars, CharPredicate comparison)
      Match the characters at the index using the specified comparison function, with a minimum of 1 character and an optional maximum.
      boolean matchSeq​(CharPredicate comparison)
      Match the characters at the index using the specified comparison function, with a minimum of 1 character and no maximum.
      char nextChar()
      Get the character at the current index and increment the index.
      void revert()
      Undo the effect of the last match operation.
      void setIndex​(int index)
      Set the current index.
      void setStart​(int start)
      Set the start index.
      void skip​(CharPredicate comparison)
      Increment the index past any characters matching a given comparison function.
      void skipAny​(String any)
      Increment the index past any of the characters in a given string.
      void skipFixed​(int n)
      Increment the index by a fixed amount.
      void skipToEnd()
      Increment the index directly to the end of the text.

    • Constructor Detail

      • TextMatcher

        public TextMatcher​(String text)
        Construct a TextMatcher with the specified text.
        Parameters:
        text - the text
        Throws:
        NullPointerException - if the text is null

    • Method Detail

      • getChar

        public char getChar​(int index)
        Get the character at the nominated index.
        Parameters:
        index - the index
        Returns:
        the character at that index
        Throws:
        IndexOutOfBoundsException - if the index is invalid

      • getLength

        public int getLength()
        Get the length of the entire text.
        Returns:
        the text length

      • getStart

        public int getStart()
        Get the start index (the index of the start of the last matched sequence).
        Returns:
        the start index

      • setStart

        public void setStart​(int start)
        Set the start index. If the current index is less than the new start index, make them equal.
        Parameters:
        start - the new start index
        Throws:
        IndexOutOfBoundsException - if the new start index is less than 0 or greater than the text length

      • getIndex

        public int getIndex()
        Get the current index (the offset within the text).
        Returns:
        the index

      • setIndex

        public void setIndex​(int index)
        Set the current index. If the new current index is less than the start index, make them equal.
        Parameters:
        index - the new current index
        Throws:
        IndexOutOfBoundsException - if the new current index is less than 0 or greater than the text length

      • isAtEnd

        public boolean isAtEnd()
        Test whether the TextMatcher object is exhausted (the index has reached the end of the text).
        Returns:
        true if the index has reached the end of the text

      • revert

        public void revert()
        Undo the effect of the last match operation.

      • match

        public boolean match​(char ch)
        Match the current character in the text against a given character. Following a successful match the start index will point to the matched character and the index will be incremented past it.
        Parameters:
        ch - the character to match against
        Returns:
        true if the character in the text matches the given character

      • match

        public boolean match​(CharSequence target)
        Match the characters at the index against a given CharSequence (String, StringBuilder etc.). Following a successful match the start index will point to the first character of the matched sequence and the index will be incremented past it.
        Parameters:
        target - the target CharSequence
        Returns:
        true if the characters in the text at the index match the target

      • match

        public boolean match​(CharPredicate comparison)
        Match the current character in the text using the specified comparison function. Following a successful match the start index will point to the matched character and the index will be incremented past it.
        Parameters:
        comparison - the comparison function
        Returns:
        true if the character in the text matches using the comparison function

      • matchAny

        public boolean matchAny​(String any)
        Match the current character in the text against any of the characters in a given String. Following a successful match the start index will point to the matched character and the index will be incremented past it.
        Parameters:
        any - the characters to match against (as a String)
        Returns:
        true if the character in the text at the index matches any of the characters in the string

      • matchSeq

        public boolean matchSeq​(int maxChars,
                        int minChars,
                        CharPredicate comparison)
        Match the characters at the index using the specified comparison function, with a given minimum number of characters and an optional maximum. To match a fixed number of characters, the maximum and minimum should be set to the same value.
        Parameters:
        maxChars - the maximum number of characters to match (or 0 to indicate no limit)
        minChars - the minimum number of characters for a successful match
        comparison - the comparison function
        Returns:
        true if the characters in the text at the index satisfy the comparison function (subject to the specified minimum and maximum number of characters)

      • matchSeq

        public boolean matchSeq​(int maxChars,
                        CharPredicate comparison)
        Match the characters at the index using the specified comparison function, with a minimum of 1 character and an optional maximum.
        Parameters:
        maxChars - the maximum number of characters to match (or 0 to indicate no limit)
        comparison - the comparison function
        Returns:
        true if one or more characters in the text at the index satisfy the comparison function (subject to the specified maximum number of characters)

      • matchSeq

        public boolean matchSeq​(CharPredicate comparison)
        Match the characters at the index using the specified comparison function, with a minimum of 1 character and no maximum.
        Parameters:
        comparison - the comparison function
        Returns:
        true if one or more characters in the text at the index satisfy the comparison function

      • matchDec

        public boolean matchDec​(int maxDigits,
                        int minDigits)
        Match the characters at the index as decimal digits, with a given minimum number of digits and an optional maximum. To match a fixed number of digits, the maximum and minimum should be set to the same value.
        Parameters:
        maxDigits - the maximum number of digits to match (or 0 to indicate no limit)
        minDigits - the minimum number of digits for a successful match
        Returns:
        true if the characters in the text at the index are decimal digits (subject to the specified minimum and maximum number of digits)

      • matchDec

        public boolean matchDec​(int maxDigits)
        Match the characters at the index as decimal digits, with a minimum of 1 digit and an optional maximum.
        Parameters:
        maxDigits - the maximum number of digits to match (or 0 to indicate no limit)
        Returns:
        true if one or more characters in the text at the index are decimal digits (subject to the specified maximum number of digits)

      • matchDec

        public boolean matchDec()
        Match the characters at the index as decimal digits, with a minimum of 1 digit and no maximum.
        Returns:
        true if one or more characters in the text at the index are decimal digits

      • matchHex

        public boolean matchHex​(int maxDigits,
                        int minDigits)
        Match the characters at the index as hexadecimal digits, with a given minimum number of digits and an optional maximum. To match a fixed number of digits, the maximum and minimum should be set to the same value.
        Parameters:
        maxDigits - the maximum number of digits to match (or 0 to indicate no limit)
        minDigits - the minimum number of digits for a successful match
        Returns:
        true if the characters in the text at the index are hexadecimal digits (subject to the specified minimum and maximum number of digits)

      • matchHex

        public boolean matchHex​(int maxDigits)
        Match the characters at the index as hexadecimal digits, with a minimum of 1 digit and an optional maximum.
        Parameters:
        maxDigits - the maximum number of digits to match (or 0 to indicate no limit)
        Returns:
        true if one or more characters in the text at the index are hexadecimal digits (subject to the specified maximum number of digits)

      • matchHex

        public boolean matchHex()
        Match the characters at the index as hexadecimal digits, with a minimum of 1 digit and no maximum.
        Returns:
        true if one or more characters in the text at the index are hexadecimal digits

      • matchContinue

        public boolean matchContinue​(int maxChars,
                             int minChars,
                             CharPredicate comparison)
        Match the characters at the index as a continuation using the specified comparison function, with a given minimum number of characters and an optional maximum, but do not set the start index on success, and on fail, set the index back to the start index (as if the original match had failed). To match a fixed number of characters, the maximum and minimum should be set to the same value.
        Parameters:
        maxChars - the maximum number of characters to match (or 0 to indicate no limit)
        minChars - the minimum number of characters for a successful match
        comparison - the comparison function
        Returns:
        true if the characters in the text at the index satisfy the comparison function (subject to the specified minimum and maximum number of characters)

      • matchContinue

        public boolean matchContinue​(int maxChars,
                             CharPredicate comparison)
        Match the characters at the index as a continuation using the specified comparison function, with no minimum number of characters and an optional maximum, but do not set the start index on success, and on fail, set the index back to the start index (as if the original match had failed).
        Parameters:
        maxChars - the maximum number of characters to match (or 0 to indicate no limit)
        comparison - the comparison function
        Returns:
        true (with a minimum of zero the function can not fail; the only effect is to set the index past the matching characters)

      • matchContinue

        public boolean matchContinue​(CharPredicate comparison)
        Match the characters at the index as a continuation using the specified comparison function, with no minimum or maximum number of characters, but do not set the start index on success, and on fail, set the index back to the start index (as if the original match had failed).
        Parameters:
        comparison - the comparison function
        Returns:
        true (with a minimum of zero the function can not fail; the only effect is to set the index past any matching characters)

      • skipAny

        public void skipAny​(String any)
        Increment the index past any of the characters in a given string.
        Parameters:
        any - the characters to be skipped, as a String

      • skip

        public void skip​(CharPredicate comparison)
        Increment the index past any characters matching a given comparison function.
        Parameters:
        comparison - the comparison function

      • skipToEnd

        public void skipToEnd()
        Increment the index directly to the end of the text.

      • skipFixed

        public void skipFixed​(int n)
        Increment the index by a fixed amount.
        Parameters:
        n - the number of characters to skip (must be positive)
        Throws:
        IllegalArgumentException - if the increment is negative
        StringIndexOutOfBoundsException - if the incremented index is beyond end of string

      • nextChar

        public char nextChar()
        Get the character at the current index and increment the index.
        Returns:
        the current character
        Throws:
        StringIndexOutOfBoundsException - if the index is at or beyond end of string

      • getString

        public String getString​(int start,
                        int end)
        Get a substring of the text.
        Parameters:
        start - the start offset
        end - the end offset (exclusive)
        Returns:
        the substring
        Throws:
        StringIndexOutOfBoundsException - if the start offset is lees than zero, the end offset is less than the start offset, or the end offset is greater than the length

      • getCharSeq

        public CharSequence getCharSeq​(int start,
                               int end)
        Get a substring of the text as a CharSequence. This will be slightly more efficient than getting a String, for those cases where a CharSequence is just as useful.
        Parameters:
        start - the start offset
        end - the end offset (exclusive)
        Returns:
        the CharSequence
        Throws:
        IndexOutOfBoundsException - if the start offset is lees than zero, the end offset is less than the start offset, or the end offset is greater than the length

      • getResultChar

        public char getResultChar()
        Get the result of the last match operation (or the first character of a longer match) as a single character.
        Returns:
        the first character of the result of the last match
        Throws:
        IndexOutOfBoundsException - if the start index at or beyond the end of the text

      • getResult

        public String getResult()
        Get the result of the last match operation as a String.
        Returns:
        the result of the last match

      • getResultCharSeq

        public CharSequence getResultCharSeq()
        Get the result of the last match operation as a CharSequence. This will be slightly more efficient than getting a String, for those cases where a CharSequence is just as useful.
        Returns:
        the result of the last match

      • getResultLength

        public int getResultLength()
        Get the length of the result of the last match operation.
        Returns:
        the length of the result of the last match

      • getResultInt

        public int getResultInt()
        Get the result of the last match operation as an int.
        Returns:
        the result of the last match as an int (always positive)
        Throws:
        NumberFormatException - if the start and end indices do not describe a valid int

      • getResultInt

        public int getResultInt​(boolean negative)
        Get the result of the last match operation as an int.
        Parameters:
        negative - true to indicate that the value must be negated
        Returns:
        the result of the last match as an int (always positive)
        Throws:
        NumberFormatException - if the start and end indices do not describe a valid int

      • getInt

        public int getInt​(int from,
                  int to)
        Get a positive int from the text.
        Parameters:
        from - the start offset
        to - the end offset (exclusive)
        Returns:
        the int (always positive)
        Throws:
        NumberFormatException - if the start and end indices do not describe a valid int
        IndexOutOfBoundsException - if the start and end indices are not contained within the text

      • getInt

        public int getInt​(int from,
                  int to,
                  boolean negative)
        Get a signed int from the text.
        Parameters:
        from - the start offset
        to - the end offset (exclusive)
        negative - true to indicate that the value must be negated
        Returns:
        the int
        Throws:
        NumberFormatException - if the start and end indices do not describe a valid int
        IndexOutOfBoundsException - if the start and end indices are not contained within the text

      • getResultLong

        public long getResultLong()
        Get the result of the last match operation as a long.
        Returns:
        the result of the last match as a long (always positive)
        Throws:
        NumberFormatException - if the start and end indices do not describe a valid long

      • getResultLong

        public long getResultLong​(boolean negative)
        Get the result of the last match operation as a long.
        Parameters:
        negative - true to indicate that the value must be negated
        Returns:
        the result of the last match as a long (always positive)
        Throws:
        NumberFormatException - if the start and end indices do not describe a valid long

      • getLong

        public long getLong​(int from,
                    int to)
        Get a positive long from the text.
        Parameters:
        from - the start offset
        to - the end offset (exclusive)
        Returns:
        the long (always positive)
        Throws:
        NumberFormatException - if the start and end indices do not describe a valid long
        IndexOutOfBoundsException - if the start and end indices are not contained within the text

      • getLong

        public long getLong​(int from,
                    int to,
                    boolean negative)
        Get a signed long from the text.
        Parameters:
        from - the start offset
        to - the end offset (exclusive)
        negative - true to indicate that the value must be negated
        Returns:
        the long
        Throws:
        NumberFormatException - if the start and end indices do not describe a valid long
        IndexOutOfBoundsException - if the start and end indices are not contained within the text

      • getResultHexInt

        public int getResultHexInt()
        Get the result of the last match operation as an unsigned int, treating the digits as hexadecimal.
        Returns:
        the result of the last match as an int
        Throws:
        NumberFormatException - if the start and end indices do not describe a valid int

      • getHexInt

        public int getHexInt​(int from,
                     int to)
        Get an unsigned int from the text, treating the digits as hexadecimal.
        Parameters:
        from - the start offset
        to - the end offset (exclusive)
        Returns:
        the hexadecimal int
        Throws:
        NumberFormatException - if the start and end indices do not describe a valid int
        IndexOutOfBoundsException - if the start and end indices are not contained within the text

      • getResultHexLong

        public long getResultHexLong()
        Get the result of the last match operation as an unsigned long, treating the digits as hexadecimal.
        Returns:
        the result of the last match as a long
        Throws:
        NumberFormatException - if the start and end indices do not describe a valid long

      • getHexLong

        public long getHexLong​(int from,
                       int to)
        Get an unsigned long from the text, treating the digits as hexadecimal.
        Parameters:
        from - the start offset
        to - the end offset (exclusive)
        Returns:
        the hexadecimal long
        Throws:
        NumberFormatException - if the start and end indices do not describe a valid long
        IndexOutOfBoundsException - if the start and end indices are not contained within the text

      • isDigit

        public static boolean isDigit​(char ch)
        Test whether the given character is a digit.
        Parameters:
        ch - the character
        Returns:
        true if the character is a digit

      • isHexDigit

        public static boolean isHexDigit​(char ch)
        Test whether the given character is a hexadecimal digit.
        Parameters:
        ch - the character
        Returns:
        true if the character is a hexadecimal digit

      • convertDecDigit

        public static int convertDecDigit​(char ch)
        Convert a decimal digit to the integer value of the digit.
        Parameters:
        ch - the decimal digit
        Returns:
        the integer value (0 - 9)
        Throws:
        NumberFormatException - if the digit is not valid

      • convertHexDigit

        public static int convertHexDigit​(char ch)
        Convert a hexadecimal digit to the integer value of the digit.
        Parameters:
        ch - the hexadecimal digit
        Returns:
        the integer value (0 - 15)
        Throws:
        NumberFormatException - if the digit is not valid