$Extract()

Returns a substring of a given string.

The format for the $EXTRACT function is:

$E[XTRACT](expr[,intexpr1[,intexpr2]])

The expression specifies a string from which $EXTRACT() derives a substring.
The first optional integer expression (second argument) specifies the starting character position in the string. If the starting position is beyond the end of the expression, $EXTRACT() returns an empty string. If the starting position is zero (0) or negative, $EXTRACT() starts at the first character; if this argument is omitted, $EXTRACT() returns the first character of the expression. $EXTRACT() numbers character positions starting at one (1) (that is, the first character of a string is at position one (1)).
The second optional integer expression (third argument) specifies the ending character position for the result. If the ending position is beyond the end of the expression, $EXTRACT() stops with the last character of the expression. If the ending position precedes the starting position, $EXTRACT() returns an empty string. If this argument is omitted, $EXTRACT() returns one character at most.

$EXTRACT() provides a tool for manipulating strings based on character positions.

For a mumps process started in UTF-mode, $EXTRACT interprets the string arguments as UTF-8 encoded. With VIEW “BADCHAR” enabled, $EXTRACT() produces a run-time error when it encounters a character in the reserved range of the Unicode standard, but it does not process the characters that fall after the span specified by the arguments. The parallel function of $EXTRACT() is $ZEXTRACT(). Use $ZEXTRACT() for byte-oriented operations. For more information, refer to “$ZExtract()”.

$EXTRACT() can be used on the left-hand side of the equal sign (=) of a SET command to set a substring of a string. This construct permits easy maintenance of individual pieces within a string. It can also be used to right justify a value padded with blank characters. For more information on SET $EXTRACT(), refer to “Set” in the Commands chapter.

Examples of $EXTRACT()

Example:

GTM>for i=0:1:3 write !,$extract("HI",i),"<"
<
H<
I<
<
GTM>

This loop displays the result of $EXTRACT(), specifying no ending character position and a beginning character position “before” first and second positions, and “after” the string.

Example:

GTM>For i=0:1:3 write !,$extract("HI",1,i),"<"
<
H<
HI<
HI<
GTM>

This loop displays the result of $EXTRACT() specifying a beginning character position of 1 and an ending character position “before, " first and second positions, and “after” the string.

Example:

GTM>zprint ^trim
trim(x)
    new i,j
    for i=1:1:$length(x) quit:" "'=$extract(x,i)
    for j=$length(x):-1:1 quit:" "'=$extract(x,j)
    quit $extract(x,i,j)
GTM>set str=" MUMPS "
GTM>write $length(str)
7
GTM>write $length($$^trim(str))
5
GTM>

This extrinsic function uses $EXTRACT() to remove extra leading and trailing spaces from its argument.