substring, substring_... - Substring Functions

substring, substring_... - Substring Functions

Syntax Forms

1. ... substring( val = text [off = off] [len = len] ) ...

2. ... substring_from( val = text {sub = substring}|{regex = regex}
                      [case = case] [occ = occ] [len = len]  ) ...

3. ... substring_after( val = text {sub = substring}|{regex = regex}
                       [case = case] [occ = occ] [len = len]  ) ...

4. ... substring_before( val = text {sub = substring}|{regex = regex}
                        [case = case] [occ = occ] [len = len]  ) ...

5. ... substring_to( val = text {sub = substring}|{regex = regex}
                    [case = case] [occ = occ] [len = len]  ) ...

Effect

In the argument text, the substring functions determine a substring and return it.

The substring is determined as follows:

• The function substring uses the offset off and the length len to return a certain subrange. At least one of the two arguments off or len must be specified.

• The function substring_from scans text for the match (specified in occ) with the character string specified in substring or with the regular expression specified in regex and returns the subrange of the length len from the offset of the found location. If len is not specified, the substring is returned to the end of the character string. If substring is empty, an exception from the class CX_SY_STRG_PAR_VAL is raised. The search is case-sensitive by default, but you can override this with the parameter case. If no substring is found, the return code is empty.

• The function substring_after works in the same way as substring_from, but the subrange plus the length of the substring found is returned, from the offset of the found location.

• The function substring_before works in the same way as substring_from, but the subrange of the length len is returned, before the offset of the found location. If len is not specified, the subrange is formed from the start of the character string.

• The function substring_to works in the same way as substring_before, but the subrange before the offset of the found location plus the length of the substring found is returned.

The return code has the type string accordingly.

Note

The performance of the substring functions is not as good as a direct substring access. They do, however, allow you to use expressions in all operand positions.

Example

The return codes of the following function calls are: "CD", "CDEFGH"., "EFGH"., "AB"., and "ABCD".

DATA  result TYPE string.
...
result = substring( val = 'ABCDEFGH' off = 2 len = 2 ).
...
result = substring_from( val = 'ABCDEFGH' sub = 'CD' ).
...
result = substring_after( val = 'ABCDEFGH' sub = 'CD' ).
...
result = substring_before( val = 'ABCDEFGH' sub = 'CD' ).
...
result = substring_to( val = 'ABCDEFGH' sub = 'CD' ).
...

Exceptions

Catchable Exceptions

CX_SY_RANGE_OUT_OF_BOUNDS

• Cause: Illegal offset or length specification in the off and len.
  Runtime Error: STRING_OFFSET_TOO_LARGE
  

CX_SY_REGEX_TOO_COMPLEX

• Cause: More information: Exceptions in Regular Expressions.
  Runtime Error: REGEX_TOO_COMPLEX
  

CX_SY_STRG_PAR_VAL

• Cause: Substring in sub or regular expression in regex is empty or occurrence in occ is 0.
  Runtime Error: STRG_ILLEGAL_PAR