Method Detail

• 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 text (EOT) has been reached.

• next

  char next()

  This method reads the current character and increments the index stepping to the next character. You need to check if a character is available before calling this method.

  Returns:

  the current character.

• forceNext

  char forceNext()

  Like next() this method reads the current character and increments the index. If there is no character available this method will do nothing but return '\0' (the NULL character and NOT '0').

  Returns:

  the current character or 0 if none is available.

• peek

  char peek()

  This method reads the current character without incrementing the index. You need to check if a character is available before calling this method.

  Returns:

  the current character.

• forcePeek

  char forcePeek()

  This method reads the current character without incrementing the index. If there is no character available this method will return 0 (the NULL character and NOT '0').

  Returns:

  the current character or 0 if none is available.

• 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 current 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 current character is no such digit.

• readLong

  long readLong​(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). Use 19 or higher to be able to read any long number.

  Returns:

  the parsed number.

  Throws:

  NumberFormatException - if the current current position does NOT point to a number.

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

  Throws:

  NumberFormatException - if the current current position does NOT point to a number.

• readFloat

  default float readFloat()
                   throws NumberFormatException

  This method reads the float value (decimal number) starting at the current position by reading as many matching characters as available and returns its parsed value.
  

  Returns:

  the parsed number.

  Throws:

  NumberFormatException - if the current current position does NOT point to a number.

• consumeDecimal

  String consumeDecimal()

  Consumes the characters of a decimal number (double or float).

  Returns:

  the decimal number as String.

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

• expect

  default boolean expect​(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 like the following code:

   read(expected.length).equals(expected)
   

  ATTENTION:
  Be aware that if already the first character differs, this method will NOT change the state of the scanner. So take care NOT to produce infinity loops.

  Parameters:

  expected - is the expected string.

  Returns:

  true if the expected string was successfully consumed from this scanner, false otherwise.

• expect

  boolean expect​(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 like the following code:

   read(expected.length).equals[IgnoreCase](expected)
   

  ATTENTION:
  Be aware that if already the first character differs, this method will NOT change the state of the scanner. So take care NOT to produce infinity loops.

  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.

• expectStrict

  default boolean expectStrict​(String expected)

  This method acts as expect(String, boolean) but if the expected String is NOT completely present, no character is consumed and the state of the scanner remains unchanged.
  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.

• expectStrict

  boolean expectStrict​(String expected,
                       boolean ignoreCase)

  This method acts as expect(String, boolean) but if the expected String is NOT completely present, no character is consumed and the state of the scanner remains unchanged.
  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.

  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.

• expect

  boolean expect​(char expected)

  This method checks that the current character is equal to the given expected character.
  If the current character was as expected, 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.

• 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.expectStrict(expected, ignoreCase)) {
     throw new IllegalStateException(...);
   }
   

  Parameters:

  expected - is the expected string.

  ignoreCase - - if true the case of the characters is ignored during comparison.

• require

  void require​(char expected)

  This method verifies that the current 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.

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

• readUntil

  String readUntil​(char stop,
                   boolean acceptEot)

  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.

  acceptEot - if true EOT 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 acceptEot is false.

• readUntil

  String readUntil​(CharFilter filter,
                   boolean acceptEot)

  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.

  acceptEot - if true if EOT should be treated like the stop character and the rest of the text will be returned, false otherwise (to return null if EOT 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 acceptEot is false.

• readUntil

  default String readUntil​(CharFilter filter,
                           boolean acceptEot,
                           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.

  acceptEot - if true if EOT should be treated like the stop character and the rest of the text will be returned, false otherwise (to return null if EOT 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 EOT was reached without a stop signal the entire rest of the data is returned or null if acceptEot is false.

• readUntil

  default String readUntil​(CharFilter filter,
                           boolean acceptEot,
                           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.

  acceptEot - if true if EOT should be treated like the stop character and the rest of the text will be returned, false otherwise (to return null if EOT 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 EOT was reached without a stop signal the entire rest of the data is returned or null if acceptEot is false.

• readUntil

  String readUntil​(CharFilter filter,
                   boolean acceptEot,
                   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.

  acceptEot - if true if EOT should be treated like the stop character and the rest of the text will be returned, false otherwise (to return null if EOT 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 EOT was reached without a stop signal the entire rest of the data is returned or null if acceptEot is false. Thre result will be trimmed if trim is true.

• readUntil

  String readUntil​(char stop,
                   boolean acceptEot,
                   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.forceNext();
   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.

  acceptEot - if true EOT 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 acceptEot is false.

• readUntil

  String readUntil​(char stop,
                   boolean acceptEot,
                   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.

  acceptEot - if true EOT 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(CharFilter, boolean, CharScannerSyntax)

• readUntil

  String readUntil​(CharFilter filter,
                   boolean acceptEot,
                   CharScannerSyntax syntax)

  This method reads all next characters until the given CharFilter accepts the current character as stop character or the end of text (EOT) 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:

  filter - is used to decide where to stop.

  acceptEot - if true EOT 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(char, boolean, CharScannerSyntax)

• 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 - is 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:

  skipWhile(CharFilter)

• readWhile

  String readWhile​(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 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.

  See Also:

  skipWhile(char)

• 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 the stream was reached.

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

  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(char)

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

  skipWhile(char)

• skipWhileAndPeek

  default char skipWhileAndPeek​(CharFilter filter)

  Behaves like the following code:

   skipWhile(filter);
   return forcePeek();
   

  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 forcePeek();
   

  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.

• readLine

  default String readLine()

  Returns:

  a String with the data until the end of the current line or EOT. Will be null if the EOT 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 EOT. Will be null if the EOT has already been reached and hasNext() returns false.

• 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​(boolean tolerant)

  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:

  tolerant - - true if invalid escape sequences should be tolerated (as '?'), false to throw an exception in such case.

  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​(boolean tolerant)

  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:

  tolerant - - true if an invalid char literal should be tolerated (as '?'), false to throw an exception in such case.

  Returns:

  the parsed Java String literal value or null if not pointing to a String literal.

• isEot

  boolean isEot()

  Returns:

  true if end of text (EOT) is known to have been reached, false otherwise. The returned result will be almost the same as !hasNext() but this method will not modify the state of this scanner (read additional data, modify buffers, etc.). However, if the underlying stream is already consumed without returning -1 to signal EOS this method may return false even though the next call of hasNext() may also return false.

• isEos

  boolean isEos()

  Returns:

  true if the end of stream (EOS) has been reached, false otherwise. If true (EOS) the internal buffer contains the entire rest of the data to scan in memory. If then also all data is consumed from the buffer, EOT has been reached. For instances of that are not backed by an underlying stream of data (like CharSequenceScanner) this method will always return true.