FIND

Syntax

FIND [{FIRST OCCURRENCE}|{ALL OCCURRENCES} OF] pattern
  IN [section_of] dobj
  [IN {BYTE|CHARACTER} MODE]
  [{RESPECTING|IGNORING} CASE]
  [MATCH COUNT  mcnt]
  { {[MATCH OFFSET moff]
     [MATCH LENGTH mlen]}
  | [RESULTS result_tab|result_wa] }
  [SUBMATCHES s1 s2 ...].

Extras:

1. ... {FIRST OCCURRENCE}|{ALL OCCURRENCES} OF

2. ... IN {BYTE|CHARACTER} MODE

3. ... {RESPECTING|IGNORING} CASE

4. ... MATCH COUNT mcnt

5. ... MATCH OFFSET moff

6. ... MATCH LENGTH mlen

7. ... RESULTS result_tab|result_wa

8. ... SUBMATCHES s1 s2 ...

Effect

: The data object dobj is searched for the byte or character sequence specified by the search string pattern. The addition OCCURRENCE[S] determines whether only the first, or all occurrences are searched. The addition section_of can be used to restrict the search range. The addition CASE is used to determine whether upper/lower case is taken into account in the search. The additions MATCH, SUBMATCHES, and RESULTS are used to determine the number, position, and length of the found sequence(s).

The search is ended when the search string is found for the first time or when all the search strings in the search range have been found, or when the end of the search range is reached. The user is informed of the search result by setting sy-subrc.

In character string processing, the closing blanks are taken into account in data objects dobj of fixed length.

Note

The statement FIND IN TABLE is available for searching in internal tables.

System fields

sy-subrc	Meaning
0	The search string was found at least once in the search range.
4	The search string was not found in the search range.
8	The search string contains an invalid double-byte character in character string processing.

Addition 1

... {FIRST OCCURRENCE}|{ALL OCCURRENCES} OF

The optional addition {FIRST OCCURRENCE}|{ALL OCCURRENCES} OF determines whether program only searches for the first occurrence, or all occurrences of the search string. If the addition FIRST OCCURENCE, or none of the additions is specified, only the first occurrence is found. Otherwise, all occurrences are found.

If sub_string is an empty string in the pattern or is of type c, d, n or t and only contains blank characters, when searching for the first occurrence, the space in front of the first character or byte of the search range is found. If searching for all occurrences, in this case the exception CX_SY_FIND_INFINITE_LOOP is triggered.

If regex contains a regular expression in pattern that matches the empty character string, the search for one occurrence also finds the space before the first character. When searching for all occurrences, in this case, the search finds the space before the first character, all intermediate spaces that are not within a match, and the space after the last character.

Addition 2

... IN {BYTE|CHARACTER} MODE

Effect

: The optional addition IN {BYTE|CHARACTER} MODE determines whether byte or character string processing takes place. If the addition is not specified, character string processing is performed. Depending on the processing type, dobj and sub_string in pattern must be byte-like or character-type. If regular expressions are used in pattern, only character string processing is permitted.

Addition 3

... {RESPECTING|IGNORING} CASE

Effect

: This addition is only permitted for character string processing. It determines whether upper/lower case is taken into account in pattern and dobj when searching. If RESPECTING CASE is specified, the text is case-sensitive, and if IGNORING CASE is specified, the text is not case-sensitive. If neither of the additions is specified, RESPECTING CASE is used implicitly. If a regular expression is entered for pattern as an object of the class CL_ABAP_REGEX, this addition is not permitted. Instead, the properties of the object are taken into account in the search.

Addition 4

... MATCH COUNT mcnt

Effect

: If the search string pattern is found in the search range, the addition MATCH COUNT stores the number of found locations in the data object mcnt. If FIRST OCCURRENCE is used, this value is always 1 if the search is successful. For mcnt, a variable of the data type i is expected. If the search is unsuccessful, mcnt is set to 0.

Addition 5

... MATCH OFFSET moff

Effect:

If the search string pattern is found in the search range, the addition MATCH OFFSET stores the offset of the last found location in relation to the data object dobj in the data object moff. If FIRST OCCURRENCE is used, this is the offset of the first found location. For moff, a variable of the data type i is expected. If the search is not successful, moff contains its previous value.

Note

: The system field sy-fdpos is not supplied by FIND.

Addition 6

... MATCH LENGTH mlen

Effect:

If the search string pattern is found in the search range, the addition MATCH LENGTH stores the length of the last found substring in the data object mlen. If using FIRST OCCURRENCE, this is the length of the first found location. For mlen, a variable of data type i is expected. If the search is not successful, mlen contains its previous value.

Addition 7

... RESULTS result_tab|result_wa

Effect:

If the search string pattern is found in the search range, the addition RESULTS stores the offsets of the found locations, the lengths of the found substrings, and information on the registers of the subgroups of regular expressions, either in an internal table result_tab or in a structure result_wa.

The internal table result_tab must have the table type MATCH_RESULT_TAB, and the structure result_wa must have the type MATCH_RESULT from the ABAP Dictionary. The line type of the internal table is also MATCH_RESULT.

When an internal table is entered, this is initialized before the search and a line is inserted in the table for every match found. When a structure is entered, this is assigned the values of the last found location. If FIRST OCCURRENCE is used and the search is successful, only one line is inserted in the internal table.

The line or structure type MATCH_RESULT has the following components:

OFFSET of type INT4 for the offset of the substring
LENGTH of type INT4 for the length of the substring
SUBMATCHES of table type SUBMATCH_RESULT_TAB with the line type SUBMATCH_RESULT for the offset and length of the substrings of the current found locations that are stored in the registers of the subgroups of a regular expression.

The lines of result_tab are sorted according to the columns OFFSET and LENGTH. An additional component LINE is only important in the variant FIND IN TABLE.

Following an unsuccessful search, the content of an internal table result_tab is initial, while a structure result_wa contains its previous value.

Note

The addition RESULTS is particularly suitable for use with the addition ALL OCCURRENCES when specifying a table, and for use with the FIRST OCCURRENCE when specifying a structure.

Example:

The following search for a regular expression finds the two substrings "ab" at offset 0 and "ba" at offset 2, and fills the internal table result_tab with two rows accordingly. As the regular expression contains three subgroups, the component submatches contains three lines in each case. The first line of submatches refers to the outermost bracket, the second line refers to the first internal bracket, and the third line refers to the second internal bracket. For the first found location, the first and second lines contains the offset and length while the third line is undefined. For the second found location, the first and third lines contains the offset and length, while the second line is undefined.

DATA: result_tab TYPE match_result_tab.

FIND ALL OCCURRENCES OF REGEX `((ab)|(ba))`
IN 'abba'
RESULTS result_tab.

Addition 8

... SUBMATCHES s1 s2 ...

Effect:

This addition is only permitted if a regular expression is used in pattern. The current contents of the register of subgroups of the regular expression for the current found location are written to the variables s1, s2, ..., for which a character-type data type is expected. When ALL OCCURRENCES is used, the last found location is evaluated. If more variables s1, s2, ... are listed than subgroups are available, the superfluous variables are initialized. If fewer variables s1, s2, ... are listed than subgroups are available, the superfluous subgroups are ignored.

Example

: The regular expression after REGEX has two subgroups. The search finds the substring from offset 0 of length 14. The content of the register of the subgroups is "Hey" and "my".

DATA: text TYPE string,
      moff TYPE i,
      mlen TYPE i,
      s1   TYPE string,
      s2   TYPE string.

text = `Hey hey, my my, Rock and roll can never die`.

FIND REGEX `(\w+)\W+\1\W+(\w+)\W+\2`
     IN text
     IGNORING CASE
     MATCH OFFSET moff
     MATCH LENGTH mlen
     SUBMATCHES s1 s2.

Exceptions

Catchable Exceptions

CX_SY_FIND_INFINITE_LOOP

Cause: Substring of length 0 generates an endless loop when searching for all occurrences.
Runtime Error: FIND_INFINITE_LOOP

CX_SY_RANGE_OUT_OF_BOUNDS

Cause: Illegal offset or length specification in the addition SECTION OF.
Runtime Error: REFI_WRONG_SECTION (catchable)

CX_SY_INVALID_REGEX

Cause: Illegal expression after the addition REGEX.
Runtime Error: INVALID_REGEX

CX_SY_REGEX_TOO_COMPLEX

Cause: The regular expression after the addition REGEX is too complex.
Runtime Error: REGEX_TOO_COMPLEX