Tests if one string is an abbreviation of another string. An abbreviation is a substring that starts at the beginning of a string. For example, 'auto' could be an abbreviation for 'automobile'.

result = ABBREV(string, abbreviation, length)

string is the string (for which abbreviation may be an abbreviation).

abbreviation is a possible abbreviation of string.

length is the minimum length that abbreviation must be in order to be considered as an abbreviation. If length is omitted, there is no restriction upon abbreviation's minimum length (and therefore an empty string would be considered an abbreviation for any other string).

1 if abbreviation is an abbreviation of string, or 0 if not.

ABBREV() is case sensitive, and leading/trailing spaces are not stripped off before the two strings are compared.

ABBREV('Foobar', 'Foo')

1

ABBREV('Foobar', 'Foo', 4)

0 /* 'Foo' isn't at least 4 chars */

ABBREV('Foobar', 'foo')

0 /* Different case - 'F' versus 'f' */

POS, WORDPOS, VERIFY

Returns a string formatted to fit centered within a certain number of characters. If necessary, the string's size is decreased to fit into that many characters, or pad characters are used to fill out the new string with the original string centered within the new string.

formatted = CENTER(string, length, padchar)

string is the original string (to format).

length is the desired length of the final string. If length is less than the size of the original string, then characters will be deleted from the front and end of the string in order to fit the desired length. If length is greater than the size of the original string, then the original string will be centered within the new string and padchar characters will be used to fill out the new string to the desired length. length must not be negative, nor have a fractional component -- it must be a positive whole number.

padchar is the character to use for padding (if the original string is not already >= the desired length). If padchar is omitted, the default is a space character.

A copy of the original string extended to the desired length, with the original string centered within the new string, and padchars filling out the new string.

The original string is not altered. Only the returned value from CENTER is formatted.

If length is an odd number, any extra padchar is placed on the right-hand side of the centered, original string.

CENTER('Foobar',10)

'  Foobar  '

CENTER('Foobar', 11)

'  Foobar   '

CENTER('Foobar', 3)

'oob'

CENTER('Foobar', 4)

'ooba'

CENTER('Foobar', 10, '*')

'**Foobar**'

JUSTIFY, EXPAND, SPACE, FORMAT, TRANSLATE, LEFT, RIGHT

Exchanges any occurence of one substring (within a given string) with another substring.

newstring = CHANGESTR(searchfor, string, exchange)

string is the original string (to exchange substrings within).

searchfor is which substring to search for (within string. If searchfor is an empty string, then no exchange is performed, and the original string is returned.

exchange is the substring to insert in place of searchfor, wherever searchfor occurs within string. If exchange is an empty string, then each occurence of searchfor is deleted without being replaced by anything.

A copy of the original string with all occurences of searchfor replaced with exchange.

The original string is not altered.

CHANGESTR('a', 'fred', 'c')

'fred'

CHANGESTR('', '', 'new string')

''

CHANGESTR('a', 'abcdef', 'x')

'xbcdef'

CHANGESTR('0', '0', '1')

'1'

CHANGESTR('a', 'def', 'xyz')

'def'

CHANGESTR('a', '', 'x')

''

CHANGESTR('', 'def', 'xyz')

'def'

CHANGESTR('abc', 'abcdef', 'xyz')

'xyzdef'

CHANGESTR('abcdefg', 'abcdef', 'xyz')

'abcdef'

CHANGESTR('abc', 'abcdefabccdabcd', 'z')

'zdefzcdzd'

TRANSLATE

Compares two strings for inequality, and returns the position where they differ.

result = COMPARE(string1, string2, padchar)

string1 and string2 is the two strings to be compared.

If one of the strings is shorter than the other, padchar is the character used to pad out the shorter string to the same length as the longer string. If padchar is omitted, then by default, the shorter string is padded with extra spaces.

0 if both strings are equal. If not equal, then the first position where the two strings are different is returned (where 1 is the first character in the strings).

COMPARE() is case-sensitive, so 'BLORT' does not equal 'blort'. Use TRANSLATE() to upper-case the strings prior to COMPARE(), if desired.

Leading and trailing spaces do matter, so ' blort ' does not equal 'blort'. Use STRIP() to removed leading/trailing space prior to COMPARE(), if desired.

COMPARE('FooBar', 'Foobar')

4

COMPARE('Foobar', 'Foobar')

0

COMPARE('Foobarrr', 'Fooba')

6

COMPARE('Foobarrr', 'Fooba', 'r')

0

POS, WORDPOS, ABBREV, COUNTSTR, LASTPOS, VERIFY

newstring = COPIES(string, total)

string is the original string (to append). If string is an empty string, then the resulting newstring is also an empty string.

total is a count of how many times to append string. total cannot be negative, nor have a fractional component -- it must be a positive whole number. If total is 0, an empty string is created.

The new string comprised of total instances of string appended.

COPIES('Foo', 3)

'FooFooFoo'

COPIES('*', 16)

'****************'

COPIES('Bar ', 2)

'Bar Bar '

COPIES('', 10000)

''

Counts how many occurences of a substring are within another string.

howmany = COUNTSTR(searchfor, string)

string is the original string (to search for searchfor within).

searchfor is which substring to search for (within string. If searchfor is an empty string, then 0 is returned to indicate no occurrences of searchfor within string.

A count of how many occurrences of searchfor appear within string.

COUNTSTR('', '')

0

COUNTSTR('a', 'abcdef')

1

COUNTSTR(0, 0)

1

COUNTSTR('a', 'def')

0

COUNTSTR('a', '')

0

COUNTSTR('', 'def')

0

COUNTSTR('abc', 'abcdef')

1

COUNTSTR('abcdefg', 'abcdef')

0

COUNTSTR('abc', 'abcdefabccdabcd')

3

COUNTSTR('aaa', 'aaaaaa')

2

Removes one or more characters from a string.

newstring = DELSTR(string, start, length)

string is the string to remove characters from.

start is which character number to start removing from, where 1 would be to start removing at the first character in the string. If there are less characters in the string than start, then no characters are removed.

length is the desired number of characters to remove (within string), starting at (ie, including) the start character. If length is omitted, then the default is to remove all character from the start character to the end of the string. length cannot be negative, nor have a fractional component -- it must be a positive whole number.

A copy of the original string without the removed characters.

It is not an error if start or length (or a combination of them) refers to more characters than string actually contains.

The original string is not altered. Only the returned value from DELSTR has characters removed.

DELSTR('Foobar', 3)

'Foo'

DELSTR('Foobar', 3, 2)

'Foor'

DELSTR('Foobar', 3, 4)

'Foo'

DELSTR('Foobar', 7)

'Foobar'

DELWORD, OVERLAY, LEFT

Replaces tab characters with spaces, or vice versa.

newstring = EXPAND(string, options, tabwidth1, tabwidth2, ...)

string is the string to replace characters within.

options is the desired operation. It is one of the following:

Option	Meaning
'S'	Replace each tab character with an appropriate number of spaces based upon the tabwidth args.
'T'	Replace space characters with a tab character based upon the tabwidth args.

If omitted, options defaults to 'S'.

tabwidth1 is the desired width of the first tab stop. For example, a value of '8' would put the first tab stop at the eighth character. If omitted, tabwidth1 defaults to 8. There may be more tabwidth arguments supplied. For example, if tabwidth2 is supplied, then this sets the width of the second tab stop. For example, a value of '8' would effectively put the second tab stop at the sixteenth character. If there are more spaces/tabs to be replaced than there are tabwidths specified, then the value of the last tabwidth is used for all subsequent replacements.

A copy of the original string with the space/tab characters replaced.

The first character in string is presumed to be at a tabstop.

The original string is not altered. Only the returned value from EXPAND has characters replaced.

Some interpreters do not support this function.

EXPAND('   Foo   bar', 'T', 3)

'09'X || 'Foo' || '09'X || 'bar'

EXPAND('   Foo bar', 'T')

'   Foo bar'

EXPAND(' Foo   bar', 'T', 3)

' Foo' || '09'X || ' bar'

EXPAND('        Foo   bar', 'T')

'09'X || 'Foo   bar'

EXPAND('       Foo   bar ', 'T', 3, 3, 6)

'0909'X || ' Foo' || '09'X || ' bar '

JUSTIFY, CENTER, SPACE, FORMAT, TRANSLATE

Inserts a substring into another string.

newstring = INSERT(insert, string, position, length, padchar)

insert is the substring to be inserted (into string).

string is the string into which insert is inserted.

position is the desired character position (within string) after which to insert insert. A position of 0 would cause insert to be inserted before the first character in string (ie, at the very start). A position of 1 would cause insert to be inserted after the first character in string (ie, at the very start). If position is greater than the number of characters in string, then insert will be inserted after the last character of string. If position is omitted, then it defaults to 0.

length is the desired length for insert. If insert is larger, then characters will be deleted from the end of the string in order to fit the desired length. If insert is smaller, then it is padded out with padchar characters at the end to fit the desired length. length must not be negative, nor have a fractional component -- it must be a positive whole number. If length is omitted, then no truncation nor padding is performed upon insert.

padchar is the character to use for padding (if the insert is not already >= length). If padchar is omitted, the default is a space character.

A copy of the original string with insert inserted into it.

The original string is not altered. Only the returned value from INSERT has the inserted substring.

INSERT('first', 'SECOND')

'SECONDfirst'

INSERT('first', 'SECOND', 3)

'fiSECONDrst'

INSERT('first', 'SECOND', 3, 10)

'fiSECOND rst'

INSERT('first', 'SECOND', 3, 10, '*')

'fiSECOND****rst'

INSERT('first', 'SECOND', 3, 4)

'fiSECOrst'

INSERT('first', 'SECOND', 8)

'first SECOND'

JUSTIFY, SPACE, COPIES, CENTER, OVERLAY

Finds the last occurrence of a substring within another string.

where = LASTPOS(searchfor, string, start)

searchfor is which substring to search for (within string. If searchfor is an empty string, then 0 is returned to indicate no occurrences of searchfor within string.

string is the original string (to search for searchfor within).

start is which character position to start the backward search from, where 1 would be to start searching backwards at the first character in string. If omitted, the default is to start searching from the last character. start must not be negative, nor have a fractional component -- it must be a positive whole number.

If searchfor is found, then LASTPOS() returns the character position where the last occurrence of searchfor occurs within string (where 1 is the first character within string). If searchfor is not found, then LASTPOS() returns 0.

LASTPOS('be', 'to be or not to be')

17

LASTPOS('to', 'to be or not to be', 10)

3

LASTPOS('is', 'to be or not to be')

0

WORDPOS, POS, COUNTSTR, VERIFY

Excerpts one or more characters from the left-hand side of a string.

excerpt = LEFT(string, length, padchar)

string is the original string (from which to excerpt characters).

length is the number of characters to be excerpted. If length is 0, no characters are excerpted. If length is greater than the number of characters in string, then the excerpt is padded out with padchar characters to the desired length.

padchar is the character to use for padding (if the original string is not >= length). If padchar is omitted, the default is a space character.

A string containing the excerpted characters.

The original string is not altered.

LEFT('Foo bar', 5)

'Foo b'

LEFT('Foo bar', 3)

'Foo'

LEFT('Foo bar', 10)

'Foo bar   '

LEFT('Foo bar', 10, '*')

'Foo bar***'

SUBSTR, RIGHT, SUBWORD

Counts the number of characters in a string.

howmany = LENGTH(string)

string is the string (whose length is to be calculated).

A count of how many characters are in the string.

Leading and trailing spaces are counted. You may wish to use STRIP first to trim those spaces.

LENGTH('')

0

LENGTH('Foo')

3

LENGTH('Foo bar')

7

LENGTH(' foo bar ')

10

Overlays a substring into another string. OVERLAY() differs from INSERT() in that OVERLAY() overwrites characters in the string.

newstring = OVERLAY(overlay, string, position, length, padchar)

overlay is the substring to be inserted (into string).

string is the string into which overlay is overlaid.

position is the desired character position (within string) at which to overlay overlay. A position of 1 would cause overlay to be overlaid at the first character in string (ie, at the very start). If position is greater than the number of characters in string, then the new string will be padded out with padchar characters and then overlay will be inserted after those pad characters. If position is omitted, then it defaults to 1.

length is the desired length for overlay. If overlay is larger, then characters will be deleted from the end in order to fit the desired length. If overlay is smaller, then it is padded out with padchar characters at the end to fit the desired length. length must not be negative, nor have a fractional component -- it must be a positive whole number. If length is omitted, then no truncation nor padding is performed upon overlay.

padchar is the character to use for padding (if the overlay is not already >= length). If padchar is omitted, the default is a space character.

A copy of the original string with overlay overlaid in it.

The original string is not altered. Only the returned value from OVERLAY has the overlaid substring.

OVERLAY('NEW', 'old-value')

'NEW-value'

OVERLAY('NEW', 'old-value', 4)

'oldNEWlue'

OVERLAY('NEW', 'old-value', 4, 5)

'oldNEW  e'

OVERLAY('NEW', 'old-value', 4, 5, ‘*’)

'oldNEW**e'

OVERLAY('NEW', 'old-value', 4, 2)

'oldNEalue'

OVERLAY('NEW', 'old-value', 8)

'old-valuNEW'

OVERLAY('NEW', 'old-value', 11)

'old-value NEW'

OVERLAY('NEW', 'old-value', 4, 2)

'oldNEalue'

OVERLAY('NEW', 'old-value', 9)

'old-valuNEW'

JUSTIFY, SPACE, COPIES, CENTER, INSERT

Finds the first occurrence of a substring within another string.

where = POS(searchfor, string, start)

searchfor is which substring to search for (within string. If searchfor is an empty string, then 0 is returned to indicate no occurrences of searchfor within string.

string is the original string (to search for searchfor within).

start is which character position to start the search from, where 1 would be to start searching at the first character in string. If omitted, the default is to start searching from the first character. start must not be negative, nor have a fractional component -- it must be a positive whole number.

If searchfor is found, then POS() returns the character position where the first occurrence of searchfor occurs within string (where 1 is the first character within string). If searchfor is not found, then POS() returns 0.

LASTPOS('be', 'to be or not to be')

3

LASTPOS('to', 'to be or not to be', 10)

17

LASTPOS('to', 'to be or not to be', 18)

0

LASTPOS('is', 'to be or not to be')

0

WORDPOS, LASTPOS, COUNTSTR, VERIFY

Reverses the order of characters in a string.

newstring = REVERSE(string)

string whose characters are to be reversed.

A copy of the original string with the order of its characters reversed.

The original string is not altered. Only the return value of REVERSE has its characters reversed.

REVERSE('FooBar')

'raBooF'

REVERSE(' Foo Bar')

'raB ooF '

REVERSE('3.14159')

'95141.3'

Excerpts one or more characters from the right-hand side of a string.

excerpt = RIGHT(string, length, padchar)

string is the original string (from which to excerpt characters).

length is the number of characters to be excerpted. If length is 0, no characters are excerpted. If length is greater than the number of characters in string, then the excerpt is padded out on the left with padchar characters to the desired length.

padchar is the character to use for padding (if the original string is not >= length). If padchar is omitted, the default is a space character.

A string containing the excerpted characters.

The original string is not altered.

RIGHT('Foo bar', 5)

'o bar'

RIGHT('Foo bar', 4)

' bar'

RIGHT('Foo bar', 10)

'   Foo bar'

RIGHT('Foo bar', 10, '*')

'***Foo bar'

SUBSTR, LEFT, SUBWORD

Removes leading and/or trailing space (or other) characters from a string.

newstring = STRIP(string, option, padchar)

string whose leading and trailing space characters are to be removed.

padchar is the character to strip. If padchar is omitted, the default is a space character.

option determines whether padchars are stripped from the beginning and/or end of string. It must be one of the following:

Option	Meaning
L	(Leading) Only leading characters are stripped. Trailing characters are not.
T	(Trailing) Only trailing characters are stripped. Leading characters are not.
B	(Both) Both leading and trailing characters are stripped.

A copy of the original string with its leading and trailing space characters removed.

The original string is not altered. Only the return value of STRIP has its leading/trailing padchars removed.

This removes only those padchars appearing at the front or end of the string. To delete padchars within the string, use SPACE().

When padchar is omitted, Reginald strips TAB characters as well as space characters. Other interpreters may strip only space characters (ie, not TAB).

STRIP('   FooBar')

'FooBar'

STRIP(' Foo Bar ')

'Foo Bar'

STRIP(' Foo Bar ', 'L')

'Foo Bar '

STRIP('  3.14159  ')

'3.14159'

STRIP('*** Foo *** Bar ***', ,'*')

' Foo *** Bar '

SPACE, TRANSLATE

Excerpts one or more characters from a string, and returns that excerpt.

excerpt = SUBSTR(string, start, length, padchar)

string is the original string (from which to excerpt characters).

start is which character position to start the excerpt from, where 1 would be to start the excerpt at the first character in the string. If there are less characters in the string than start, then an empty string is returned. start cannot be 0 or negative, nor have a fractional component -- it must be a positive whole number.

length is the number of characters to be excerpted, starting at the character position start. If length is omitted, the default is to excerpt all characters from start to the end of the string. If length is 0, no characters are excerpted. length cannot be negative, nor have a fractional component -- it must be a positive integer.

padchar is the character to use for padding (if the original string is not >= length + start). If padchar is omitted, the default is a space character.

A string containing the excerpted characters.

Any leading or trailing spaces are not trimmed from the excerpt.

It is not an error if start or length (or a combination of them) refers to more characters than string actually contains.

The original string is not altered.

SUBSTR('Foo bar', 3)

'o bar'

SUBSTR('Foo bar', 3, 3)

'o b'

SUBSTR('Foo bar', 4, 6)

' bar  '

SUBSTR('Foo bar', 4, 6, '*')

' bar**'

SUBSTR('Foo bar', 9, 4, '*')

'****'

SUBWORD, LEFT, RIGHT

Translates characters in a string to other characters, or makes a string uppercase.

newstring = TRANSLATE(string, tableout, tablein, padchar)

string is the original string (to translate).

tablein is a string containing upto 256 characters, representing characters that you wish translated to the respective characters in tableout.

If one or both of the tables are specified, each character in string that exists in tablein is translated to the character in tableout that occupies the same position as the tablein character. Characters in string which are not found in tablein are left unchanged.

If omitted, tablein defaults to all 256 characters of the computer's default character set. If omitted, tableout defaults to an empty set.

If tableout is larger than tablein, the extra entries are ignored. If smaller than tablein, tableout is padded with padchar characters to the same length as tablein. If padchar is omitted, the default padding is space characters.

If both of the tables are omitted, TRANSLATE() upper-cases string.

If a character occurs more than once in tablein, only the first occurrence will matter.

A copy of the original string with each tablein character translated to its respective tableout's character.

The original string is not altered. Only the return value of TRANSLATE has its characters translated.

TRANSLATE('FooBar')

'FOOBAR'

TRANSLATE('FooBar', 'ABFORabfor', 'abforABFOR')

'fOObAR'

TRANSLATE('FooBar', 'abfor')

'F  B  '

TRANSLATE('FooBar', 'abfor', , '#')

'F##B##'

CHANGESTR

Tests if any characters of one string also occur in another string.

where = VERIFY(string, lookfor, option, start)

string is the string to search (for lookfor).

start is which character number to start searching from, where 1 would be to start searching at the first character in the string. If there are less characters in the string than start, then a 0 is returned to indicate that no characters in lookfor matched.

option must be one of:

Option	Meaning
N	(Nomatch) Return the position of the first character in string that isn't found in lookfor, or 0 if all of the characters in string also exist in lookfor.
M	(Match) Return the position of the first character in string that also exists in lookfor, or 0 none of the characters in string also exist in lookfor.

If omitted, option defaults to 'N'.

A character position (where 1 is the first character in string).

It is not an error if start refers to more characters than string actually contains.

VERIFY('foobar', 'barfo')

2

VERIFY('foobar', 'barfo', 'M')

2

VERIFY('foobar', 'fob', 'N')

5

VERIFY('foobar', 'barf', 'N', 3)

3

VERIFY('foobar', 'barf', 'N', 4)

0

Creates a range of characters between a given start character and end character. The range of characters is produced from the computer's character set.

newstring = XRANGE(start, end)

start is which character to start from. If omitted, the default is to start from character 0 ('00'x).

end is which character to end at. If omitted, the default is to end at character 255 ('ff'x).

A string that consists of all the characters from start through end, inclusive.

The actual representation of the output from XRANGE() depends on the character set used by your computer.

If the value of start is larger than the value of end, the output will wrap around from ‘ff’x to ‘00’x. If start or end is not a string containing exactly one character, this raises a SYNTAX error.

XRANGE('A', 'J')

'ABCDEFGHIJ'

XRANGE('FC'x)

'FCFDFEFF'x

XRANGE(, '05'x)

'000102030405'x

XRANGE('FD'x, '04'x)

'FDFEFF0001020304'x