Rexx Built in Functions - adesutherland/CREXX GitHub Wiki
The built-in methods (here an implicit first argument of type rexx is assumed)
abbrev(info [,length])
returns 1 if info is equal to the leading characters of string and info is not less than the minimum length, length; 0 is returned if either of these conditions is not met. length must be a non-negative whole number; the default is the length of info. Examples:
'Print'.abbrev('Pri') == 1
'PRINT'.abbrev('Pri') == 0
'PRINT'.abbrev('PRI',4) == 0
'PRINT'.abbrev('PRY') == 0
'PRINT'.abbrev('') == 1
'PRINT'.abbrev('',1) == 0
**Note:** A null string will always match if a length of 0 (or the
default) is used. This allows a default keyword to be selected
automatically if desired. **Example:**
say 'Enter option:'; option=ask
select /* keyword1 is to be the default */
when 'keyword1'.abbrev(option) then ...
when 'keyword2'.abbrev(option) then ...
...
otherwise ...
end
abs()
returns the absolute value of string, which must be a number. Any sign is removed from the number, and it is then formatted by adding zero with a digits setting that is either nine or, if greater, the number of digits in the mantissa of the number (excluding leading insignificant zeros). Scientific notation is used, if necessary.
**Examples:**
'12.3'.abs == 12.3
' -0.307'.abs == 0.307
'123.45E+16'.abs == 1.2345E+18
'- 1234567.7654321'.abs == 1234567.7654321
b2d([n])
Binary to decimal. Converts string, a string of at least one binary (0 and/or 1) digits, to an equivalent string of decimal characters (a number), without rounding. The returned string will use digits, and will not include any blanks. If the number of binary digits in the string is not a multiple of four, then up to three '0' digits will be added on the left before conversion to make a total that is a multiple of four. If string is the null string, 0 is returned. If n is not specified, string is taken to be an unsigned number.
**Examples:**
'01110'.b2d == 14
'10000001'.b2d == 129
'111110000001'.b2d == 3969
'1111111110000001'.b2d == 65409
'1100011011110000'.b2d == 50928
If n is specified, string is taken as a signed number expressed in n
binary characters. If the most significant (left-most) bit is zero
then the number is positive; otherwise it is a negative number in
twos-complement form. In both cases it is converted to a NetRexx
number which may, therefore, be negative. If n is 0, 0 is always
returned.
If necessary, string is padded on the left with '0' characters
(note, not "signextended"), or truncated on the left, to length n
characters; (that is, as though string.right(n, '0') had been
executed.)
**Examples:**
'10000001'.b2d(8) == -127
'10000001'.b2d(16) == 129
'1111000010000001'.b2d(16) == -3967
'1111000010000001'.b2d(12) == 129
'1111000010000001'.b2d(8) == -127
'1111000010000001'.b2d(4) == 1
'0000000000110001'.b2d(0) == 0
b2x()
Binary to hexadecimal. Converts string, a string of at least one binary (0 and/or 1) digits, to an equivalent string of hexadecimal characters. The returned string will use uppercase Roman letters for the values A-F, and will not include any blanks. If the number of binary digits in the string is not a multiple of four, then up to three '0' digits will be added on the left before conversion to make a total that is a multiple of four.
**Examples:**
'11000011'.b2x == 'C3'
'10111'.b2x == '17'
'0101'.b2x == '5'
'101'.b2x == '5'
'111110000'.b2x == '1F0'
center(length [,pad])
*or*
centre(length [,pad])
returns a string of length *length* with *string* centered in it,
with *pad* characters added as necessary to make up the required
length. *length* must be a non-negative whole number. The default
*pad* character is blank. If the string is longer than *length*, it
will be truncated at both ends to fit. If an odd number of
characters are truncated or added, the right hand end loses or gains
one more character than the left hand end.
**Examples:**
'ABC'.centre(7) == ' ABC '
'ABC'.center(8,'-') == '--ABC---'
'The blue sky'.centre(8) == 'e blue s'
'The blue sky'.center(7) == 'e blue '
**Note:** This method may be called either **centre** or **center**,
which avoids difficulties due to the difference between the British
and American spellings.
changestr(needle, new)
returns a copy of string in which each occurrence of the needle string is replaced by the new string. Each unique (non-overlapping) occurrence of the needle string is changed, searching from left to right and starting from the first (leftmost) position in string. Only the original string is searched for the needle, and each character in string can only be included in one match of the needle.
If the *needle* is the null string, the result is a copy of
*string*, unchanged.
**Examples:**
'elephant'.changestr('e','X') == 'XlXphant'
'elephant'.changestr('ph','X') == 'eleXant'
'elephant'.changestr('ph','hph') == 'elehphant'
'elephant'.changestr('e','') == 'lphant'
'elephant'.changestr('','!!') == 'elephant'
The **countstr** method (see page ) can be used to count the number
of changes that could be made to a string in this fashion.
compare(target [,pad])
:
returns 0 if *string* and *target* are the same. If they are not,
the returned number is positive and is the position of the first
character that is not the same in both strings. If one string is
shorter than the other, one or more *pad* characters are added on
the right to make it the same length for the comparison. The default
*pad* character is a blank.
**Examples:**
'abc'.compare('abc') == 0
'abc'.compare('ak') == 2
'ab '.compare('ab') == 0
'ab '.compare('ab',' ') == 0
'ab '.compare('ab','x') == 3
'ab-- '.compare('ab','-') == 5
copies(n)
returns n directly concatenated copies of string. n must be positive or 0; if 0, the null string is returned.
**Examples:**
'abc'.copies(3) == 'abcabcabc'
'abc'.copies(0) == ''
''.copies(2) == ''
copyindexed(sub)
copies the collection of indexed sub-values (see page ) of sub into the collection associated with string, and returns the modified string. The resulting collection is the union of the two collections (that is, it contains the indexes and their values from both collections). If a given index exists in both collections then the sub-value of string for that index is replaced by the sub-value from sub.
The non-indexed value of *string* is not affected.
**Example:** Following the instructions:
foo='def'
foo['a']=1
foo['b']=2
bar='ghi'
bar['b']='B'
bar['c']='C'
merged=foo.copyIndexed(bar)
then:
merged['a'] == '1'
merged['b'] == 'B'
merged['c'] == 'C'
merged['d'] == 'def'
countstr(needle)
returns the count of non-overlapping occurrences of the needle string in string, searching from left to right and starting from the first (leftmost) position in string.
If the *needle* is the null string, **0** is returned.
**Examples:**
'elephant'.countstr('e') == '2'
'elephant'.countstr('ph') == '1'
'elephant'.countstr('') == '0'
The **changestr** method (see page ) can be used to change
occurrences of *needle* to some other string.
c2d()
Coded character to decimal. Converts the encoding of the character
in *string* (which must be exactly one character) to its decimal
representation. The returned string will be a non-negative number
that represents the encoding of the character and will not include
any sign, blanks, insignificant leading zeros, or decimal part.
**Examples:**
'M'.c2d == '77' -- ASCII or Unicode
'7'.c2d == '247' -- EBCDIC
'\textbackslash{}r'.c2d == '13' -- ASCII or Unicode
'\textbackslash{}0'.c2d == '0'
The **c2x** method (see page ) can be used to convert the encoding
of a character to a hexadecimal representation.
c2x()
Coded character to hexadecimal. Converts the encoding of the
character in *string* (which must be exactly one character) to its
hexadecimal representation (unpacks). The returned string will use
uppercase Roman letters for the values A-F, and will not include any
blanks. Insignificant leading zeros are removed.
**Examples:**
'M'.c2x == '4D' -- ASCII or Unicode
'7'.c2x == 'F7' -- EBCDIC
'\textbackslash{}r'.c2x == 'D' -- ASCII or Unicode
'\textbackslash{}0'.c2x == '0'
The **c2d** method (see page ) can be used to convert the encoding
of a character to a decimal number.
datatype(option)
returns 1 if *string* matches the description requested with the
*option*, or 0 otherwise. If *string* is the null string, 0 is
always returned.
Only the first character of *option* is significant, and it may be
in either uppercase or lowercase. The following *option* characters
are recognized:
A
: (Alphanumeric); returns 1
if *string* only contains characters from the ranges \"a-z\",
\"A-Z\", and \"0-9\".
B
: (Binary); returns 1 if
*string* only contains the characters \"0\" and/or \"1\".
D
: (Digits); returns 1 if
*string* only contains characters from the range \"0-9\".
L
: (Lowercase); returns 1 if
*string* only contains characters from the range \"a-z\".
M
: (Mixed case); returns 1 if
*string* only contains characters from the ranges \"a-z\" and
\"A-Z\".
N
: (Number); returns 1 if
*string* is a syntactically valid number that could be added to
**'0'** without error,
S
: (Symbol); returns 1 if
*string* only contains characters that are valid in non-numeric
symbols (the alphanumeric characters and underscore), and does
not start with a digit. Note that both uppercase and lowercase
letters are permitted.
U
: (Uppercase); returns 1 if
*string* only contains characters from the range \"A-Z\".
W
: (Whole Number); returns 1
if *string* is a syntactically valid number that can be added to
**'0'** without error, and whose decimal part after that
addition, with no rounding, is zero.
X
: (heXadecimal); returns 1 if
*string* only contains characters from the ranges \"a-f\",
\"A-F\", and \"0-9\".
**Examples:**
'101'.datatype('B') == 1
'12.3'.datatype('D') == 0
'12.3'.datatype('N') == 1
'12.3'.datatype('W') == 0
'LaArca'.datatype('M') == 1
''.datatype('M') == 0
'Llanes'.datatype('L') == 0
'3 d'.datatype('s') == 0
'BCd3'.datatype('X') == 1
'BCgd3'.datatype('X') == 0
**Note:** The **datatype** method tests the meaning of the
characters in a string, independent of the encoding of those
characters. Extra letters and Extra digits cause **datatype** to
return 0 except for the number tests (\"**N**\" and \"**W**\"),
which treat extra digits whose value is in the range 0-9 as though
they were the corresponding Arabic numeral.
date()
: see page
delstr(n [,length])
returns a copy of *string* with the sub-string of *string* that
begins at the *nth* character, and is of length *length* characters,
deleted. If *length* is not specified, or is greater than the number
of characters from *n* to the end of the string, the rest of the
string is deleted (including the *nth* character). *length* must be
a non-negative whole number, and *n* must be a positive whole
number. If *n* is greater than the length of *string*, the string is
returned unchanged.
**Examples:**
'abcd'.delstr(3) == 'ab'
'abcde'.delstr(3,2) == 'abe'
'abcde'.delstr(6) == 'abcde'
delword(n [,length
returns a copy of *string* with the sub-string of *string* that
starts at the *nth* word, and is of length *length* blank-delimited
words, deleted. If *length* is not specified, or is greater than
number of remaining words in the string, it defaults to be the
remaining words in the string (including the *nth* word). *length*
must be a non-negative whole number, and *n* must be a positive
whole number. If *n* is greater than the number of words in
*string*, the string is returned unchanged. The string deleted
includes any blanks following the final word involved, but none of
the blanks preceding the first word involved.
**Examples:**
'Now is the time'.delword(2,2) == 'Now time'
'Now is the time '.delword(3) == 'Now is '
'Now time'.delword(5) == 'Now time'
d2b([n])
Decimal to binary. Returns a
string of binary characters of length as needed or of length n,
which is the binary representation of the decimal number. The
returned string will use 0 and 1 characters for binary values.
string must be a whole number, and must be non-negative unless n is
specified, or an error will result. If n is not specified, the
length of the result returned is such that there are no leading 0
characters, unless string was equal to 0 (in which case '0' is
returned).
If n is specified it is the length of the final result in
characters; that is, after conversion the input string will be
sign-extended to the required length (negative numbers are converted
assuming twos-complement form). If the number is too big to fit into
n characters, it will be truncated on the left. n must be a
nonnegative whole number.
**Examples:**
'0'.d2b == 0
'9'.d2b == 1001
'19'.d2b == 10011
'129'.d2b == 10000001
'129'.d2b(1) == 1
'129'.d2b(8) == 10000001
'127'.d2b(12) == 000001111111
'129'.d2b(16) == 0000000010000001
'257'.d2b(8) == 00000001
'-127'.d2b(8) == 10000001
'-127'.d2b(16) == 1111111110000001
'12'.d2b(0) ==
d2c()
Decimal to coded character. Converts the string (a number) to a single character, where the number is used as the encoding of the character.
*string* must be a non-negative whole number. An error results if
the encoding described does not produce a valid character for the
implementation (for example, if it has more significant bits than
the implementation's encoding for characters).
**Examples:**
'77'.d2c == 'M' -- ASCII or Unicode
'+77'.d2c == 'M' -- ASCII or Unicode
'247'.d2c == '7' -- EBCDIC
'0'.d2c == '\textbackslash 0'
d2x([n
Decimal to hexadecimal. Returns a string of hexadecimal characters
of length as needed or of length *n*, which is the hexadecimal
(unpacked) representation of the decimal number. The returned string
will use uppercase Roman letters for the values A-F, and will not
include any blanks. *string* must be a whole number, and must be
non-negative unless *n* is specified, or an error will result. If
*n* is not specified, the length of the result returned is such that
there are no leading 0 characters, unless *string* was equal to 0
(in which case **'0'** is returned).
If *n* is specified it is the length of the final result in
characters; that is, after conversion the input string will be
sign-extended to the required length (negative numbers are converted
assuming twos-complement form). If the number is too big to fit into
*n* characters, it will be truncated on the left. *n* must be a
non-negative whole number.
**Examples:**
'9'.d2x == '9'
'129'.d2x == '81'
'129'.d2x(1) == '1'
'129'.d2x(2) == '81'
'127'.d2x(3) == '07F'
'129'.d2x(4) == '0081'
'257'.d2x(2) == '01'
'-127'.d2x(2) == '81'
'-127'.d2x(4) == 'FF81'
'12'.d2x(0) == ''
exists(index)
returns 1 if *index* names a sub-value (see page ) of *string* that
has explicitly been assigned a value, or 0 otherwise.
**Example:** Following the instructions:
vowel=0
vowel['a']=1
vowel['b']=1
vowel['b']=null -- drops previous assignment
then:
vowel.exists('a') == '1'
vowel.exists('b') == '0'
vowel.exists('c') == '0'
format([before [,after
formats (lays out) *string*, which must be a number.
The number, *string*, is first formatted by adding zero with a
digits setting that is either nine or, if greater, the number of
digits in the mantissa of the number (excluding leading
insignificant zeros). If no arguments are given, the result is
precisely that of this operation.
The arguments *before* and *after* may be specified to control the
number of characters to be used for the integer part and decimal
part of the result respectively. If either of these is omitted (with
no arguments specified to its right), or is **null**, the number of
characters used will be as many as are needed for that part.
*before* must be a positive number; if it is larger than is needed
to contain the integer part, that part is padded on the left with
blanks to the requested length. If *before* is not large enough to
contain the integer part of the number (including the sign, for
negative numbers), an error results.
*after* must be a non-negative number; if it is not the same size as
the decimal part of the number, the number will be rounded (or
extended with zeros) to fit. Specifying 0 for *after* will cause the
number to be rounded to an integer (that is, it will have no decimal
part or decimal point).
**Examples:**
' - 12.73'.format == '-12.73'
'0.000'.format == '0'
'3'.format(4) == ' 3'
'1.73'.format(4,0) == ' 2'
'1.73'.format(4,3) == ' 1.730'
'-.76'.format(4,1) == ' -0.8'
'3.03'.format(4) == ' 3.03'
' - 12.73'.format(null,4) == '-12.7300'
Further arguments may be passed to the method to control the use of
exponential notation. The full syntax of the method is then:
The first two arguments are as already described. The other three
(*explaces*, *exdigits*, and *exform*) control the exponent part of
the result. The default for any of the arguments may be selected by
omitting them (if there are no arguments to be specified to their
right) or by using the value **null**.
*explaces* must be a positive number; it sets the number of places
(digits after the sign of the exponent) to be used for any exponent
part, the default being to use as many as are needed. If *explaces*
is specified and is not large enough to contain the exponent, an
error results. If *explaces* is specified and the exponent will be
0, then *explaces*+2 blanks are supplied for the exponent part of
the result.
*exdigits* sets the trigger point for use of exponential notation.
If, after the first formatting, the number of places needed before
the decimal point exceeds *exdigits*, or if the absolute value of
the result is less than **0.000001**, then exponential form will be
used, provided that *exdigits* was specified. When *exdigits* is not
specified, exponential notation will never be used. The current
setting of may be used for *exdigits* by specifying the special word
**digits** (see page ) . If 0 is specified for *exdigits*,
exponential notation is always used unless the exponent would be 0.
*exform* sets the form for exponential notation (if needed).
*exform* may be either **'Scientific'** (the default) or
**'Engineering'**. Only the first character of *exform* is
significant and it may be in uppercase or in lowercase. The current
setting of may be used by specifying the special word **form** (see
page ) . If engineering form is in effect, up to three digits (plus
sign) may be needed for the integer part of the result (*before*).
**Examples:**
'12345.73'.format(null,null,2,2) == '1.234573E+04'
'12345.73'.format(null,3,null,0) == '1.235E+4'
'1.234573'.format(null,3,null,0) == '1.235'
'123.45'.format(null,3,2,0) == '1.235E+02'
'1234.5'.format(null,3,2,0,'e') == '1.235E+03'
'1.2345'.format(null,3,2,0) == '1.235 '
'12345.73'.format(null,null,3,6) == '12345.73 '
'12345e+5'.format(null,3) == '1234500000.000'
**Implementation minimum:** If exponents are supported in an
implementation, then they must be supported for exponents whose
absolute value is at least as large as the largest number that can
be expressed as an exact integer in default precision, *i.e.*,
999999999. Therefore, values for *explaces* of up to 9 should also
be supported.
insert(new [,n [,length [,pad]]])
inserts the string *new*, padded or truncated to length *length*,
into a copy of the target *string* after the *nth* character; the
string with any inserts is returned. *length* and *n* must be a
non-negative whole numbers. If *n* is greater than the length of the
target string, padding is added before the *new* string also. The
default value for *n* is 0, which means insert before the beginning
of the string. The default value for *length* is the length of
*new*. The default *pad* character is a blank.
**Examples:**
'abc'.insert('123') == '123abc'
'abcdef'.insert(' ',3) == 'abc def'
'abc'.insert('123',5,6) == 'abc 123 '
'abc'.insert('123',5,6,'+') == 'abc++123+++'
'abc'.insert('123',0,5,'-') == '123--abc'
lastpos(needle [,start])
returns the position of the last occurrence of the string needle in string (the "haystack"), searching from right to left. If the string needle is not found, or is the null string, 0 is returned. By default the search starts at the last character of string and scans backwards. This may be overridden by specifying start, the point at which to start the backwards scan. start must be a positive whole number, and defaults to the value string**.length** if larger than that value or if not specified (with a minimum default value of one).
**Examples:**
'abc def ghi'.lastpos(' ') == 8
'abc def ghi'.lastpos(' ',7) == 4
'abcdefghi'.lastpos(' ') == 0
'abcdefghi'.lastpos('cd') == 3
''.lastpos('?') == 0
left(length [,pad])
returns a string of length length containing the left-most length characters of string. The string is padded with pad characters (or truncated) on the right as needed. The default pad character is a blank. length must be a non-negative whole number. This method is exactly equivalent to string**.substr(1**, length [, pad]).
**Examples:**
'abc d'.left(8) == 'abc d '
'abc d'.left(8,'.') == 'abc d...'
'abc defg'.left(6) == 'abc de'
length()
returns the number of characters in string.
**Examples:**
'abcdefgh'.length == 8
''.length == 0
lower([n [,length]
returns a copy of *string* with any uppercase characters in the
sub-string of *string* that begins at the *nth* character, and is of
length *length* characters, replaced by their lowercase equivalent.
*n* must be a positive whole number, and defaults to 1 (the first
character in *string*). If *n* is greater than the length of
*string*, the string is returned unchanged.
*length* must be a non-negative whole number. If *length* is not
specified, or is greater than the number of characters from *n* to
the end of the string, the rest of the string (including the *nth*
character) is assumed.
**Examples:**
'SumA'.lower == 'suma'
'SumA'.lower(2) == 'Suma'
'SuMB'.lower(1,1) == 'suMB'
'SUMB'.lower(2,2) == 'SumB'
''.lower == ''
max(number)
returns the larger of *string* and *number*, which must both be
numbers. If they compare equal (that is, when subtracted, the result
is 0), then *string* is selected for the result.
The comparison is effected using a numerical comparison with a
digits setting that is either nine or, if greater, the larger of the
number of digits in the mantissas of the two numbers (excluding
leading insignificant zeros).
The selected result is formatted by adding zero to the selected
number with a digits setting that is either nine or, if greater, the
number of digits in the mantissa of the number (excluding leading
insignificant zeros). Scientific notation is used, if necessary.
**Examples:**
0.max(1) ==1
'-1'.max(1) ==1
'+1'.max(-1) ==1
'1.0'.max(1.00) =='1.0'
'1.00'.max(1.0) =='1.00'
'123456700000'.max(1234567E+5) == '123456700000'
'1234567E+5'.max('123456700000') == '1.234567E+11'
min(number)
returns the smaller of *string* and *number*, which must both be
numbers. If they compare equal (that is, when subtracted, the result
is 0), then *string* is selected for the result.
The comparison is effected using a numerical comparison with a
digits setting that is either nine or, if greater, the larger of the
number of digits in the mantissas of the two numbers (excluding
leading insignificant zeros).
The selected result is formatted by adding zero to the selected
number with a digits setting that is either nine or, if greater, the
number of digits in the mantissa of the number (excluding leading
insignificant zeros). Scientific notation is used, if necessary.
**Examples:**
0.min(1) ==0
'-1'.min(1) =='-1'
'+1'.min(-1) =='-1'
'1.0'.min(1.00) =='1.0'
'1.00'.min(1.0) =='1.00'
'123456700000'.min(1234567E+5) == '123456700000'
'1234567E+5'.min('123456700000') == '1.234567E+11'
overlay(new [,n [,length [,pad]]])
overlays the string new, padded or truncated to length length, onto a copy of the target string starting at the nth character; the string with any overlays is returned. Overlays may extend beyond the end of the original string. If length is specified it must be a non-negative whole number. If n is greater than the length of the target string, padding is added before the new string also. The default pad character is a blank, and the default value for n is 1. n must be greater than 0. The default value for length is the length of new.
**Examples:**
'abcdef'.overlay(' ',3) == 'ab def'
'abcdef'.overlay('.',3,2) == 'ab. ef'
'abcd'.overlay('qq') == 'qqcd'
'abcd'.overlay('qq',4) == 'abcqq'
'abc'.overlay('123',5,6,'+') == 'abc+123+++'
pos(needle [,start])
returns the position of the string needle, in string (the "haystack"), searching from left to right. If the string needle is not found, or is the null string, 0 is returned. By default the search starts at the first character of string (that is, start has the value 1). This may be overridden by specifying start (which must be a positive whole number), the point at which to start the search; if start is greater than the length of string then 0 is returned. Examples:
'Saturday'.pos('day') == 6
'abc def ghi'.pos('x') == 0
'abc def ghi'.pos(' ') == 4
'abc def ghi'.pos(' ',5) == 8
reverse()
returns a copy of
*string*, swapped end for end.
**Examples:**
'ABc.'.reverse == '.cBA'
'XYZ '.reverse == ' ZYX'
'Tranquility'.reverse == 'ytiliuqnarT'
right(length [,pad])
returns a string of length *length* containing the right-most
*length* characters of *string* - that is, padded with *pad*
characters (or truncated) on the left as needed. The default *pad*
character is a blank. *length* must be a non-negative whole number.
**Examples:**
'abc d'.right(8) == ' abc d'
'abc def'.right(5) == 'c def'
'12'.right(5,'0') == '00012'
sequence(final)
returns a string of all characters, in ascending order of encoding, between and including the character in string and the character in final. string and final must be single characters; if string is greater than final, an error is reported.
**Examples:**
'a'.sequence('f') == 'abcdef'
'\\0'.sequence('\\x03') == '\\x00\\x01\\x02\\x03'
'\\ufffe'.sequence('\\uffff') == '\\ufffe\\uffff'
sign()
returns a number that indicates the sign of string, which must be a number. string is first formatted, just as though the operation "string+0" had been carried out with sufficient digits to avoid rounding. If the number then starts with '-' then '-1' is returned; if it is '0' then '0' is returned; and otherwise '1' is returned.
**Examples:**
'12.3'.sign == 1
'0.0'.sign == 0
' -0.307'.sign == -1
soundex()
returns the normalized soundex value of the string. This implementation is for the English language.
**Examples:**
'EULER'.soundex() == 'E460'
space([n [,pad]])
returns a copy of string with the blank-delimited words in string formatted with n (and only n) pad characters between each word. n must be a non-negative whole number. If n is 0, all blanks are removed. Leading and trailing blanks are always removed. The default for n is 1, and the default pad character is a blank.
**Examples:**
'abc def '.space == 'abc def'
' abc def '.space(3) == 'abc def'
'abc def '.space(1) == 'abc def'
'abc def '.space(0) == 'abcdef'
'abc def '.space(2,'+') == 'abc++def'
strip([option [,char]]
returns a copy of string with Leading, Trailing, or Both leading and trailing characters removed, when the first character of option is L, T, or B respectively (these may be given in either uppercase or lowercase). The default is B. The second argument, char, specifies the character to be removed, with the default being a blank. If given, char must be exactly one character long.
**Examples:**
' ab c '.strip == 'ab c'
' ab c '.strip('L') == 'ab c '
' ab c '.strip('t') == ' ab c'
'12.70000'.strip('t',0) == '12.7'
'0012.700'.strip('b',0) == '12.7'
substr(n [,length [,pad]])
returns the sub-string of string that begins at the nth character, and is of length length, padded with pad characters if necessary. n must be a positive whole number, and length must be a non-negative whole number. If n is greater than string**.length**, then only pad characters can be returned. If length is omitted it defaults to be the rest of the string (or 0 if n is greater than the length of the string). The default pad character is a blank.
**Examples:**
'abc'.substr(2) == 'bc'
'abc'.substr(2,4) == 'bc '
'abc'.substr(5,4) == ' '
'abc'.substr(2,6,'.') == 'bc....'
'abc'.substr(5,6,'.') == '......'
**Note:** In some situations the positional (numeric) patterns of
parsing templates are more convenient for selecting sub-strings,
especially if more than one sub-string is to be extracted from a
string.
subword(n [,length])
returns the sub-string of string that starts at the nth word, and is up to length blank-delimited words long. n must be a positive whole number; if greater than the number of words in the string then the null string is returned. length must be a non-negative whole number. If length is omitted it defaults to be the remaining words in the string. The returned string will never have leading or trailing blanks, but will include all blanks between the selected words.
**Examples:**
'Now is the time'.subword(2,2) == 'is the'
'Now is the time'.subword(3) == 'the time'
'Now is the time'.subword(5) == ''
time()
: see page
translate(tableo, tablei [,pad])
returns a copy of string with each character in string either unchanged or translated to another character.
The **translate** method acts by searching the input translate
table, *tablei*, for each character in *string*. If the character is
found in *tablei* (the first, leftmost, occurrence being used if
there are duplicates) then the corresponding character in the same
position in the output translate table, *tableo*, is used in the
result string; otherwise the original character found in *string* is
used. The result string is always the same length as *string*.
The translate tables may be of any length, including the null
string. The output table, *tableo*, is padded with *pad* or
truncated on the right as necessary to be the same length as
*tablei*. The default *pad* is a blank.
**Examples:**
'abbc'.translate('\&','b') == 'a\&\&c'
'abcdef'.translate('12','ec') == 'ab2d1f'
'abcdef'.translate('12','abcd','.') == '12..ef'
'4123'.translate('abcd','1234') == 'dabc'
'4123'.translate('hods','1234') == 'shod'
**Note:** The last two examples show how the **translate** method
may be used to move around the characters in a string. In these
examples, any 4-character string could be specified as the first
argument and its last character would be moved to the beginning of
the string. Similarly, the term:
'gh.ef.abcd'.translate(19970827,'abcdefgh')
(which returns \"**27.08.1997**\") shows how a string (in this case
perhaps a date) might be re-formatted and merged with other
characters using the **translate** method.
trunc([n])
returns the integer part of string, which must be a number, with n decimal places (digits after the decimal point). n must be a non-negative whole number, and defaults to zero.
The number *string* is formatted by adding zero with a digits
setting that is either nine or, if greater, the number of digits in
the mantissa of the number (excluding leading insignificant zeros).
It is then truncated to *n* decimal places (or trailing zeros are
added if needed to make up the specified length). If *n* is 0 (the
default) then an integer with no decimal point is returned. The
result will never be in exponential form.
**Examples:**
'12.3'.trunc == 12
'127.09782'.trunc(3) == 127.097
'127.1'.trunc(3) == 127.100
'127'.trunc(2) == 127.00
'0'.trunc(2) == 0.00
upper([n [,length]])
returns a copy of string with any lowercase characters in the sub-string of string that begins at the nth character, and is of length length characters, replaced by their uppercase equivalent.
*n* must be a positive whole number, and defaults to 1 (the first
character in *string*). If *n* is greater than the length of
*string*, the string is returned unchanged.
*length* must be a non-negative whole number. If *length* is not
specified, or is greater than the number of characters from *n* to
the end of the string, the rest of the string (including the *nth*
character) is assumed.
**Examples:**
'Fou-Baa'.upper == 'FOU-BAA'
'Mad Sheep'.upper == 'MAD SHEEP'
'Mad sheep'.upper(5) == 'Mad SHEEP'
'Mad sheep'.upper(5,1) == 'Mad Sheep'
'Mad sheep'.upper(5,4) == 'Mad SHEEp'
'tinganon'.upper(1,1) == 'Tinganon'
''.upper == ''
verify(reference [,option [,start]])
verifies that string is composed only of characters from reference, by returning the position of the first character in string that is not also in reference. If all the characters were found in reference, 0 is returned. The option may be either 'Nomatch' (the default) or 'Match'. Only the first character of option is significant and it may be in uppercase or in lowercase. If 'Match' is specified, the position of the first character in string that is in reference is returned, or 0 is returned if none of the characters were found. The default for start is 1 (that is, the search starts at the first character of string). This can be overridden by giving a different start point, which must be positive. If string is the null string, the method returns 0, regardless of the value of the option. Similarly if start is greater than string**.length**, 0 is returned. If reference is the null string, then the returned value is the same as the value used for start, unless 'Match' is specified as the option, in which case 0 is returned.
**Examples:**
'123'.verify('1234567890') == 0
'1Z3'.verify('1234567890') == 2
'AB4T'.verify('1234567890','M') == 3
'1P3Q4'.verify('1234567890','N',3) == 4
'ABCDE'.verify('','n',3) == 3
'AB3CD5'.verify('1234567890','m',4) == 6
word(n)
returns the nth blank-delimited word in string. n must be positive. If there are fewer than n words in string, the null string is returned. This method is exactly equivalent to string**.subword(**n,1).
**Examples:**
'Now is the time'.word(3) == 'the'
'Now is the time'.word(5) == ''
wordindex(n)
returns the character position of the nth blank-delimited word in string. n must be positive. If there are fewer than n words in the string, 0 is returned.
**Examples:**
'Now is the time'.wordindex(3) == 8
'Now is the time'.wordindex(6) == 0
wordlength(n)
returns the length of the nth blank-delimited word in string. n must be positive. If there are fewer than n words in the string, 0 is returned.
**Examples:**
'Now is the time'.wordlength(2) == 2
'Now comes the time'.wordlength(2) == 5
'Now is the time'.wordlength(6) == 0
wordpos(phrase [,start])
searches string for the first occurrence of the sequence of blank-delimited words phrase, and returns the word number of the first word of phrase in string. Multiple blanks between words in either phrase or string are treated as a single blank for the comparison, but otherwise the words must match exactly. Similarly, leading or trailing blanks on either string are ignored. If phrase is not found, or contains no words, 0 is returned. By default the search starts at the first word in string. This may be overridden by specifying start (which must be positive), the word at which to start the search.
**Examples:**
'now is the time'.wordpos('the') == 3
'now is the time'.wordpos('The') == 0
'now is the time'.wordpos('is the') == 2
'now is the time'.wordpos('is the') == 2
'now is the time'.wordpos('is time') == 0
'To be or not to be'.wordpos('be') == 2
'To be or not to be'.wordpos('be',3) == 6
words()
returns the number of blank-delimited words in string.
**Examples:**
'Now is the time'.words == 4
' '.words == 0
''.words == 0
x2b()
Hexadecimal to binary. Converts string (a string of at least one hexadecimal characters) to an equivalent string of binary digits. Hexadecimal characters may be any decimal digit character (0-9) or any of the first six alphabetic characters (a-f), in either lowercase or uppercase. string may be of any length; each hexadecimal character with be converted to a string of four binary digits. The returned string will have a length that is a multiple of four, and will not include any blanks.
**Examples:**
'C3'.x2b == '11000011'
'7'.x2b == '0111'
'1C1'.x2b == '000111000001'
x2c()
Hexadecimal to coded character. Converts the string (a string of hexadecimal characters) to a single character (packs). Hexadecimal characters may be any decimal digit character (0-9) or any of the first six alphabetic characters (a-f), in either lowercase or uppercase.
*string* must contain at least one hexadecimal character;
insignificant leading zeros are removed, and the string is then
padded with leading zeros if necessary to make a sufficient number
of hexadecimal digits to describe a character encoding for the
implementation.
An error results if the encoding described does not produce a valid
character for the implementation (for example, if it has more
significant bits than the implementation's encoding for characters).
**Examples:**
'004D'.x2c == 'M' -- ASCII or Unicode
'4d'.x2c == 'M' -- ASCII or Unicode
'A2'.x2c == 's' -- EBCDIC
'0'.x2c == '\textbackslash 0'
The **d2c** method (see page ) can be used to convert a number to
the encoding of a character.
x2d([n])
Hexadecimal to decimal. Converts the string (a string of hexadecimal characters) to a decimal number, without rounding. If string is the null string, 0 is returned.
If *n* is not specified, *string* is taken to be an unsigned number.
**Examples:**
'0E'.x2d == 14
'81'.x2d == 129
'F81'.x2d == 3969
'FF81'.x2d == 65409
'c6f0'.x2d == 50928
If *n* is specified, *string* is taken as a signed number expressed
in *n* hexadecimal characters. If the most significant (left-most)
bit is zero then the number is positive; otherwise it is a negative
number in twos-complement form. In both cases it is converted to a
number which may, therefore, be negative. If *n* is 0, 0 is always
returned.
If necessary, *string* is padded on the left with **'0'** characters
(note, not \"sign-extended\"), or truncated on the left, to length
*n* characters; (that is, as though *string***.right(***n*, **'0')**
had been executed.)
**Examples:**
'81'.x2d(2) == -127
'81'.x2d(4) == 129
'F081'.x2d(4) == -3967
'F081'.x2d(3) == 129
'F081'.x2d(2) == -127
'F081'.x2d(1) == 1
'0031'.x2d(0) == 0
The **c2d** method (see page ) can be used to convert a character to
a decimal representation of its encoding.