com.mysql.cj.util

## Class StringInspector

- java.lang.Object
- - com.mysql.cj.util.StringInspector

    public class StringInspector
    extends Object

Utility class to inspect a MySQL string, typically a query string. Provides string searching and manipulation operations such as finding sub-strings, matching sub-strings or building a comments-free version of a string. This object keeps internal state that affect the operations, e.g., executing an indexOf operation after another causes the second to start the search form where the previous one stopped.

### Field Summary

Fields
`private String` `closingMarkers`
`private Set<SearchMode>` `defaultSearchMode`
`private boolean` `escaped`
`private boolean` `inMysqlBlock`
`private boolean` `markedEscape`
`private boolean` `markedInMysqlBlock`
`private int` `markedPos`
`private int` `markedStopAt`
`private static int` `NON_COMMENTS_MYSQL_VERSION_REF_LENGTH`
`private String` `openingMarkers`
`private String` `overridingMarkers`
`private int` `pos`
`private String` `source`
`private int` `srcLen`
`private int` `stopAt`

### Constructor Summary

Constructors
Constructor and Description
`StringInspector(String source, int startingPosition, String openingMarkers, String closingMarkers, String overridingMarkers, Set<SearchMode> searchMode)` This object provides string searching and manipulation operations such as finding sub-strings, matching sub-strings or building a comments-free version of a string.
`StringInspector(String source, String openingMarkers, String closingMarkers, String overridingMarkers, Set<SearchMode> searchMode)` This object provides string searching and manipulation operations such as finding sub-strings, matching sub-strings or building a comments-free version of a string.

### Method Summary

All Methods Instance Methods Concrete Methods
`char` `getChar()` Returns the character in the current position.
`int` `getPosition()` Returns the current position.
`int` `incrementPosition()` Increments the current position index, by one, taking into consideration the "escaped" status of current character, if the mode `SearchMode.ALLOW_BACKSLASH_ESCAPE` is present in the default search mode.
`int` `incrementPosition(int by)` Increments the current position index, by be given number, taking into consideration the "escaped" status of current character, if the mode `SearchMode.ALLOW_BACKSLASH_ESCAPE` is present in the default search mode.
`int` `incrementPosition(int by, Set<SearchMode> searchMode)` Increments the current position index, by be given number, taking into consideration the "escaped" status of current character, if the mode `SearchMode.ALLOW_BACKSLASH_ESCAPE` is present in the specified search mode.
`int` `incrementPosition(Set<SearchMode> searchMode)` Increments the current position index, by one, taking into consideration the "escaped" status of current character, if the mode `SearchMode.ALLOW_BACKSLASH_ESCAPE` is present in the search mode specified.
`private int` `indexOfClosingMarker(Set<SearchMode> searchMode)` Returns the position of the next closing marker corresponding to the opening marker in the current position.
`int` `indexOfIgnoreCase(String... searchFor)` Finds the position of the of the first of a consecutive sequence of strings within the source string, ignoring case, with the option to skip text delimited by the specified markers or inside comment blocks.
`int` `indexOfIgnoreCase(String searchFor)` Finds the position of the given string within the source string, ignoring case, with the option to skip text delimited by the specified markers or inside comment blocks.
`int` `indexOfIgnoreCase(String searchFor, Set<SearchMode> searchMode)` Finds the position of the given string within the source string, ignoring case, with the option to skip text delimited by the specified markers or inside comment blocks.
`int` `indexOfNextAlphanumericChar()` Returns the position of the next alphanumeric character regardless the default search mode originally specified.
`int` `indexOfNextChar()` Returns the position of the next valid character.
`private int` `indexOfNextChar(Set<SearchMode> searchMode)` Returns the position of the next valid character using the given search mode instead of the default one.
`int` `indexOfNextNonWsChar()` Returns the position of the next non-whitespace character regardless the default search mode originally specified.
`int` `indexOfNextWsChar()` Returns the position of the next whitespace character regardless the default search mode originally specified.
`void` `mark()` Marks the current object's state.
`int` `matchesIgnoreCase(String... toMatch)` Checks if the given consecutive sequence of strings matches the source string counting from the current position, ignoring case, with the option to skip text delimited by the specified markers or inside comment blocks.
`int` `matchesIgnoreCase(String toMatch)` Checks if the given string matches the source string counting from the current position, ignoring case, with the option to skip text delimited by the specified markers or inside comment blocks.
`void` `reset()` Resets this object's state to previously mark state.
`private void` `resetEscaped()` Checks if the current character is escaped by analyzing previous characters, as long as the search mode `SearchMode.ALLOW_BACKSLASH_ESCAPE` is present in the default search mode.
`void` `restart()` Resets this object's state to original values.
`int` `setStartPosition(int pos)` Sets the position from where the source string will be processed from now on, taking into consideration the "escaped" status of current character, if the mode `SearchMode.ALLOW_BACKSLASH_ESCAPE` is present in the default search mode.
`int` `setStopPosition(int pos)` Sets the position where the source string processing will stop.
`List<String>` `split(String delimiter, boolean trim)` Splits the source string by the given delimiter.
`String` `stripCommentsAndHints()` Returns a copy of the source string stripped of all comments and hints.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### NON_COMMENTS_MYSQL_VERSION_REF_LENGTH

    private static final int NON_COMMENTS_MYSQL_VERSION_REF_LENGTH

See Also:
  Constant Field Values

#### source

    private String source

#### openingMarkers

    private String openingMarkers

#### closingMarkers

    private String closingMarkers

#### overridingMarkers

    private String overridingMarkers

#### defaultSearchMode

    private Set<SearchMode> defaultSearchMode

#### srcLen

    private int srcLen

#### pos

    private int pos

#### stopAt

    private int stopAt

#### escaped

    private boolean escaped

#### inMysqlBlock

    private boolean inMysqlBlock

#### markedPos

    private int markedPos

#### markedStopAt

    private int markedStopAt

#### markedEscape

    private boolean markedEscape

#### markedInMysqlBlock

    private boolean markedInMysqlBlock

### Constructor Detail

#### StringInspector

    public StringInspector(String source,
                           String openingMarkers,
                           String closingMarkers,
                           String overridingMarkers,
                           Set<SearchMode> searchMode)

This object provides string searching and manipulation operations such as finding sub-strings, matching sub-strings or building a comments-free version of a string.

Parameters:
  `source` - the source string to process
  `openingMarkers` - the characters that can delimit the beginning of a quoted text block
  `closingMarkers` - the characters that can delimit the end of a of a quoted text block. The length of this parameter must match the length of th previous one
  `overridingMarkers` - the subset of `openingMarkers` that override the remaining markers, e.g., if `openingMarkers = "'("`, `closingMarkers = "')"` and `overridingMarkers = "'"` then the block between the outer parenthesis in `"start ('max('); end"` is strictly consumed, otherwise the suffix `"'); end"` would end up being consumed too in the process of handling the nested parenthesis.
  `searchMode` - a `Set`, ideally an `EnumSet`, containing the default flags from the enum `SearchMode` that determine the behavior of the search and manipulation operations. Note that some operation may override the search mode according to their needs, but the default one is not touched.

#### StringInspector

    public StringInspector(String source,
                           int startingPosition,
                           String openingMarkers,
                           String closingMarkers,
                           String overridingMarkers,
                           Set<SearchMode> searchMode)

This object provides string searching and manipulation operations such as finding sub-strings, matching sub-strings or building a comments-free version of a string.

Parameters:
  `source` - the source string to process
  `startingPosition` - the position from where the source string will be processed
  `openingMarkers` - the characters that can delimit the beginning of a quoted text block
  `closingMarkers` - the characters that can delimit the end of a of a quoted text block. The length of this parameter must match the length of th previous one
  `overridingMarkers` - the subset of `openingMarkers` that override the remaining markers, e.g., if `openingMarkers = "'("`, `closingMarkers = "')"` and `overridingMarkers = "'"` then the block between the outer parenthesis in `"start ('max('); end"` is strictly consumed, otherwise the suffix `"'); end"` would end up being consumed too in the process of handling the nested parenthesis.
  `searchMode` - a `Set`, ideally an `EnumSet`, containing the default flags from the enum `SearchMode` that determine the behavior of the search and manipulation operations. Note that some operation may override the search mode according to their needs, but the default one is not touched.

### Method Detail

#### setStartPosition

    public int setStartPosition(int pos)

Sets the position from where the source string will be processed from now on, taking into consideration the "escaped" status of current character, if the mode `SearchMode.ALLOW_BACKSLASH_ESCAPE` is present in the default search mode.

Parameters:
  `pos` - the position from where the source string will be processed
Returns:
  the previous current position value

#### setStopPosition

    public int setStopPosition(int pos)

Sets the position where the source string processing will stop.

Parameters:
  `pos` - the position where the source string will stop being processed
Returns:
  the previous stop position value

#### mark

    public void mark()

Marks the current object's state. A subsequent call to the `reset()` method restores the marked state.

#### reset

    public void reset()

Resets this object's state to previously mark state.

#### restart

    public void restart()

Resets this object's state to original values. Allows to reuse the object from a fresh start.

#### getChar

    public char getChar()

Returns the character in the current position.

Returns:
  the character in the current position

#### getPosition

    public int getPosition()

Returns the current position.

Returns:
  the current position

#### incrementPosition

    public int incrementPosition()

Increments the current position index, by one, taking into consideration the "escaped" status of current character, if the mode `SearchMode.ALLOW_BACKSLASH_ESCAPE` is present in the default search mode.

Returns:
  the new current position

#### incrementPosition

    public int incrementPosition(Set<SearchMode> searchMode)

Increments the current position index, by one, taking into consideration the "escaped" status of current character, if the mode `SearchMode.ALLOW_BACKSLASH_ESCAPE` is present in the search mode specified.

Parameters:
  `searchMode` - the search mode to use in this operation
Returns:
  the new current position

#### incrementPosition

    public int incrementPosition(int by)

Increments the current position index, by be given number, taking into consideration the "escaped" status of current character, if the mode `SearchMode.ALLOW_BACKSLASH_ESCAPE` is present in the default search mode.

Parameters:
  `by` - the number of positions to increment
Returns:
  the new current position

#### incrementPosition

    public int incrementPosition(int by,
                                 Set<SearchMode> searchMode)

Increments the current position index, by be given number, taking into consideration the "escaped" status of current character, if the mode `SearchMode.ALLOW_BACKSLASH_ESCAPE` is present in the specified search mode.

Parameters:
  `by` - the number of positions to increment
  `searchMode` - the search mode to use in this operation
Returns:
  the new current position

#### resetEscaped

    private void resetEscaped()

Checks if the current character is escaped by analyzing previous characters, as long as the search mode `SearchMode.ALLOW_BACKSLASH_ESCAPE` is present in the default search mode.

#### indexOfNextChar

    public int indexOfNextChar()

Returns the position of the next valid character. This method does not increment the current position automatically, i.e., if already positioned in a valid character then repeated calls return always the same index. If the character in the current position matches one of the prefixes that determine a skipping block, then the position marker advances to the first character after the block to skip.

Returns:
  the position of the next valid character, or the current position if already on a valid character

#### indexOfNextChar

    private int indexOfNextChar(Set<SearchMode> searchMode)

Returns the position of the next valid character using the given search mode instead of the default one. This method does not increment the current position automatically, i.e., if already positioned in a valid character then repeated calls return always the same index. If the character in the current position matches one of the prefixes that determine a skipping block, then the position marker advances to the first character after the block to skip.

Parameters:
  `searchMode` - the search mode to use in this operation
Returns:
  the position of the next valid character, or the current position if already on a valid character

#### indexOfClosingMarker

    private int indexOfClosingMarker(Set<SearchMode> searchMode)

Returns the position of the next closing marker corresponding to the opening marker in the current position. If the current position is not an opening marker, then -1 is returned instead.

Parameters:
  `searchMode` - the search mode to use in this operation
Returns:
  the position of the next closing marker corresponding to the opening marker in the current position

#### indexOfNextAlphanumericChar

    public int indexOfNextAlphanumericChar()

Returns the position of the next alphanumeric character regardless the default search mode originally specified. This method does not increment the current position automatically, i.e., if already positioned in a valid character then repeated calls return always the same index. If the character in the current position matches one of the prefixes that determine a skipping block, then the position marker advances to the first alphanumeric character after the block to skip.

Returns:
  the position of the next valid character, or the current position if already on a valid character

#### indexOfNextNonWsChar

    public int indexOfNextNonWsChar()

Returns the position of the next non-whitespace character regardless the default search mode originally specified. This method does not increment the current position automatically, i.e., if already positioned in a valid character then repeated calls return always the same index. If the character in the current position matches one of the prefixes that determine a skipping block, then the position marker advances to the first non-whitespace character after the block to skip.

Returns:
  the position of the next valid character, or the current position if already on a valid character

#### indexOfNextWsChar

    public int indexOfNextWsChar()

Returns the position of the next whitespace character regardless the default search mode originally specified. This method does not increment the current position automatically, i.e., if already positioned in a valid character then repeated calls return always the same index. If the character in the current position matches one of the prefixes that determine a skipping block, then the position marker advances to the first whitespace character after the block to skip.

Returns:
  the position of the next valid character, or the current position if already on a valid character

#### indexOfIgnoreCase

    public int indexOfIgnoreCase(String searchFor)

Finds the position of the given string within the source string, ignoring case, with the option to skip text delimited by the specified markers or inside comment blocks.

Parameters:
  `searchFor` - the sub-string to search for
Returns:
  the position where the sub-string is found, starting from the current position, or -1 if not found

#### indexOfIgnoreCase

    public int indexOfIgnoreCase(String searchFor,
                                 Set<SearchMode> searchMode)

Finds the position of the given string within the source string, ignoring case, with the option to skip text delimited by the specified markers or inside comment blocks.

Parameters:
  `searchFor` - the sub-string to search for
  `searchMode` - the search mode to use in this operation
Returns:
  the position where the sub-string is found, starting from the current position, or -1 if not found

#### indexOfIgnoreCase

    public int indexOfIgnoreCase(String... searchFor)

Finds the position of the of the first of a consecutive sequence of strings within the source string, ignoring case, with the option to skip text delimited by the specified markers or inside comment blocks.

Independently of the `searchMode` specified, when searching for the second and following sub-strings `SearchMode.SKIP_WHITE_SPACE` will be added and `SearchMode.SKIP_BETWEEN_MARKERS` removed.

Parameters:
  `searchFor` - the sequence of sub-strings to search
Returns:
  the position where the first sub-string is found, starting from the current position, or -1 if not found

#### matchesIgnoreCase

    public int matchesIgnoreCase(String toMatch)

Checks if the given string matches the source string counting from the current position, ignoring case, with the option to skip text delimited by the specified markers or inside comment blocks.

Parameters:
  `toMatch` - the sub-string to match
Returns:
  the position where the sub-string match ended, or -1 if not matched

#### matchesIgnoreCase

    public int matchesIgnoreCase(String... toMatch)

Checks if the given consecutive sequence of strings matches the source string counting from the current position, ignoring case, with the option to skip text delimited by the specified markers or inside comment blocks.

Independently of the `searchMode` specified, when matching the second and following sub-strings `SearchMode.SKIP_WHITE_SPACE` will be added and `SearchMode.SKIP_BETWEEN_MARKERS` removed.

Parameters:
  `toMatch` - the sequence of sub-strings to match
Returns:
  the position where the sequence of sub-strings match ended, or -1 if not matched

#### stripCommentsAndHints

    public String stripCommentsAndHints()

Returns a copy of the source string stripped of all comments and hints.

Returns:
  a comments-free string

#### split

    public List<String> split(String delimiter,
                              boolean trim)

Splits the source string by the given delimiter. Consecutive delimiters result in empty string parts.

Parameters:
  `delimiter` - the characters sequence where to split the source string
  `trim` - whether each one of the parts should be trimmed or not
Returns:
  a `List` containing all the string parts

Copyright © 2016, 2025, Oracle and/or its affiliates.