$Extract()

Returns a substring of a given string.

The format for the $EXTRACT function is:

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

$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.