\begindata{text,3499520} \textdsversion{12} \template{default} \define{global } \heading{REXX Functions} The functions in this section simulate the string functions offered by REXX, but have so many differences that each function name is distinguished with an x suffix. In general the differences are these: \leftindent{Unlike most Ness functions, those of REXX create entirely new string values rather than references to the argument string. Ness functions have no concept of "position" in a string; instead substrings are referred to directly as values. REXX functions refer to word and character positions with integers, counting with one (1) as the first character or word. A "word" is any sequence of non-space characters delimited by the end of the string or by space characters: (space), TAB, newline, carriage return, vertical tab, or form feed. REXX functions have optional arguments, but Ness functions do not. Where REXX would have an optional 'start' argument, the function 'right' can be called; where REXX would have an optional pad argument, use padx, prepadx, or centerpadx. Some REXX implementations utilize the anitquated EDCDIC character code. These Ness functions encode text in ASCII. String constants in REXX are delimited in apostrohpes (') while those in Ness are delimited with double-quote ("). Ness is a typed language, unlike REXX. Thus when a function returns an integer its value cannot be passed directly to a function requiring a string argument. The functions textImage and parseInt can be used to convert between integers and strings.} Unless otherwise indicated, the type of arguments and functions is \italic{marker.} \bold{abbrevx(information, info)} returns boolean Returns True if info is equal to the leading characters of information. If info is empty, the result is True.\example{ ABBREVX("Print", "Pri") -> True ABBREVX("PRINT", "Pri") -> False ABBREVX("PRINT", "PRY") -> False ABBREVX("PRINT", "") -> True} \bold{centerx(string, integer length)} Returns a string of the given length whose center is at the center of the first argument string. If the first argument is shorter than the given length, it is padded with spaces. (For padding with non-spaces, see function centerpadx). If an odd number of characters must be deleted or padded, the extra one is done on the right hand end. Length must be 0 or more. \example{CENTERX("abc", 7) -> " abc " CENTERX("abc", 8) -> " abc " CENTERX("The blue sky", 8) -> "e blue s" CENTERX("The blue sky", 7) -> "e blue " CENTERX("The blue seas", 8) -> "e blue s" CENTERX("The blue seas", 7) -> " blue s" } \bold{centerpadx(string, integer length, pad)} Just line centerx, except the padding is done with the character given as the third argument instead of spaces. \example{CENTERPADX("abc", 7, ".") -> "..abc.." CENTERPADX("abc", 8, ".") -> "..abc..." CENTERPADX("The blue sky", 8, ".") -> "e blue s" CENTERPADX("The blue sky", 7, ".") -> "e blue "} \bold{copiesx(string, integer n)} Returns a string consisting of n copies of the string argument. N must be zero or more. \example{COPIESX("abc", 3) -> "abcabcabc" COPIESX("abc", 0) -> ""} \bold{delstrx(string, integer n, integer length)} Returns a copy of string from which has been deleted the substring that begins at the nth character, and is of length length. If length+n-1 exceeds the length of string, the rest of string is deleted. If n is greater than the length of string, the copy is idnetical to the original. Length must be zero or more. N must be one or more. \{The length must be specified, but may be arbitrarily large.\} \example{DELSTRX("abcd", 3, 9999) -> "ab" DELSTRX("abcde", 3, 2) -> "abe" DELSTRX("abcde", 6, 9999) -> "abcde"} \bold{delwordx(string, integer n, integer length)} Returns a copy of string from which has been deleted the substring that begins at the nth word, and is length words long. If length+n-1 exceeds the number of words, the rest of the string is deleted. If n exceeds the number of words, the copy is identical to the original string. Length must be zero or more. N must be one or more. \{The length must be specified, but may be arbitrarily large.\} \example{DELWORDX("Now is the time", 2, 2) -> "Now time" DELWORDX("Now is the time ", 3, 9999) -> "Now is " DELWORDX("Now is the time", 5, 9999) -> "Now is the time"} \bold{findx(string, phrase)} returns integer Returns an integer which is the index of the word in string where a substring matching phrase begins. Multiple blanks are treated as single blanks. If the phrase is not found, zero is returned. \example{FINDX("now is the time", "is the time") -> 2 FINDX("now is the time", "is the") -> 2 FINDX("now is the time", "is time ") -> 0} \bold{indexx(string, target)} returns integer Returns the integer index of the first location in string which starts a substring matching the target. If no instance of target is found in string, returns 0. \example{INDEXX("abcdef", "cd") -> 3 INDEXX("abcdef", "xd") -> 0} \bold{insertx(new, target, integer n)} Returns a copy of the target string into which new has been inserted beginning at the n'th character. n must be non-negative. If n is greater than the length of the target string, blank padding is added. N must be zero or more. \example{INSERTX(" ", "abcdef", 3) -> "abc def" INSERTX("123", "abc", 5) -> "abc 123" INSERTX("123", "abc", 0) -> "123abc"} \bold{justifyx(string, integer length)} Returns a copy of string stretched or shrunk to the given length. Leading and trailing spaces are deleted. To stretch, spaces are added evenly between the words; to shrink, spaces are reduced to one at each word break and then the string is truncated. Length must be zero or more. If the added space is not evenly divided by the number of spaces between words, the excess are added to spaces starting from the left or right and proceeding toward the middle. (Left and right are alternated on each call to the function.) \example{JUSTIFYX("The blue sky", 14) -> "The blue sky" JUSTIFYX("The blue sky ", 8) -> "The blue" JUSTIFYX(" The blue sky", 9) -> "The blue"} \bold{leftx(string, integer len)} Returns a copy of the leftmost len characters of string. If the string is shorter than len, a copy of the string is returned. Len must be zero or more. \{In Rexx, the string would have been padded; use padx to accomplish this.\} \example{LEFTX("abc d", 8) -> "abc d" LEFTX("abc def", 7) -> "abc de"} \bold{overlayx(new, target, integer n)} Returns a copy of the string target with the characters starting at position n replaced with a copy of the string new. If n is greater than the length of the target string, the target is padded with blanks. n must be greater than 0. \example{OVERLAYX(" ", "abcdef", 3) -> "ab def" OVERLAYX(".", "abcdef", 3) -> "ab.def" OVERLAYX("qq", "abcd", 1) -> "qqcd" OVERLAYX("qq", "abcd", 4) -> "abcqq" OVERLAYX("123", "abc", 5) -> "abc 123"} \bold{padx(string, integer length, pad)} Returns a copy of string stretched or shrunk to the given length. It it shrunk by truncation on the right and stretched by padding on the right with the given pad character. Length must be zero or more. \example{PADX("test", 7, ".") -> "test..." PADX("test", 3, ".") -> "tes"} \bold{prepadx(string, integer length, pad)} Just like padx, but truncation or padding are done on the left. Length must be zero or more. \example{PREPADX("test", 7, ".") -> "...test" PREPADX("test", 3, ".") -> "est"} \bold{prestripx(string, chars)} Just like stripx, but characters are removed from the left. \example{PRESTRIPX(" ab c ", " .") -> "ab c " PRESTRIPX(" ab c ", " a") -> "b c "} \bold{posx(needle, haystack)} returns integer Returns an integer giving the position in the second argument of the first occurrence of a substring equal to the first argument. If no occurrence is found, returns 0. \{Unlike Rexx, no "start" parameter is allowed. Use substr.\} \example{POSX("day", "Saturday") -> 6 POSX("x", "abc def ghi") -> 0 POSX(" ", "abc def ghi") -> 4} \bold{reversex(string)} Returns a copy of the argument string in reverse order. \italic{Warning:} If the string has styles in them, each character that was in a styled substring will be individually wrapped with the style. This can greatly increase space requirements. \example{REVERSEX("ABc.") -> ".cBA" REVERSEX("XYZ ") -> " ZYX"} \bold{rightx(string, integer length)} Returns a copy of the rightmost length characters of string. If the string is shorter than length, returns a copy of string. \{There is no pad argument; use prepadx to get padding.\} Length must be zero or more. \example{RIGHTX("abc d", 8) -> "abc d" RIGHTX("abc def", 5) -> "c def"} \bold{spacex(string)} Returns a copy of string with spaces reduced to a minimum. Leading and trailing spaces are removed and all multiple internal spaces are reduced to single spaces. \example{SPACEX(" test words ") -> "test words" SPACEX("test words too ") -> "test words too"} \bold{stripx(string, chars)} Returns a copy of string from which the right hand end has been reduced by removal of all characters of which there is an instance in chars. \example{STRIPX(" ab c ", " .") -> " ab c" STRIPX(" ab c ", " c") -> " ab"} \bold{substrx(string, integer pos, integer length)} Substrx extracts a substring of specified length, starting at pos. If the length of the string is L, the returned length is the shorter oflength or L-pos+1, but not less than zero. Length must be zero or more. Pos must be one or more. \example{SUBSTRX("abc", 2, 9999) -> "bc" SUBSTRX("abc", 2, 1) -> "b"} \bold{subwordx(string, integer n, integer length)} Returns a copy of the substring of string that starts at the nth word, and has length blank-delimited words. The returned string will never have leading or trailing blanks, but will include all blanks between the selected words. If n exceeds the number of words in the string, an empty string is returned. If length exceeds the number of words after the n'th, all words after the n'th are returned. Length must be zero or more. N must be one or more. \{Unlike REXX, length is not optional; but it may be arbitrarily large.\} \example{SUBWORDX("Now is the time", 2, 2) -> "is the" SUBWORDX("Now is the time", 3, 9999) -> "the time" SUBWORDX("Now is the time", 5, 9999) -> ""} \bold{tolowerx(string)} Returns a copy of string with all ASCII upper case letters converted to lower case. \example{TOLOWERX("This IS a tEst") -> "this is a test" } \bold{toupperx(string)} Returns a copy of string with all ASCII lower case letters converted to upper case. \example{TOUPPERX("This IS a tEst") -> "THIS IS A TEST" } \bold{translatex(string, tableo, tablei)} Translates characters in string to be other characters, or may be used reorder characters in a string. Returns a copy of string with some characters translated; string characters from tablei are replaced with the character at the corresponding position in tableo. The tables may be of any length: the first occurrence of a character in tablei is the one that is used if there are duplicates. If the output table is shorter than the input, the corresponding characters are deleted from the result. If there are styles in the string, they will be retained in the result. Styles in the tables will not affect the result. In consequence translatex cannot be used to reorder styled text. \example{TRANSLATEX("abbc", "&", "b") -> "a&&c" TRANSLATEX("abcdef", "12", "ec") -> "ab2d1f" TRANSLATEX("abcdef", "12", "abcd") -> "12ef" TRANSLATEX("4123", "abcd", "1234") -> "dabc"} \bold{verifyx(string, reference)} returns integer Returns an integer value indicating the position of the first character in string which is not among the set of characters in reference. If all characters are found, returns zero. \example{VERIFYX("123", "1234567890") -> 0 VERIFYX("1Z3", "1234567890") -> 2} \bold{wordx(string, integer n)} Returns a copy of the n'th word from string. If string has fewer than n words, returns an empty string. N must be one or more. \example{WORDX("Now is the time", 3) -> "the" WORDX("Now ! is the time", 3) -> "is" WORDX("Now is the time", 5) -> ""} \bold{wordindexx(string, integer n)} returns integer Returns an integer giving the position of the nth blank-delimited word in string. If there are not n words in the string, 0 is returned. N must be one or more. \example{WORDINDEXX("Now is the time", 3) -> 8 WORDINDEXX("Now is the time", 6) -> 0} \bold{wordsx(string)} returns integer Returns an integer giving the number of words in string. Words are any strings delimited by spaces. \example{WORDSX("Now is the time") -> 4 WORDSX(" ") -> 0} \bold{xrangex(start, end)} Returns a string of all one byte codes between and including the values start and end. If start is greater than end, the values will wrap from "\\377" to "\\0". If start is an empty string, "\\0" will be used; if end is the empty string, "\\377" will be used. \example{XRANGEX("a", "f") -> "abcdef" XRANGEX("\\3", "\\7") -> "\\3\\4\\5\\6\\7" XRANGEX("i", "j") -> "ij" XRANGEX("\\376", "\\2") -> "\\376\\377\\0\\1\\2"} \begindata{bp,3487616} \enddata{bp,3487616} \view{bpv,3487616,0,0,0} Copyright 1992 Carnegie Mellon University and IBM. All rights reserved. \smaller{\smaller{$Disclaimer: Permission to use, copy, modify, and distribute this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice, this permission notice, and the following disclaimer appear in supporting documentation, and that the names of IBM, Carnegie Mellon University, and other copyright holders, not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL IBM, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER COPYRIGHT HOLDER BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. $ }}\enddata{text,3499520}