SNOBOL5 Functions

Primitive functions

These are primitive SNOBOL5 functions which are not predicates or pattern functions. Any of these functions can be redefined by the user using DEFINE(). When calling any SNOBOL5 function, if an argument is omitted, the corresponding parameter value is set to null (null string). Note that a null string converts into a zero when it is the operand of an arithmetic operation. In the Green book, all of these functions used only upper case names. SNOBOL5 allows either all upper case or all lower case names (not mixed) for these functions. The naming throughout is still case sensitive however.

ABS(x) or abs(x) /pi /Absolute value function .. returns the arithmetic absolute value of x. If x is the minimum possible integer, an error occurs.

AND(x,y) or and(x,y) returns the logical AND of the bytes in strings x and y. If x or y is shorter than the other, then trailing zero bytes are assumed for the shorter one. The length of the result is the maximum of lengths of x and y.

APPLY(f,a1,a2...) or apply(f,a1,a3...) calls function f with arguments a1, a2 ... and returns the value of the called function. The name of the function f must be a character string. APPLY is useful for situations requiring a variable function name.

ARG(f,i) or arg(f,i) returns a string which is the name of the ith parameter of the programmer defined function f. The name of the function f must be a character string. This function is useful for obtaining the parameters in generalized trace procedures.

ARRAY(p,x) or array(p,x) returns an array described by the string p, whose elements are are all initialized to the value x. The syntax for p is as follows:

p ::= slice ["," slice]... slice ::= upperbound | lowerbound ":" upperbound upperbound ::= integer lowerbound ::= integer

The lower bound is assumed to be one if not specified. The upper bound must not be less than the lower bound. ARRAY('3,-1:1') returns a 3 by 3 element, two dimension array.

ATAN(x) or atan(x) returns the arc tangent x. The result is in radians ranging from -π/2 to +π/2.

ATAN2(y,x) or atan2(y,x) returns the arc tangent of coordinate x,y. The result is in radians ranging from -π to +π.

BACKSPACE(unit) or backspace(unit) This function is omitted in SNOBOL5. See the SEEK function. In the prior Minnesota SNOBOL4, the function backspaces a file open for read to the start of the record prior to the current position in the file. That is after the carriage return character before the start of the record, usually at the line feed character for ASCII files. If there is no carriage return character, then it positions it to the start of the file. This works the same for ascci or binary file modifiers. If a fixed length backspace is desired, use the relative SEEK function. An error is issued if the unit is not a file or is not open for read. Note, backspacing once after a read means that you will read the record again if you do another read. If you need to read the records in a file in reverse order, you need to issue two backspaces between each read.

BIT2H(x) or bit2h(x) This converts the bit string x to a hexadecimal string. The string x should be a character string of "0" and "1" characters. However, if they are not zero's and one's then the low order bit of the ascii encoding of each of the character is used. If x is not a multiple of 4 in length, it will be considered padded on the right with zeros. The function returns the hexadecimal result using characters 0123456789ABCDEF. For example, bit2h('11010111011') returns the string "D76".

BIT2I(x) or bit2i(x) This converts the bit string x to a 64 bit integer in two's complement form. The string x should be a character string of "0" and "1" characters. However, if they are not zero's and one's then the low order bit of the ascii encoding of each of the character is used. The string x should be in big endian format, with the least significant bit on the right. If x has fewer than 64 characters, then it is padded on the left with '0' characters, and thus cannot produce a negative result. If x has more than 64 characters, the function fails. For example, bit2i(bit(123)) returns the integer 123. See the related bit2is(x) function and inverse bit(x) function.

BIT2IS(x) or bit2is(x) This converts the bit string x to a 64 bit integer in two's complement form, extending the left most sign bit. The string x should be a character string of "0" and "1" characters. However, if they are not zero's and one's then the low order bit of the ascii encoding of each of the character is used. The string x should be in big endian format, with the least significant bit on the right. If x has fewer than 64 characters, then it is padded on the left with the first character of x. Thus the first character of x defines the sign of the resulting number. If x has more than 64 characters, the function fails. For example, bit2is(bit(123)) returns the integer 123. While bit2is('11') returns -1 and bit2is('011') returns 3. See the related bit2i(x) function and inverse bit(x) function.

BIT2R(x) or bit2r(x) This converts the bit string x to a real per its binary IEEE 754 Standard double precision 64 bit encoding. The string x should be a character string of "0" and "1" characters. However, if they are not zero's and one's then the low order bit of the ascii encoding of each of the character is used. The string x should be in big endian format, with the sign bit on the left. If string x does not have exactly 64 characters, the function fails. For example, bit2r(bit(&PI)) returns the real number 3.1415926535898. See the related inverse bit(x) function.

BIT2S(x) or bit2s(x) This converts the bit string x to a character string using ascii encoding of characters. The string x should be a character string of "0" and "1" characters. However, if they are not zero's and one's then the low order bit of the ascii encoding of each of the character is used. The string x is not a multiple of 8 characters, it is assumed to be padded on the right to make it so. For example, bit2s(bit('hello')) returns the string 'hello'. See the related inverse bit(x) function.

BIT(x) or bit(x) This function returns the bit representation of x. If x is a string, then the bit representation of the string is returned in the form of a string of ones ("1") and zeros ("0"). The high order bit of the first character in the string is the first in the result string. For example, bit('hi') returns '0110100001101001'. If x is an integer or real number, the bit string returned is in big endian format with the most significant bit coming first. For example, bit(123) returns '0000000000000000000000000000000000000000000000000000000001111011'. For a real number, the IEEE 754 Standard double precision 64-bit float point binary format is returned. For example, bit(123.5) returns '0100000001011110111000000000000000000000000000000000000000000000'. Only string, integer or real data types are permitted for x. See the related HEX(x) function.

BYTES2I(x) or bytes2i(x) This converts the byte string x to an integer. The string x should be in little endian order with leftmost byte being the low order one. If there are fewer than 8 bytes, the string x is considered to be padded with zero bytes to reach 8 bytes. If x has more than 8 bytes, the function fails.

BYTES2IS(x) or bytes2is(x) This converts the byte string x (sign extended) to an integer. The string x should be in little endian order with leftmost byte being the low order one. If there are fewer than 8 bytes, the string x is considered to be padded with bytes containing the sign bit of the right-most byte, effectively extending the sign bit. If x has more than 8 bytes, the function fails.

BYTES2R(x) or bytes2r(x) This converts the byte string x to a real. The string x should be of length 8 in IEEE 754 standard double precision form, in little endian order with leftmost byte being the low order one. If x is not of length 8, the function fails.

BYTESS2R(x) or bytess2r(x) This converts the byte string x to a real. The string x should be of length 4 in IEEE 754 standard single precision form, in little endian order with leftmost byte being the low order one. If x is not of length 4, the function fails.

BYTESX2R(x) or bytesx2r(x) This converts the byte string x to a real. The string x should be of length 10 in IEEE 754 standard extended precision form, in little endian order with leftmost byte being the low order one. If x is not of length 10, the function fails.

CENTER(S,L,C) or center(s,l,c) This function centers string S so that the result string has length max(L,SIZE(S)) by equal padding (equal within one character) on the left and right using the first character of string C as the pad character, or using a blank if C is null. Padding occurs if SIZE(S)<.L. Note S is not trimmed before padding so any leading or trailing blanks in S may make it look like it was not centered. One use for CENTER is centering titles on a printed page. See the example under RPAD.

CHAR(x) or char(x) returns the ASCII character that is represented by the number x. This function is equivalent to SUBSTR(&ALPHABET,x,1). For example, CHAR(32) returns a blank character, CHAR(48) returns a zero ("0"), and CHAR(65) returns the letter "A". x must be in the range of 0 through 255. If x is REAL, then the fractional part is ignored.

CLEAR() or clear() resets all natural variables to null at this function level. If a variable has been pushed as a result of some function invocation, it will reappear with its old value when that function returns. Note that all of the pattern primitives, which are variables, such as ARB, BAL etc. are also reset to null strings. To get their values back, you can use the corresponding keywords &ARB, &BAL etc.

CODE(s) or code() "compiles" the SNOBOL5 statements given by the string s and returns the compiled code (see CODE data type). The newly compiled code can be executed by using the <code> form of the goto. This starts execution at the first compiled statement. Also, if labels are included in the statements in string s, then they replace any existing labels currently in effect and may be branched to using the parenthesis form of the goto. The CODE function fails if there is a syntax error in the string s. Note, that the first character of a statement must be blank or it will be treated as a label. Also, more than one statement can be compiled by separating them with the semicolon.

COLLECT(i) or collect() forces garbage collection in the SNOBOL5 work space. The function returns the number of unused bytes in the work space. If there are fewer than i bytes in the work space after collection, then the function fails.

CONVERT(x,t) or convert(x,t) converts the object x to the data type specified by string t. If the conversion is not possible, then the function fails. Anything can be converted to type "STRING". A useful conversion is that converting a table into an "ARRAY", which gives an n by 2 array form of the table. This allows one to serially access all of the elements of a table. Likewise, an n by 2 array can be converted into a "TABLE". The <n,1> slice is the set of indexes for the table elements containing the corresponding values in slice <n,2>. See also the INT(x), REAL(x), STR(x) functions which are shortcuts to INTEGER, REAL and STRING conversions, respectively.

COPY(a) or copy(a) returns a copy of a of any datatype except TABLE. This is most useful for arrays.

COS(x) or cos(x) returns the cosine of angle x in radians.

DATA(p) or data(p) defines a "programmer defined" data type and returns the null string. The prototype of the data type is defined by string p which has the following syntax:

p ::= datatypename "(" fieldname ["," fieldname]... ")"

To create an instance of the new data type, use what looks like a function reference, giving the data type name instead of the function name. Each argument gets assigned to the corresponding fields of the data type instance. The fields may be accessed with what also looks like a function reference with one argument, which is the instance of the data type. You should not specify field names that are other data type names or function names. For example, if you wanted to introduce complex numbers in your program:

* first define the data type DATA('COMPLEX(R,I)') * setting X to be 2+3i X = COMPLEX(2,3) * multiplying two complex numbers Z=X*Y R(Z) = R(X) * R(Y) + I(X) * I(Y) I(Z) = R(X) * I(Y) + R(Y) * I(X) * you could use DEFINE() and OPSYN() to make the * arithmetic operators (+-/*) in SNOBOL5 handle * complex numbers by defining new arithmetic * functions

DATATYPE(x) or datatype(x) returns the name of the datatype of object x as a string. This also works for programmer defined data types defined with the DATA() function. DATATYPE('ABC') returns 'STRING' for example.

DATE() or date() returns the current date and time as a character string in the form 'YYYY-MM-DD HH:MM:SS.SSS'. Both time and date are returned at once to handle midnight properly. Note that the prior Minnesota SNOBOL4 version returned 'YYYY-MM-DD HH:MM:SS.SS'. This format was chosen because it lends itself to sorting by date and time. The time is return in the local time zone.

DEFINE(p,e) or define(p,e) defines a programmer defined function. The prototype p of the function is specified by string p which has the following syntax:

p ::= fncname "(" [param ["," param]... ] ")" [lclv [,lclv]... ]

where the parameters and local variables are specified. The local variable values are saved and set to null upon entry into the function, and their old values are restored when the function returns. This also applies to the parameters, except instead of being set to null, they are set to the values of the corresponding arguments. The function is assumed to start at the statement with label fncname, when e is null. If a different label is to be used, the string e can be used to indicate this when calling DEFINE. Use the special return label RETURN to return from the function successfully and FRETURN to return with failure. NRETURN can be used to return the name of a variable instead of its value. The value to be returned by the defined function can be set by assigning a value to the variable fncname. DEFINE() returns the null string.

The following is an example of the definition and use of a function to compute numbers in Pascal's triangle (binomial coefficients):

DEFINE('BN(ROW,COL)PREV','PAS') :(SKP) * Note that label PAS is different than BN * Return NULL (zero) outside the triangle PAS LE(0,COL) LE(COL,ROW) :F(RETURN) * Return 1 at the triangle top BN(0,0) BN = EQ(COL) EQ(ROW) 1 :S(RETURN) * Calculate previous row number * PREV is a local variable PREV = ROW - 1 * Return sum of two prior items in * triangle by calling BN recursively BN = BN(PREV,COL) + BN(PREV,COL - 1) + :(RETURN) SKP OUTPUT = 'There are ' BN(4,2) ' ways' + ' to select 2 items out of a set of 4'

The following is an example of the definition and use of a function to compute factorials of numbers:

DEFINE('FACT(N)') :(SKIPFCN) * Set value to 1 FACT FACT = 1 * Return 1 if N<2 * Return N*((N-1)!) with recursive call FACT = GT(N,1) FACT(N - 1) * N :(RETURN) SKIPFCN OUTPUT = '5 factorial is ' FACT(5)

DETACH(s) or detach(s) removes the I/O association to the variable with the name specified by string s. See INPUT() and OUTPUT() functions.

DUMP(n) or dump(n) prints a dump of all natural variables which have a non-null value, if the argument n is a non-zero integer. If n is zero, the dump is not performed.

DUPL(s,n) or dupl(s,n) returns a string consisting of string s repeated n times.

ENDFILE(n) or endfile(n) closes the file attached to I/O unit number n.

ENDIANB(S) or endianb(S) performs a bitwise endian shuffle. That is, if S is bit string with a multiple of 8 length, it returns the opposite endian of string S. That is if S is in little endian format, then the output is in big endian format. If S is in big endian format, then the output is in little endian format. If the length of S is not a multiple of 8, then the function fails. See ENDIANH(s) for a version for hex digits. Use REVERSE(s) for a byte version. For example:

x = bit(123456789) OUTPUT = 'x=' x y = endianb(x) OUTPUT = 'y=' y Produces output: x=0000000000000000000000000000000000000111010110111100110100010101 y=0001010111001101010110110000011100000000000000000000000000000000

ENDIANH(S) or endianh(S) performs a hex digit endian shuffle. That is, if S is hex digit string with a multiple of 2 length, it returns the opposite endian of string S. That is if S is in little endian format, then the output is in big endian format. If S is in big endian format, then the output is in little endian format. If the length of S is not even, the function fails. See ENDIANB(s) for a version for bit digits. Use REVERSE(s) for a byte version. For example:

x = hex(123456789) OUTPUT = 'x=' x y = endianh(x) OUTPUT = 'y=' y Produces output: x=00000000075BCD15 y=15CD5B0700000000

EVAL(s) or eval(s) causes the SNOBOL5 expression given in string s to be compiled and evaluated. "s" may also be an integer, or an unevaluated expression. If the argument is not syntactically correct, then EVAL fails. For example, EVAL('N + 4') returns the current value of N increased by four.

FIELD(dt,n) or field(dt,n) returns a string giving the name of the nth field of a programmer defined data type dt. The function fails if there is no nth field in that data type. The following example illustrates its use:

DATA('NODE(PREV,NEXT,CONTENT)') OUTPUT = FIELD('NODE',2)

The above prints the string 'NEXT'.

GETENV(x) or getenv(x) returns the value of environment variable x. In Windows the case of x does not matter, but Linux is case sensitive with regard to x. See "SNOPATH" environment variable used in include processing. As an example, the following prints the paths in the PATH environment variable:

br = ';' br = IDENT(&OS,'Linux') ':' x = getenv('PATH') br loop x (break(br) | REM) . OUTPUT br = :S(loop)

HEX(x) or hex(x) This function returns the hexadecimal digit representation of x. If x is a string, then the hex digit representation of the string is returned in the form of a string of zero ("0") through ("A") characters. The high order hex digit of the first character in the string x is the first in the result string. For example, hex('hi') returns '6869'. If x is an integer or real number, the hex string returned is in big endian format with the most significant hex digit coming first. For example, hex(123) returns '000000000000007B'. For a real number, the IEEE 754 Standard double precision 64-bit float point binary format is returned. For example, hex(123.5) returns '405EE00000000000'. Only string, integer or real data types are permitted for x. See the related BIT(x) function.

HEX2B(x) or hex2b(x) This converts the hex string x to a bit string. The string x should be a character string of 0...9A...F or 0...9a...f hexadecimal characters. The function returns a string of zero and one characters representing the hexadecimal string. The leftmost hex character generates the leftmost 4 bit characters with the high order one coming first. For example, hex2b('f3') returns the string "11110011". If the source string x contains characters that are not hexadecimal characters, then they are treated as zero characters.

HEX2I(x) or hex2i(x) This converts the hexadecimal digit string x to a 64 bit integer in two's complement form. The string x should be a character string of these characters: 0123456789abcdefABCDEF However, if they are any other characters, they are considered to be zero hex digits. The string x should be in big endian format, with the least significant bit on the right. If x has fewer than 16 characters, then it is padded on the left with '0' characters, and thus cannot produce a negative result. If x has more than 64 characters, the function fails. For example, hex2i('7f') returns the integer 127. See the related hex2is(x) function and inverse hex(x) function.

HEX2IS(x) or hex2is(x) This converts the hexadecimal digit string x to a 64 bit integer in two's complement form, sign bit extended. The string x should be a character string of these characters: 0123456789abcdefABCDEF However, if they are any other characters, they are considered to be zero hex digits. The string x should be in big endian format, with the least significant bit on the right. If x has fewer than 16 characters, then it is padded on the left with the high order bit of the leftmost hex digit. If x has more than 64 characters, the function fails. For example, hex2is('f7') returns the integer -9. See the related hex2i(x) function and inverse hex(x) function.

HEX2R(x) or hex2r(x) This converts the hexadecimal digit string x to a real per its binary IEEE 754 Standard double precision 64 bit encoding. The string x should be a character string of these characters: 0123456789abcdefABCDEF However, if they are any other characters, they are considered to be zero hex digits. The string x should be in big endian format, with the sign bit on the left. If string x does not have exactly 16 characters, the function fails. For example, hex2r(hex(&PI)) returns the real number 3.1415926535898. See the related inverse hex(x) function.

HEX2S(x) or hex2s(x) This converts the hex string x to a character string. The string x should be a character string of 0...9A...F or 0...9a...f hexadecimal characters. The function returns a string bytes compsed of pairs of hex digits. The leftmost hex character generates the high order portion of the result character. If the source string x contains characters that are not hexadecimal characters, then they are treated as zero characters. If x is odd in length, a trailing zero hex digit is assumed appended. For example, hex2s('31323') returns the string "120".

HEXSR(x) or hexs2r(x) This converts the 8 hexadecimal digit string (single precision) x to a double precision REAL per its binary IEEE 754 Standard encoding. The string x should be a character string of these characters: 0123456789abcdefABCDEF However, if they are any other characters, they are considered to be zero hex digits. The string x should be in big endian format, with the sign bit on the left. If string x does not have exactly 8 characters, the function fails. See the related hex2r(x) and hexx2r(x) functions.

HEXXR(x) or hexx2r(x) This converts the 20 hexadecimal digit string (double extended precision) x to a double precision REAL per its binary IEEE 754 Standard encoding. The string x should be a character string of these characters: 0123456789abcdefABCDEF However, if they are any other characters, they are considered to be zero hex digits. The string x should be in big endian format, with the sign bit on the left. If string x does not have exactly 20 characters, the function fails. Furthermore, if the source number is larger than can be represented in double precision, an infinity or zero may result. See the related hex2r(x) and hexs2r(x) functions.

I2BYTES(x) or i2byte(x) This converts the integer X to a string of 8 bytes in little endian form. The leftmost byte is the low order one.

INPUT(vname,unitn,buflen,fname,mods) or input(vname,unitn,buflen,fname,mods) is used to associate a SNOBOL5 input variable name with an external input unit and optionally specify the file name (or path name) along with the file modifiers. This function is usually used in one of two ways. First, using just the first three operands, and second with all five parameters. The fourth and fifth parameters are an extension over the definition contained in the green book. They permit the specification of the file name along with optional file modifiers.

In the spirit of mainframe SNOBOL, 999 numbered I/O ports are provided through which all I/O operations are performed. On one side, the port is connected to a file or device and inside the program it is connected to one or more I/O variables. For example:

File unit number I/O variable name ENGLISH.SNO ----> 5 ------> 'INPUT' This is accomplished with the call: INPUT('INPUT',5,80,'ENGLISH.SNO','-vl') The first parameter (vname) gives the name of the variable to be used inside the program to accomplish the reads. The second parameter (unitn) gives the I/O unit number (port number) in the range 1 through 999. The third parameter (buflen) gives the maximum record length to be read (longer records are truncated) (this defaults to 80 if you omit the operand). The third parameter is ignored for directory reads (when the fifth parameter is "-dir"). The fourth parameter (fname) gives the path name to the file or directory. The fifth parameter specifies any modifiers you wish to apply. In this case, the file named "ENGLISH.SNO" will be read using the input variable "INPUT", through unit 5, with a maximum record length of 80, and a modifier (-vl) indicating that variable length records are to be read instead of fixed length 80 records.

If the fourth parameter is omitted, the record length can be changed or additional I/O variable names can be associated with the unit number. Also, if the fourth operand is omitted, the file name can be specified on the command line used to invoke SNOBOL5:

SNOBOL5 -5 ENGLISH.SNO -vl

A file is not opened until its first use.

The output function is the counterpart for writing to files. See the section on Input/Output for a description of the possible file modifiers.

INT(x) or int(x) converts x into an integer. This function is equivalent to CONVERT(x,'INTEGER').

IO_FINDUNIT() or io_findunit() returns an unused I/O unit number. If there are no free unit numbers available any more, then the function fails. SNOBOL5 supports 999 unit numbers. See the INPUT, OUTPUT, and ENDFILE functions which use I/O unit numbers.

ITEM(x,i1,i2,...) or item(x,i1,i2,...) is used to reference an element of an array or table without using the bracket form of reference (XXX<N>). ITEM returns the <i1,i2,...> element of the array or table x. The following illustrates the use of ITEM.

X = ARRAY(10) Y = ARRAY(4) Y<2> = 'HELLO' X<5> = Y OUTPUT = ITEM(X<5>,2) * The above prints HELLO * The following has invalid syntax OUTPUT = X<5><2>

LOAD(x,y) or load(x,y) The LOAD function is not curently available in this implementation of SNOBOL5.

LOB(x) or lob(x) returns a string of "0" and "1" characters showing the low order bit value for each character in string x. This is useful for making a bit string viewable after a logical operations such as AND, OR, NOR, NAND, XOR, or NOT. For example:

OUTPUT = lob(bit(xor('ABC','abc'))) prints the string "001000000010000000100000"

LOCAL(f,n) or local(f,n) returns the name of the nth local variable for the function with the name given by the string f. For example:

DEFINE('FACT(X)N,Y,Z') OUTPUT = LOCAL('FACT',2)

prints the string 'Y'.

LOG(x) or log(x) returns the natural logarithm of x.

LOG10(x) or log10(x) returns the base 10 logarithm of x.

LOG2(x) or log2(x) returns the base 2 logarithm of x.

LPAD(S,L,C) lpad(S,L,C) pads string S on left so that the result string has length MAX(L,SIZE(S)) by padding on the left with the first character of string C, or with a blank if C is null. Padding occurs if SIZE(S)<.L. Note S is not trimmed before padding so any leading or trailing blanks in S may make it look like it was not properly padded. A use for LPAD is to right align numbers within a field so that when several lines are printed, the numbers appear to line up properly. See the example with RPAD.

MAX(x,y) or max(x,y) returns the arithmetic maximum of x and y. If either operand is REAL, then the result is REAL.

MIN(x,y) or min(x,y) returns the arithmetic minimum of x and y. If either operand is REAL, then the result is REAL.

NAND(x,y) or nand(x,y) returns the logical NAND of the bytes in strings x and y. If x or y is shorter than the other, then trailing zero bytes are assumed for the shorter one. The length of the result is the maximum of lengths of x and y.

NOR(x,y) or nor(x,y) returns the logical NOR of the bytes in strings x and y. If x or y is shorter than the other, then trailing zero bytes are assumed for the shorter one. The length of the result is the maximum of lengths of x and y.

NOT(x) or not(x) returns the logical negation of the bytes in string x.

OPSYN(newfn,oldfn,n) or opsyn(newfn,oldfn,n) makes the operator or function defined by newfn a synonym for the operator or function defined by oldfn. If newfn and oldfn are not operators, the third parameter must be omitted. If newfn or oldfn is an operator, n specifies whether it is unary or binary by giving an integer 1 or 2. The concatenation operator is specified using a string of one blank. If the newfn name is not a SNOBOL5 operator and not a syntactically correct SNOBOL5 function name, it can still be accessed using the APPLY function.

The following:

OPSYN('ADD','+',2)

makes the function ADD perform the same function as the binary '+' operator. If you look back at the DATA() function where the COMPLEX data type was illustrated, the snobol '+' operator can be redefined to also handle complex addition using the following:

DATA('COMPLEX(R,I)') OPSYN('ADD','+',2) DEFINE('CADD(X,Y)') :(CADDEND) CADD IDENT(DATATYPE(X),'COMPLEX') + :S(CADD1) CADD = + DIFFER(DATATYPE(Y),'COMPLEX') + ADD(X,Y) :S(RETURN) X = DIFFER(DATATYPE(X),'COMPLEX') + COMPLEX(X) :(CADD2) CADD1 Y = DIFFER(DATATYPE(Y),'COMPLEX') + COMPLEX(Y) CADD2 CADD = COMPLEX() R(CADD) = ADD(R(X),R(Y)) I(CADD) = ADD(I(X),I(Y)) CADD = EQ(I(CADD)) R(CADD) :(RETURN) CADDEND OPSYN('+','CADD',2)

OR(x,y) or or(x,y) returns the logical OR of the bytes in strings x and y. If x or y is shorter than the other, then trailing zero bytes are assumed for the shorter one. The length of the result is the maximum of lengths of x and y.

OUTPUT(vname,unitn,format,fname,mods) or output(vname,unitn,format,fname,mods) is used to associate a SNOBOL5 output variable name with an external unit number and optionally specify the file name (or path name) along with the file modifiers. This function is usually used in one of two ways. First, using just the first three parameters, and second with all five operands. The fourth and fifth parameters is an extension over the definition contained in the green book. They permit the specification of the file name along with optional file modifiers.

DOS file unit number I/O variable name LISTING <------- 6 <------ 'OUTPUT' This is accomplished with the call: OUTPUT('OUTPUT',6,,'LISTING') The first parameter (vname) gives the name of the variable to be used inside the program to accomplish the writes. The second parameter (unitn) give the I/O unit number (port number) in the range 1 through 999. The third parameter is ignored and in prior versions of SNOBOL gave a FORTRAN format to be used in formatting the output. The fourth parameter (fname) gives the path name to the file and the fifth parameter specifies any modifiers you wish to apply. In the above example, the file named "LISTING" will be written using the output variable "OUTPUT", through unit 6.

If the fourth and fifth parameters are omitted, additional output variable names can be associated with the unit number. Also, if the fourth operand is omitted, the file name can be specified on the command line used to invoke SNOBOL5:

SNOBOL5 -5 ENGLISH.SNO -VL -6 LISTING The INPUT function is the counterpart for reading files. See the section on Input/Output for a description of possible file modifiers in the fifth parameter.

PROTOTYPE(a) or prototype(a) returns the prototype used to create array a. See the the p parameter on the ARRAY function. The following:

X = ARRAY('3,-1:1') Y = PROTOTYPE(X)

sets Y to the value '3,-1:1'.

R2BYTES(x) or r2bytes(x) This converts the real X to a string of 8 bytes in IEEE 754 standard double precision, little endian form. The leftmost byte is the low order one.

R2BYTESS(x) or r2bytess(x) This converts the real X to a string of 4 bytes in IEEE 754 standard single precision, little endian form. The leftmost byte is the low order one.

R2BYTESX(x) or r2bytesx(x) This converts the real X to a string of 10 bytes in IEEE 754 standard extended precision, little endian form. The leftmost byte is the low order one.

R2HEXS(x) or r2hexs(x) This function returns the hexadecimal digit representation of x as a single precision encoding. The input x must be of type REAL or the function returns failure. The result is returned in the form of a string of eight characters, zero ("0") through ("A"). The high order hex digit is the first character in the result string. The result is in big endian format with the most significant hex digit coming first. The real numbers are encoded per the IEEE 754 Standard. See the related inverse function hexs2r(x).

R2HEXX(x) or r2hexx(x) This function returns the hexadecimal digit representation of x as an extended double precision encoding. The input x must be of type REAL or the function returns failure. The result is returned in the form of a string of 20 characters, zero ("0") through ("A"). The high order hex digit is the first character in the result string. The result is in big endian format with the most significant hex digit coming first. The real numbers are encoded per the IEEE 754 Standard. See the related inverse function hexx2r(x).

RAND(x) or rand(x) returns the a random integer. When x is not null or zero, it is used to set the random number generator seed. The distribution of the random numbers is not guaranteed. The number returned can be in the range of -9223372036854775808 to +9223372036854775807.

REAL(x) or real(x) converts x into a REAL. This function is equivalent to CONVERT(x,'REAL').

REMDR(x,y) or remdr(x,y) returns the integer remainder from the division of the integer x by the integer y. The sign of the remainder is the same as that of x. REMDR(14,12) gives 2.