Module io.github.mmm.scanner
Package io.github.mmm.scanner

Interface CharStreamScanner

All Superinterfaces:
AutoCloseable, TextFormatProcessor, TextPosition
All Known Implementing Classes:
AbstractCharStreamScanner, CharReaderScanner, CharSequenceScanner
public interface CharStreamScanner extends TextFormatProcessor, AutoCloseable
This is the interface for a scanner that can be used to parse a stream or sequence of characters.

  • Field Details

    • EOS

      static final char EOS
      The NULL character '\0' used to indicate the end of stream (EOS).
      ATTENTION: Do not confuse and mix '\0' with '0'.
      See Also:

  • Method Details

    • hasNext

      boolean hasNext()
      This method determines if there is at least one more character available.
      Returns:
      true if there is at least one character available, false if the end of data has been reached.

    • next

      char next()
      This method reads the current character from the stream and increments the index stepping to the next character. You should check if a character is available before calling this method. Otherwise if your stream may contain the NUL character ('\0') you can not distinguish if the end of the stream was reached or you actually read the NUL character.
      Returns:
      the next() character or EOS if none is available.

    • peek

      char peek()
      This method reads the current character without consuming characters and will therefore not change the state of this scanner.
      Returns:
      the current character or EOS if none is available.

    • peek

      char peek(int lookaheadOffset)
      Like peek() but with further lookahead.
      Attention:
      This method requires lookahead. For implementations that are backed by an underlying stream (or reader) the given lookaheadOffset shall not exceed the available lookahead size (buffer capacity given at construction time). Otherwise the method may fail.
      Parameters:
      lookaheadOffset - the lookahead offset. If 0 this method will behave like peek(). In case of 1 it will return the character after the next one and so forth.
      Returns:
      the peeked character at the given lookaheadOffset or EOS if no such character exists.

    • peekString

      String peekString(int count)
      This method peeks the number of next characters given by count and returns them as String. If there are less characters available the returned String will be shorter than count and only contain the available characters. Unlike read(int) this method does not consume the characters and will therefore not change the state of this scanner.
      Attention:
      This method requires lookahead. For implementations that are backed by an underlying stream (or reader) the given count shall not exceed the available lookahead size (buffer capacity given at construction time). Otherwise the method may fail.
      Parameters:
      count - is the number of characters to peek. You may use Integer.MAX_VALUE to peek until the end of text (EOT) if the data-size is suitable.
      Returns:
      a string with the given number of characters or all available characters if less than count. Will be the empty string if no character is available at all.

    • peekWhile

      String peekWhile(CharFilter filter, int maxLen)
      Parameters:
      filter - the CharFilter accepting only the characters to peek.
      maxLen - the maximum number of characters to peek (to get as lookahead without modifying this stream).
      Returns:
      a String with the peeked characters of the given maxLen or less if a character was hit that is not accepted by the given filter or the end-of-text has been reached before. The state of this stream remains unchanged.
      See Also:

    • peekUntil

      default String peekUntil(CharFilter stopFilter, int maxLen)
      Parameters:
      stopFilter - the CharFilter that decides which characters to accept as stop characters.
      maxLen - the maximum number of characters to peek (get as lookahead without modifying this stream).
      Returns:
      a String with the peeked characters of the given maxLen or less if a stop character was hit or the end-of-text has been reached before. The state of this stream remains unchanged.
      See Also:

    • read

      String read(int count)
      This method reads the number of next characters given by count and returns them as string. If there are less characters available the returned string will be shorter than count and only contain the available characters.
      Parameters:
      count - is the number of characters to read. You may use Integer.MAX_VALUE to read until the end of data if the data-size is suitable.
      Returns:
      a string with the given number of characters or all available characters if less than count. Will be the empty string if no character is available at all.

    • read

      void read(int count, StringBuilder builder)
      This method reads the number of next characters given by count and appends them to the given StringBuilder. If there are less characters available then only the remaining characters will be appended resulting in less characters than count.
      Parameters:
      count - is the number of characters to read. You may use Integer.MAX_VALUE to read until the end of data if the data-size is suitable.
      builder - the StringBuilder where to append the characters to read.

    • getPosition

      int getPosition()
      Returns:
      the position in the sequence to scan or in other words the number of characters that have been read. Will initially be 0. Please note that this API is designed for scanning textual content (for parsers). Therefore we consider 2.1 terabyte as a suitable limit.

    • readUntil

      String readUntil(char stop, boolean acceptEnd)
      This method reads all next characters until the given stop character or the end is reached.
      After the call of this method, the current index will point to the next character after the (first) stop character or to the end if NO such character exists.
      Parameters:
      stop - is the character to read until.
      acceptEnd - if true the end of data will be treated as stop, too.
      Returns:
      the string with all read characters excluding the stop character or null if there was no stop character and acceptEnd is false.

    • readUntil

      String readUntil(char stop, boolean acceptEnd, char escape)
      This method reads all next characters until the given (un-escaped) stop character or the end is reached.
      In advance to readUntil(char, boolean), this method allows that the stop character may be used in the input-string by adding the given escape character. After the call of this method, the current index will point to the next character after the (first) stop character or to the end if NO such character exists.
      This method is especially useful when quoted strings should be parsed. E.g.: 
       CharStreamScanner scanner = getScanner();
 doSomething();
 char c = scanner.next();
 if ((c == '"') || (c == '\'')) {
   char escape = c; // may also be something like '\\'
   String quote = scanner.readUntil(c, false, escape)
 } else {
   doOtherThings();
 }
      Parameters:
      stop - is the character to read until.
      acceptEnd - if true the end of data will be treated as stop, too.
      escape - is the character used to escape the stop character. To add an occurrence of the escape character it has to be duplicated (occur twice). The escape character may also be equal to the stop character. If other regular characters are escaped the escape character is simply ignored.
      Returns:
      the string with all read characters excluding the stop character or null if there was no stop character and acceptEnd is false.

    • readUntil

      String readUntil(char stop, boolean acceptEnd, CharScannerSyntax syntax)
      This method reads all next characters until the given stop character or the end of the string to parse is reached. In advance to readUntil(char, boolean), this method will scan the input using the given syntax which e.g. allows to escape the stop character.
      After the call of this method, the current index will point to the next character after the (first) stop character or to the end of the string if NO such character exists.
      Parameters:
      stop - is the character to read until.
      acceptEnd - if true the end of data will be treated as stop, too.
      syntax - contains the characters specific for the syntax to read.
      Returns:
      the string with all read characters excluding the stop character or null if there was no stop character.
      See Also:

    • readUntil

      String readUntil(CharFilter filter, boolean acceptEnd)
      This method reads all next characters until the first character accepted by the given filter or the end is reached.
      After the call of this method, the current index will point to the first accepted stop character or to the end if NO such character exists.
      Parameters:
      filter - is used to decide where to stop.
      acceptEnd - if true if end of data should be treated like the stop character and the rest of the text will be returned, false otherwise (to return null if the end of data was reached and the scanner has been consumed).
      Returns:
      the string with all read characters not accepted by the given CharFilter or null if there was no accepted character and acceptEnd is false.

    • readUntil

      default String readUntil(CharFilter filter, boolean acceptEnd, String stop)
      This method reads all next characters until the first character accepted by the given filter, the given stop String or the end is reached.
      After the call of this method, the current index will point to the first accepted stop character, or to the first character of the given stop String or to the end if NO such character exists.
      Parameters:
      filter - is used to decide where to stop.
      acceptEnd - if true if the end of data should be treated like the stop character and the rest of the text will be returned, false otherwise (to return null if end of data was reached and the scanner has been consumed).
      stop - the String where to stop consuming data. Should be at least two characters long (otherwise accept by CharFilter instead).
      Returns:
      the string with all read characters not accepted by the given CharFilter or until the given stop String was detected. If end of data was reached without a stop signal the entire rest of the data is returned or null if acceptEnd is false.

    • readUntil

      default String readUntil(CharFilter filter, boolean acceptEnd, String stop, boolean ignoreCase)
      This method reads all next characters until the first character accepted by the given filter, the given stop String or the end is reached.
      After the call of this method, the current index will point to the first accepted stop character, or to the first character of the given stop String or to the end if NO such character exists.
      Parameters:
      filter - is used to decide where to stop.
      acceptEnd - if true if the end of data should be treated like the stop character and the rest of the text will be returned, false otherwise (to return null if the end of data was reached and the scanner has been consumed).
      stop - the String where to stop consuming data. Should be at least two characters long (otherwise accept by CharFilter instead).
      ignoreCase - - if true the case of the characters is ignored when compared with characters from stop String.
      Returns:
      the string with all read characters not accepted by the given CharFilter or until the given stop String was detected. If the end of data was reached without a stop signal the entire rest of the data is returned or null if acceptEnd is false.

    • readUntil

      String readUntil(CharFilter filter, boolean acceptEnd, String stop, boolean ignoreCase, boolean trim)
      This method reads all next characters until the first character accepted by the given filter, the given stop String or the end is reached.
      After the call of this method, the current index will point to the first accepted stop character, or to the first character of the given stop String or to the end if NO such character exists.
      Parameters:
      filter - is used to decide where to stop.
      acceptEnd - if true if the end of data should be treated like the stop character and the rest of the text will be returned, false otherwise (to return null if the end of data was reached and the scanner has been consumed).
      stop - the String where to stop consuming data. Should be at least two characters long (otherwise accept by CharFilter instead).
      ignoreCase - - if true the case of the characters is ignored when compared with characters from stop String.
      trim - - true if the result should be trimmed, false otherwise.
      Returns:
      the string with all read characters not accepted by the given CharFilter or until the given stop String was detected. If the end of data was reached without hitting stop the entire rest of the data is returned or null if acceptEnd is false. Thre result will be trimmed if trim is true.

    • readUntil

      String readUntil(CharFilter filter, boolean acceptEnd, CharScannerSyntax syntax)
      This method reads all next characters until the given CharFilter accepts the current character as stop character or the end of data is reached. In advance to readUntil(char, boolean), this method will scan the input using the given syntax which e.g. allows to escape the stop character.
      After the call of this method, the current index will point to the first accepted stop character or to the end of the string if NO such character exists.
      Parameters:
      filter - is used to decide where to stop.
      acceptEnd - if true the end of data will be treated as stop, too.
      syntax - contains the characters specific for the syntax to read.
      Returns:
      the string with all read characters excluding the stop character or null if there was no stop character.
      See Also:

    • readUntil

      default String readUntil(CharFilter stopFilter, int min, int max)
      Parameters:
      stopFilter - the CharFilter that decides which characters to accept as stop characters.
      min - the minimum number of characters expected.
      max - the (maximum) length of the characters to consume.
      Returns:
      the String with all consumed characters excluding the stop character. If no stop character was found until maxLength characters have been consumed, this method behaves like read(maxLength).
      Throws:
      IllegalStateException - if less than the minimum number of characters have been rejected.
      See Also:

    • readWhile

      default String readWhile(CharFilter filter)
      This method reads all next characters that are accepted by the given filter.
      After the call of this method, the current index will point to the next character that was NOT accepted by the given filter or to the end if NO such character exists.
      Parameters:
      filter - used to decide which characters should be accepted.
      Returns:
      a string with all characters accepted by the given filter. Will be the empty string if no character was accepted.
      See Also:

    • readWhile

      String readWhile(CharFilter filter, int min, int max)
      This method reads all next characters that are accepted by the given filter.
      After the call of this method, the current index will point to the next character that was NOT accepted by the given filter. If the next max characters or the characters left until the end of this scanner are accepted, only that amount of characters are skipped.
      Parameters:
      filter - used to decide which characters should be accepted.
      min - the minimum number of characters expected.
      max - the maximum number of characters that should be read.
      Returns:
      a string with all characters accepted by the given filter limited to the length of max and the end of this scanner. Will be the empty string if no character was accepted.
      Throws:
      IllegalStateException - if less than the minimum number of characters have been accepted.
      See Also:

    • readLine

      default String readLine()
      Returns:
      a String with the data until the end of the current line or the end of the data. Will be null if the end has already been reached and hasNext() returns false.

    • readLine

      String readLine(boolean trim)
      Parameters:
      trim - - true if the result should be trimmed, false otherwise.
      Returns:
      a String with the data until the end of the current line (trimmed if trim is true) or the end of the data. Will be null if the end has already been reached and hasNext() returns false.

    • readBoolean

      default Boolean readBoolean()
      Reads a Boolean value from this scanner if available.
      Returns:
      the consumed Boolean value or null if no such value was available and the position remains unchanged.

    • readBoolean

      default Boolean readBoolean(boolean ignoreCase)
      Reads a Boolean value from this scanner if available.
      Parameters:
      ignoreCase - - if true the case of the characters is ignored when compared, false otherwise (only lower case is accepted).
      Returns:
      the consumed Boolean value or null if no such value was available and the position remains unchanged.

    • readBoolean

      default Boolean readBoolean(boolean ignoreCase, boolean acceptYesNo)
      Reads a Boolean value from this scanner if available.
      Parameters:
      ignoreCase - - if true the case of the characters is ignored when compared, false otherwise (only lower case is accepted).
      acceptYesNo - - if true also "yes" is accepted for true and "no" for false, false otherwise.
      Returns:
      the consumed Boolean value or null if no such value was available and the position remains unchanged.

    • readNumber

      void readNumber(CharScannerNumberParser numberParser)
      Generic way to read and parse any kind of Number.
      Parameters:
      numberParser - the CharScannerNumberParser. Can decide if sign, digits, radix, exponent, or even specials are

    • readDouble

      default Double readDouble() throws NumberFormatException
      This method reads the double value (decimal number) starting at the current position by reading as many matching characters as available and returns its parsed value.
      Returns:
      the parsed double number or null if the current current position does not point to a number.
      Throws:
      NumberFormatException - if the number at the current position could not be parsed.

    • readDouble

      Double readDouble(CharScannerRadixHandler radixMode) throws NumberFormatException
      This method reads the double value (decimal number) starting at the current position by reading as many matching characters as available and returns its parsed value.
      Parameters:
      radixMode - the CharScannerRadixHandler - e.g. CharScannerRadixMode.ALL.
      Returns:
      the parsed double number or null if the current current position does not point to a number.
      Throws:
      NumberFormatException - if the number at the current position could not be parsed.

    • readFloat

      default Float readFloat() throws NumberFormatException
      This method reads a Float value from the current position consuming as many matching characters as available.
      Returns:
      the parsed Float value or null if the current current position does not point to a Float number.
      Throws:
      NumberFormatException - if the number at the current position could not be parsed.

    • readFloat

      Float readFloat(CharScannerRadixHandler radixMode) throws NumberFormatException
      This method reads a Float value from the current position consuming as many matching characters as available.
      Parameters:
      radixMode - the CharScannerRadixHandler - e.g. CharScannerRadixMode.ALL.
      Returns:
      the parsed Float value or null if the current current position does not point to a Float number.
      Throws:
      NumberFormatException - if the number at the current position could not be parsed.

    • readLong

      default Long readLong() throws NumberFormatException
      Returns:
      the consumed Long value or null if no number was present and the position remains unchanged.
      Throws:
      NumberFormatException - if the current current position points to a number that is not a Long value.

    • readLong

      Long readLong(CharScannerRadixHandler radixMode)
      Parameters:
      radixMode - the CharScannerRadixHandler - e.g. CharScannerRadixMode.ALL.
      Returns:
      the consumed Long value or null if no such value was present and the position remains unchanged.
      Throws:
      NumberFormatException - if the current current position points to a number that is not a Long value.

    • readInteger

      default Integer readInteger() throws NumberFormatException
      Returns:
      the consumed Integer value or null if no such value was present and the position remains unchanged.
      Throws:
      NumberFormatException - if the current current position does not point to a Integer value.

    • readInteger

      Integer readInteger(CharScannerRadixHandler radixMode) throws NumberFormatException
      Parameters:
      radixMode - the CharScannerRadixHandler - e.g. CharScannerRadixMode.ALL.
      Returns:
      the consumed Integer value or null if no such value was present and the position remains unchanged.
      Throws:
      NumberFormatException - if the current current position does not point to a Long value.

    • readJavaNumberLiteral

      Number readJavaNumberLiteral()
      Reads a Java Number literal (e.g. "1L" or "1.3F").
      Returns:
      the consumed Number or null if no number literal was found and the position remains unchainged.
      Throws:
      NumberFormatException - if a number literal was found that has an illegal format.

    • readDigit

      default int readDigit()
      This method reads the next character if it is a digit. Else the state remains unchanged.
      Returns:
      the numeric value of the next Latin digit (e.g. 0 if '0') or -1 if the next character is no Latin digit.

    • readDigit

      int readDigit(int radix)
      This method reads the next character if it is a digit within the given radix. Else the state remains unchanged.
      Parameters:
      radix - the radix that defines the range of the digits. See Integer.parseInt(String, int). E.g. 10 to read any Latin digit (see readDigit()), 8 to read octal digit, 16 to read hex decimal digits.
      Returns:
      the numeric value of the next digit within the given radix or -1 if the next character is no such digit.

    • readUnsignedLong

      long readUnsignedLong(int maxDigits) throws NumberFormatException
      This method reads the long starting at the current position by reading as many Latin digits as available but at maximum the given maxDigits and returns its parsed value.
      ATTENTION:
      This method does NOT treat signs (+ or -) to do so, scan them yourself before and negate the result as needed.
      Parameters:
      maxDigits - is the maximum number of digits that will be read. The value has to be positive (greater than zero). Should not be greater than 19 as this will exceed the range of long.
      Returns:
      the parsed number.
      Throws:
      NumberFormatException - if the number at the current position could not be parsed.

    • readJavaStringLiteral

      default String readJavaStringLiteral()
      Reads and parses a Java String literal value according to JLS 3.10.6.
      As a complex example for the input "Hi \"\176\477\579•∑\"\n" this scanner would return the String output Hi "~'7/9•∑" followed by a newline character.
      Returns:
      the parsed Java String literal value or null if not pointing to a String literal.

    • readJavaStringLiteral

      String readJavaStringLiteral(TextFormatMessageType severity)
      Reads and parses a Java String literal value according to JLS 3.10.6.
      As a complex example for the input "Hi \"\176\477\579•∑\"\n" this scanner would return the String output Hi "~'7/9•∑" followed by a newline character.
      Parameters:
      severity - the TextFormatMessageType to use to report invalid escape sequences or missing terminating quotation.
      Returns:
      the parsed Java String literal value or null if not pointing to a String literal.

    • readJavaCharLiteral

      default Character readJavaCharLiteral()
      Reads and parses a Java Character literal value according to JLS 3.10.6.
      Examples are given in the following table:
      literal result comment
      'a' a regular char
      '\'' ' escaped char
      '\176' ~ escaped octal representation
      '•' • escaped unicode representation
      Returns:
      the parsed Java String literal value or null if not pointing to a String literal.

    • readJavaCharLiteral

      Character readJavaCharLiteral(TextFormatMessageType severity)
      Reads and parses a Java Character literal value according to JLS 3.10.6.
      Examples are given in the following table:
      literal result comment
      'a' a regular char
      '\'' ' escaped char
      '\176' ~ escaped octal representation
      '•' • escaped unicode representation
      Parameters:
      severity - the TextFormatMessageType to use to report invalid escape sequences or missing terminating quotation.
      Returns:
      the parsed Java Character literal value or null if not pointing to a Character literal.

    • expect

      default boolean expect(String expected)
      This method determines if the given expected String is completely present at the current position. It will only consume characters and change the state if the expected String was found (entirely).
      Attention:
      This method requires lookahead. For implementations that are backed by an underlying stream (or reader) the length of the expected String shall not exceed the available lookahead size (buffer capacity given at construction time). Otherwise the method may fail.
      Parameters:
      expected - is the expected string.
      Returns:
      true if the expected string was successfully consumed from this scanner, false otherwise.
      See Also:

    • expect

      default boolean expect(String expected, boolean ignoreCase)
      This method determines if the given expected String is completely present at the current position. It will only consume characters and change the state if the expected String was found (entirely).
      Attention:
      This method requires lookahead. For implementations that are backed by an underlying stream (or reader) the length of the expected String shall not exceed the available lookahead size (buffer capacity given at construction time). Otherwise the method may fail.
      Parameters:
      expected - the expected String to search for.
      ignoreCase - - if true the case of the characters is ignored when compared, false otherwise.
      Returns:
      true if the expected string was successfully found and consume from this scanner, false otherwise.
      See Also:

    • expect

      default boolean expect(String expected, boolean ignoreCase, boolean lookahead)
      This method determines if the given expected String is completely present at the current position. It will only consume characters and change the state if lookahead is false and the expected String was found (entirely).
      Attention:
      This method requires lookahead. For implementations that are backed by an underlying stream (or reader) the length of the expected String shall not exceed the available lookahead size (buffer capacity given at construction time). Otherwise the method may fail.
      Parameters:
      expected - the expected String to search for.
      ignoreCase - - if true the case of the characters is ignored when compared, false otherwise.
      lookahead - - if true the state of the scanner remains unchanged even if the expected String has been found, false otherwise (expected String is consumed on match).
      Returns:
      true if the expected string was successfully found, false otherwise.

    • expect

      boolean expect(String expected, boolean ignoreCase, boolean lookahead, int offset)
      This method determines if the given expected String is completely present at the current position. It will only consume characters and change the state if lookahead is false and the expected String was found (entirely).
      Attention:
      This method requires lookahead. For implementations that are backed by an underlying stream (or reader) the length of the expected String shall not exceed the available lookahead size (buffer capacity given at construction time). Otherwise the method may fail.
      Parameters:
      expected - the expected String to search for.
      ignoreCase - - if true the case of the characters is ignored when compared, false otherwise.
      lookahead - - if true the state of the scanner remains unchanged even if the expected String has been found, false otherwise (expected String is consumed on match).
      offset - the number of characters that have already been peeked and after which the given String is expected. Will typically be 0. If lookahead is false and the expected String was found these characters will be skipped together with the expected String.
      Returns:
      true if the expected string was successfully found, false otherwise.

    • expect

      default boolean expect(String expected, boolean ignoreCase, boolean lookahead, int offset, boolean warning)
      This method determines if the given expected String is completely present at the current position. It will only consume characters and change the state if lookahead is false and the expected String was found (entirely).
      Attention:
      This method requires lookahead. For implementations that are backed by an underlying stream (or reader) the length of the expected String shall not exceed the available lookahead size (buffer capacity given at construction time). Otherwise the method may fail.
      Parameters:
      expected - the expected String to search for.
      ignoreCase - - if true the case of the characters is ignored when compared, false otherwise.
      lookahead - - if true the state of the scanner remains unchanged even if the expected String has been found, false otherwise (expected String is consumed on match).
      offset - the number of characters that have already been peeked and after which the given String is expected. Will typically be 0. If lookahead is false and the expected String was found these characters will be skipped together with the expected String.
      warning - true to add a warning in case the expected String was not found, false otherwise.
      Returns:
      true if the expected string was successfully found, false otherwise.

    • expectOne

      default boolean expectOne(char expected)
      This method checks if the next character is equal to the given expected character.
      If the character matched with the expected character, the parser points to the next character. Otherwise its position will remain unchanged.
      Parameters:
      expected - is the expected character.
      Returns:
      true if the current character is the same as expected, false otherwise.

    • expectOne

      boolean expectOne(char expected, boolean warning)
      This method checks if the next character is equal to the given expected character.
      If the character matched with the expected character, the parser points to the next character. Otherwise its position will remain unchanged.
      Parameters:
      expected - the character to expect as next in this stream.
      warning - true to add a warning in case the expected character was not present, false otherwise.
      Returns:
      true if the expected character was found and consumer, false otherwise (and this stream remains unchanged).

    • expectOne

      default boolean expectOne(CharFilter expected)
      This method checks that the next character is accepted by the given CharFilter.
      If the current character was as expected, the parser points to the next character. Otherwise its position will remain unchanged.
      Parameters:
      expected - is the CharFilter accepting the expected chars.
      Returns:
      true if the current character is accepted, false otherwise.

    • expectUnsafe

      default boolean expectUnsafe(String expected)
      This method skips all next characters as long as they equal to the according character of the expected String.
      If a character differs this method stops and the parser points to the first character that differs from expected. Except for the latter circumstance, this method behaves similar to the following code: 
       read(expected.length).equals(expected)
      ATTENTION:
      In most cases you want to prefer expect(String) instead of using this method. Only in specific cases and for highly optimized performance it may make sense to use it. In such case be careful and consider to combine with getPosition() to be able to determine whether characters have been consumed if false was returned (e.g. otherwise when doing expectUnsafe("false") and else doing expectUnsafe("true") to parse a boolean literal your code could accept "falstrue" as "true").
      Parameters:
      expected - is the expected string.
      Returns:
      true if the expected string was successfully consumed from this scanner, false otherwise.
      See Also:

    • expectUnsafe

      boolean expectUnsafe(String expected, boolean ignoreCase)
      This method skips all next characters as long as they equal to the according character of the expected string.
      If a character differs this method stops and the parser points to the first character that differs from expected. Except for the latter circumstance, this method behaves similar to the following code: 
       read(expected.length).equals[IgnoreCase](expected)
      ATTENTION:
      In most cases you want to prefer expect(String, boolean) instead of using this method. See expectUnsafe(String) for details.
      Parameters:
      expected - is the expected string.
      ignoreCase - - if true the case of the characters is ignored when compared.
      Returns:
      true if the expected string was successfully consumed from this scanner, false otherwise.
      See Also:

    • requireOne

      default void requireOne(char expected) throws IllegalStateException
      This method verifies that the next character is equal to the given expected character.
      If the current character was as expected, the parser points to the next character. Otherwise an exception is thrown indicating the problem.
      Parameters:
      expected - is the expected character.
      Throws:
      IllegalStateException - if the required character was not found.

    • require

      void require(String expected, boolean ignoreCase)
      This method verifies that the expected string gets consumed from this scanner with respect to ignoreCase. Otherwise an exception is thrown indicating the problem.
      This method behaves functionally equivalent to the following code: 
       if (!scanner.expectUnsafe(expected, ignoreCase)) {
   throw new IllegalStateException(...);
 }
      Parameters:
      expected - is the expected string.
      ignoreCase - - if true the case of the characters is ignored during comparison.

    • requireOne

      default int requireOne(CharFilter filter)
      Parameters:
      filter - the CharFilter accepting the expected characters to skip.
      Returns:
      the actual number of characters that have been skipped.
      Throws:
      IllegalStateException - if less than 1 or more than 1000 accepted characters have been consumed.

    • requireOneOrMore

      default int requireOneOrMore(CharFilter filter)
      Parameters:
      filter - the CharFilter accepting the expected characters to skip.
      Returns:
      the actual number of characters that have been skipped.
      Throws:
      IllegalStateException - if less than 1 or more than 1000 accepted characters have been consumed.

    • require

      default int require(CharFilter filter, int min)
      Parameters:
      filter - the CharFilter accepting the expected characters to skip.
      min - the minimum required number of skipped characters.
      Returns:
      the actual number of characters that have been skipped.
      Throws:
      IllegalStateException - if less than min or more than 1000 accepted characters have been consumed.

    • require

      default int require(CharFilter filter, int min, int max)
      Parameters:
      filter - the CharFilter accepting the expected characters to skip.
      min - the minimum required number of skipped characters.
      max - the maximum number of skipped characters.
      Returns:
      the actual number of characters that have been skipped.
      Throws:
      IllegalStateException - if less than min or more than max accepted characters have been consumed.

    • skipUntil

      boolean skipUntil(char stop)
      This method skips all next characters until the given stop character or the end is reached. If the stop character was reached, this scanner will point to the next character after stop when this method returns.
      Parameters:
      stop - is the character to read until.
      Returns:
      true if the first occurrence of the given stop character has been passed, false if there is no such character.

    • skipUntil

      boolean skipUntil(char stop, char escape)
      This method reads all next characters until the given stop character or the end of the string to parse is reached. In advance to skipUntil(char), this method will read over the stop character if it is escaped with the given escape character.
      Parameters:
      stop - is the character to read until.
      escape - is the character used to escape the stop character (e.g. '\').
      Returns:
      true if the first occurrence of the given stop character has been passed, false if there is no such character.

    • skip

      int skip(int count)
      This method skips the number of next characters given by count.
      Parameters:
      count - is the number of characters to skip. You may use Integer.MAX_VALUE to read until the end of data if the data-size is suitable.
      Returns:
      a to total number of characters that have been skipped. Typically equal to count. Will be less in case the end of data was reached.

    • skipNewLine

      int skipNewLine()
      Returns:
      0 if the next characeter is not a newline and the stream remains unchanged, 1 if the next characeter was '\n' and has been skipped, or 2 if thenext characeters have been '\r' and '\n' and have been skipped.

    • skipOver

      default boolean skipOver(String substring)
      This method reads all next characters until the given substring has been detected.
      After the call of this method, the current index will point to the next character after the first occurrence of substring or to the end of data if the given substring was NOT found.
      Parameters:
      substring - is the substring to search and skip over starting at the current index.
      Returns:
      true if the given substring occurred and has been passed and false if the end of the string has been reached without any occurrence of the given substring.

    • skipOver

      default boolean skipOver(String substring, boolean ignoreCase)
      This method reads all next characters until the given substring has been detected.
      After the call of this method, the current index will point to the next character after the first occurrence of substring or to the end of data if the given substring was NOT found.
      Parameters:
      substring - is the substring to search and skip over starting at the current index.
      ignoreCase - - if true the case of the characters is ignored when compared with characters from substring.
      Returns:
      true if the given substring occurred and has been passed and false if the end of the string has been reached without any occurrence of the given substring.

    • skipOver

      boolean skipOver(String substring, boolean ignoreCase, CharFilter stopFilter)
      This method consumes all next characters until the given substring has been detected, a character was accepted by the given CharFilter or the end of data was reached.
      After the call of this method this scanner will point to the next character after the first occurrence of substring, to the stop character or to end of data.
      Parameters:
      substring - is the substring to search and skip over starting at the current index.
      ignoreCase - - if true the case of the characters is ignored when compared with characters from substring.
      stopFilter - is the filter used to detect stop characters. If such character was detected, the skip is stopped and the parser points to the character after the stop character. The substring should NOT contain a stop character.
      Returns:
      true if the given substring occurred and has been passed and false if a stop character has been detected or the end of the string has been reached without any occurrence of the given substring or stop character.

    • skipWhile

      int skipWhile(char c)
      This method reads all next characters that are identical to the character given by c.
      E.g. use readWhile(' ') to skip all blanks from the current index. After the call of this method, the current index will point to the next character that is different to the given character c or to the end if NO such character exists.
      Parameters:
      c - is the character to read over.
      Returns:
      the number of characters that have been skipped.

    • skipWhile

      default int skipWhile(CharFilter filter)
      This method reads all next characters that are accepted by the given filter.
      After the call of this method, the current index will point to the next character that was NOT accepted by the given filter or to the end if NO such character exists.
      Parameters:
      filter - is used to decide which characters should be accepted.
      Returns:
      the number of characters accepted by the given filter that have been skipped.
      See Also:

    • skipWhile

      int skipWhile(CharFilter filter, int max)
      This method reads all next characters that are accepted by the given filter.
      After the call of this method, the current index will point to the next character that was NOT accepted by the given filter. If the next max characters or the characters left until the end of this scanner are accepted, only that amount of characters are skipped.
      Parameters:
      filter - is used to decide which characters should be accepted.
      max - is the maximum number of characters that may be skipped.
      Returns:
      the number of skipped characters.
      See Also:

    • skipWhileAndPeek

      default char skipWhileAndPeek(CharFilter filter)
      Behaves like the following code: 
       skipWhile(filter);
 return peek();
      Parameters:
      filter - is used to decide which characters should be accepted.
      Returns:
      the first character that was not accepted by the given CharFilter. Only the accepted characters have been consumed, this scanner still points to the returned character.

    • skipWhileAndPeek

      default char skipWhileAndPeek(CharFilter filter, int max)
      Behaves like the following code: 
       skipWhile(filter, max);
 return peek();
      Parameters:
      filter - is used to decide which characters should be accepted.
      max - is the maximum number of characters that may be skipped.
      Returns:
      the first character that was not accepted by the given CharFilter. Only the accepted characters have been consumed, this scanner still points to the returned character.

    • getBufferParsed

      String getBufferParsed()
      Returns:
      the String with the characters that have already been parsed but are still available in the underlying buffer. May be used for debugging or error messages.

    • getBufferToParse

      String getBufferToParse()
      Returns:
      the String with the characters that have not yet been parsed but are available in the underlying buffer. May be used for debugging or error messages.

    • close

      void close()
      Specified by:
      close in interface AutoCloseable