ABAP Keyword Documentation → ABAP - Reference → Processing Internal Data → Character String and Byte String Processing → Statements for Character String and Byte String Processing → FIND
FIND - options
Other versions: 7.31 | 7.40 | 7.54
Syntax
... [{RESPECTING|IGNORING} CASE]
[MATCH COUNT mcnt]
{ {[MATCH OFFSET moff]
[MATCH LENGTH mlen]}
| [RESULTS result_tab|result_wa] }
[SUBMATCHES s1 s2 ...] ...
Extras
1. ... {RESPECTING|IGNORING} CASE
2. ... MATCH COUNT mcnt
3. ... MATCH OFFSET moff
4. ... MATCH LENGTH mlen
5. ... RESULTS result_tab|result_wa
6. ... SUBMATCHES s1 s2 ...
Effect
These additions control the FIND
statement and provide advanced evaluation options. You can use the CASE addition
to specify whether the search is case-sensitive. You can use the MATCH,
SUBMATCHES, and RESULTS additions to determine the number, position, and length of the sequence(s) found.
Addition 1
... {RESPECTING|IGNORING} CASE
Effect
You can use this addition in string processing only. It specifies whether pattern
and dobj are to be handled as case-sensitive in the search. When RESPECTING
CASE is used, the search is case-sensitive and when IGNORING CASE
is used, it is not. If you do not specify either of these additions, RESPECTING
CASE is used implicitly. If a regular expression is passed as an object of class CL_ABAP_REGEX
for pattern, this addition is not permitted. Instead, the properties of the object are respected by the search.
Addition 2
... MATCH COUNT mcnt
Effect
If the search pattern pattern is found in the search range, the MATCH
COUNT addition saves the number of occurrences in the data object mcnt.
If FIRST OCCURRENCE is used, this value is always 1 when the search is successful.
mcnt expects a variable with data type i. If the search is successful, mcnt is set to 0.
Addition 3
... MATCH OFFSET moff
Effect
If the search pattern pattern is found in the search range, the MATCH
OFFSET addition saves the offset of the last occurrence in relation to the dobj
operands in the data object moff. If FIRST OCCURRENCE
is used, this is the offset of the first occurrence. moff expects a variable
of data type i. If the search is not successful, moff retains its previous value.
Addition 4
... MATCH LENGTH mlen
Effect
If the search pattern pattern is found in the search range, the MATCH
LENGTH addition saves the length of the last substrings found in the data object mlen.
If FIRST OCCURRENCE is used, this is the length of the first occurrence
mlen expects a variable of data type i. If the search is not successful, mlen retains its previous value.
Addition 5
... RESULTS result_tab|result_wa
Effect
If the search pattern pattern is found in the search range, the RESULTS
addition saves the offsets of the occurrences, the lengths of the substrings found, and information
about the registers for 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 ABAP Dictionary. The row type of the internal table is also MATCH_RESULT.
When an internal table is specified, this table is initialized before the search starts. When the search
runs, a row is added to the internal table for each match found. If a structure is specified, it is
assigned the values of the last occurrence. If FIRST OCCURRENCE is used, exactly one row is added to the table when the search is successful.
The row type or structure type MATCH_RESULT has the following components:
- OFFSET of type INT4 for storing the offset of the substring
- LENGTH of type INT4 for storing the length of the substring
-
SUBMATCHES from table type SUBMATCH_RESULT_TAB with the row type
SUBMATCH_RESULT for storing the offset and length of the substring of the current occurrence, which are saved in the
subgroup registers of a regular expression
The rows from result_tab are sorted according to the OFFSET and LENGTH columns.
An additional component LINE is only relevant for the FIND IN TABLE variant.
If a search is not successful, the contents of the result_tab internal table are empty, whereas the result_wa structure retains its contents.
Note
The RESULTS addition is particularly useful when used in conjunction with
the ALL OCCURRENCES addition when an internal table is used, and in conjunction with the FIRST OCCURRENCE addition when a structure is used.
Example
The following search for a regular expression finds the two substrings "ab" and "ba" at offset 0 and
offset 2, and fills the internal table result_tab with two corresponding
values. Since the regular expression contains three subgroups, the submatches
component contains three lines. The first line of submatches relates to the
outer parenthesis, the second line relates to the first inner parenthesis, and the third line relates
to the second inner parenthesis. The first and second lines contain the offset and length of the first
occurrence, and the third line remains undefined. The first and third lines contain the offset and length of the second occurrence, and the second line remains undefined.
DATA: result_tab TYPE match_result_tab.
FIND ALL OCCURRENCES OF REGEX `((ab)|(ba))`
IN 'abba'
RESULTS result_tab.
Addition 6
... SUBMATCHES s1 s2 ...
Effect
This addition can be used only when a
regular expression is used in pattern. The current contents of the
subgroup registers of the regular expression
are written for the current found location to the s1, s2,
... variables, for which a character-like type is expected. When ALL OCCURRENCES
is used, the last occurrence is evaluated. If there are more variables s1,
s2, ... than subgroups, the surplus variables of fixed length are filled
with blanks and strings are initialized. If there are fewer variables s1, s2, ... than subgroups, the surplus subgroups are ignored.
Example
The regular expression after REGEX has two subgroups. The search finds the substring at offset 0 with length 14. The contents of the registry for the subgroups are "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.