REXX: Built in String Functions

String functions interrogate, compare, and manipulate character strings of data.

Some of the built-in function are listed below:

COPIES:
This function returns n copies of string concatenated together.

Syntax:    COPIES(string,n)

Examples:

COPIES('123',2)    -   /*   '123' */
COPIES('%',5)      -   /*   '%%%%%'   */

DELSTR:

This function returns length characters deleted from string, starting at n.

If length is not specified, all characters from n are deleted.

Syntax:  DELSTR(string, n, length)

Examples:

DELSTR('GreatIndia', 6)       /*Great*/
DELSTR('GreatIndia', 6,1)       /*Greatndia*/

INSERT:

This function will insert the characters new into target. All other parameters are optional. n specifies the location in target after which to insert new. The default for n is 0, which means to insert before the beginning of target.

Syntax:    INSERT(new, target, n, length, pad)

Examples:

INSERT('new','old')                 /*  'newold'             */
INSERT('new','old',2)              /*  'olnewd'             */
INSERT('new','old',2,5,'*')      /*  'olnew**d'         */
INSERT('new','old',7,4,'*')      /*  'old****new*'   */

OVERLAY:

This function will replace characters in target with characters from new. It will overlay target with new starting from position n in target.

If n is omitted, overlaying begins at position 1 in target. If length is specified, it is used to pad or truncate new.

If padding is required, the pad character specified by pad will be used. Otherwise, the default pad character of blank will be used.

Syntax: OVERLAY(new, target, n, length, pad)

Examples:

OVERLAY('abcd','1234efgh')                             /*   'abcdefgh'    */
OVERLAY('abcd','1234efgh',5)                          /*   '1234abcd'   */

OVERLAY('abcd','1234efgh',,6)                         /*   '1234 abcd'  */ 

OVERLAY('abcd','1234efgh',10,6,'*')                /*   '1234efgh*abcd**'   */

REVERSE:

This function returns a character string swapped end-over-end. The first character of string becomes the last and vice versa.

Syntax:   REVERSE(string)

Examples:

REVERSE('abcd')        returns 'dcba'
REVERSE('alla')          returns 'alla'


SUBSTR:

This function returns a substring of string starting at character n of length characters.

If length is not specified, the remainder of string is returned. If length is specified, it is used to truncate or pad the remainder of string.

The default pad character is a blank space.

SUBSTR('1234567',4)           returns '4567'
SUBSTR('1234567',4,2)        returns '45'
SUBSTR('1234567',6,3,'*')    returns '67*'

XRANGE:

This function returns a string of all one byte codes between and including a specified start and end character in a given string.

It can be useful in assigning entire alphabet to a variable.

Syntax:   XRANGE(start, end)

Examples:

XRANGE(a,d)       returns 'abcd'
XRANGE(A,D)     returns 'ABCD'

ARG:
This function can be used to determine the number of arguments passed, value of the argument and whether an argument exist or is omitted.

Syntax: ARG(n,option)

Examples:

Callrexx 'firstvalue'  ' '  'thirdvalue'

ARG()         returns 3
ARG(1)       returns 'firstvalue'
ARG(2)       returns ' '
ARG(3)       returns 'thirdvalue'
ARG(1,'e')   returns true

COMPARE:

This function compares two strings and returns 0 if they match. If strings are not equal, COMPARE returns the position of the first character that does not match.


COMPARE pads the shorter string with specified pad character, which is blank space by default.

Syntax:   COMPARE(string1, string2, pad)

Examples:

COMPARE('123','123')   returns 0   '123' = '123'
COMPARE('12 ','12')      returns 0   '12 '  = '12 '
COMPARE('12 ','12','-')  returns 3   '12 ' /= '12-'
COMPARE('12','123')     returns 3   '12'  /= '123'


LASTPOS:

This function returns the starting position of the last occurrence of the needle in haystack. If needle is not found in haystack, 0 is returned.

If start is not specified, the search begins at the end of haystack and continues left toward the beginning of haystack. If start is specified, searching commences at start and continues left toward the beginning of haystack.

Syntax: LASTPOS(needle,haystack,start)

Examples:

LASTPOS('23' , '12345 12345')    returns 8
LASTPOS('23' , '12345 12345',5) returns 2
LASTPOS('23' , '12345 12345',3) returns 0

LENGTH:

This function returns the length of the string passed to it.

Syntax: LENGTH(string)

Examples:

LENGTH('GreatIndia')    returns 10

DATATYPE:
This function is used to verify input data and can be used prevent errors. DATATYPE checks a string to the REXX definition of a string type. If only string specified, DATATYPE returns NUM if the string is a valid number. Otherwise, it returns CHAR.

Syntax:   DATATYPE(string,type)

Examples:

number = 10
IF DATATYPE(number) = 'NUM' then SAY 'valid number'
else SAY 'not a valid number, check the value in the variable number'

DATATYPE('aa1')   /* returns CHAR*/
DATATYPE(99)      /* returns NUM */

Type	Expansion	Description
A	Alphanumeric	Returns 1 if string contains only from range a-z,A-Z,0-9
B	Binary	Returns 1 if string contains only 0 or 1, or both
L	Lowercase	Returns 1 if string contains only from range a-z
M	Mixed	Returns 1 if string contains only from range a-z and A-Z
N	Number	Returns 1 if string is a valid number
S	Symbol	Returns 1 if string is a valid symbol
U	Uppercase	Returns 1 if string contains only from range A-Z
W	Whole	Returns 1 if string is a whole number
X	Hexadecimal	Returns 1 if string contains only from range a-z,A-Z,0-9 and blank when blanks appear only between pairs of hexadecimal characters.

POS:

This function returns the starting position of needle in haystack. If needle cannot be located in haystack, POS returns 0.

If start is not specified, the search commences at the start of haystack and continues right towards the end of haystack. If start is specified, searching commences at start and continues right towards the end of haystack.

The pos(needle, haystack) function is same as INDEX(haystack, needle) function.

Syntax:  POS(needle, haystack, start)

Examples:

POS('ab','abcdefg')    /*returns 1*/
POS('ab','abcdefg',2) /*returns 0 */
POS('x','abcdefg')     /*returns 0*/

SYMBOL:

This function interrogates the REXX variable pool to determine whether a variable has been set to a value.

It returns 'BAD' if the specified string is not a valid REXX symbol. 'VAR' if the string is a variable or 'LIT' for others.

Syntax:  SYMBOL(value)

Examples:

a='2'
SYMBOL('a')     Returns VAR
SYMBOL(a)       Returns LIT
SYMBOL('*')      Returns BAD

VERIFY:

This function verifies that a specified string only contains characters from a specified reference string by returning the position of the first character that is not in the reference, or 0 if the string is composed only of characters in the reference.

Also, this can determine the first character of the string that is in reference by using the MATCH option. A start position can also be defined.

Syntax: VERIFY(target, reference, option , start)

Examples:

VERIFY('I am hero','amhero')     Returns 1