UNSTRING

Syntax

Command
Mandatory parameter
Optional parameter
Mandatory keyword
Optional keyword

<Destination> := UNSTRING (<Source>[, <Position>][, <Delimiter(s)>][, <Multiple occurrence>])

Description

Copies one or more substrings from <Source> into <Destination>. The system item SI-LENGTH will be set to the length of the returned substring.

Diagram

Returned value type

String

Parameters

Parameter	Description
<Destination>	Variable for the result.
<Source>	Expression giving a string (which may also be a realstring) to copy characters from. This string will be split into substrings if one or more delimiters are used, each substring then contains all characters until the next delimiter. It is permitted to have different delimiters in a source string, as long as these delimiters are all specified as <Delimiter>. It is also permitted to have one or more delimiters placed directly next to another. The acting will then depend on the option <Multiple occurrence>.
<Position>	Starting position. The substring for the <Destination> begins with the first character from this point. If a variable is used, its value will be updated after execution of the UNSTRING instruction. The new value depends on the setting for <Multiple occurrence>. If that option is not specified (or specified as false), the new value points to the first encountered non-delimiter character. When the delimiter character is not found in the (remainder of the) string, the new value will be the length of the string plus one. Note: when no position variable is specified unstring will always return the first part of the string up to the first occurrence of a delimiter, see example 1.
<Delimiter(s)>	One or more <Delimiter> values. If multiple delimiters are specified, these have to be separated with a ",". The default delimiter value is a space.
<Multiple occurrence>	Boolean value that determines the acting in cases that multiple delimiters in the <Source> are placed directly next to another and the <Position> is passed through a variable. If the value is "False" (default), consecutive occurrences of the delimiter are treated as a single occurrence. So, the position variable will then be updated to point to the first encountered non-delimiter character. If the value is set to "True", <Position> will be updated to the first position after the first encountered occurrence of the delimiter. In this case, the position may be set to a delimiter character.

Examples


In all the examples the a-crlf variable is an Alpha with length 2 and containing the literal CR and LF characters. I.e. a-crlf := '@0D@@0A@'

Example 1

// unstring without position variable will
// always return the first word
memo-result := 'Result example 1:' + a-crlf
s-descr     := 'str1   str2 str3      str4'
memo-result += s-descr + a-crlf
memo-result += '--------------------------' + a-crlf
s-result    := unstring (s-descr,)
memo-result += s-result + a-crlf
s-result    := unstring (s-descr,)
memo-result += s-result + a-crlf
s-result    := unstring (s-descr,)
memo-result += s-result + a-crlf

Example 2

// unstring with position variable and without delimiter
// will split the string into words
memo-result := 'Result example 2:' + a-crlf
s-descr := 'str1 str2 str3 str4'
memo-result += s-descr + a-crlf
memo-result += '--------------------------' + a-crlf
loop while i-position < length (s-descr)
s-result := unstring (s-descr, i-position)
memo-result += i-position + ' ' + s-result + a-crlf
endloop

Example 3

// unstring with position variable and specified delimiter
memo-result := 'Result example 3:' + a-crlf
s-descr := 'str1 str2 str3 str4'
memo-result += s-descr + a-crlf
memo-result += '--------------------------' + a-crlf
loop while i-position < length (s-descr)
s-result := unstring (s-descr, i-position, ' ', true)
memo-result += i-position + ' ' + s-result + a-crlf
endloop

Example 4

// consecutive occurrence of the delimiter will be treated
// as multiple occurrence
memo-result := 'Result example 4:' + a-crlf
loop while i-position < 6
s-result := unstring ('AB@@CD', i-position, '@', true)
memo-result += s-result + a-crlf
endloop

Example 5

// consecutive occurrence of the delimiter will be treated
// as single occurrence
memo-result := 'Result example 5:' + a-crlf
loop while i-position < 6
s-result := unstring ('AB@@CD', i-position, '@', false)
memo-result += s-result + a-crlf
endloop

Example 6

// consecutive occurrence of the delimiter defaults to false
// (single occurrence)
memo-result := 'Result example 6:' + a-crlf
loop while i-position < 6
s-result := unstring ('AB@@CD', i-position, '@')
memo-result += s-result + a-crlf
endloop

Example 7

// Two different delimiters
memo-result := 'Result example 7:' + a-crlf
loop while i-position < 10
s-result := unstring ('ABC+DEF-GHI', i-position, '-', '+')
memo-result += s-result + a-crlf
endloop

Return to

Commands