Zbex functions
| Previous chapter Relations |
Zbex Manual |
Next Chapter Procedures |
The Zbex language includes a number of functions. The purpose of functions is to facilitate the writing of Zbex programs and to increase the speed of these programs. Functions can be used in assignment statements any place a normal variable can be used. Functions are classified by the data type of their output. Non-string and non-bit string functions can appear in relations.
Functions with integer output
| Function | Output |
|---|---|
| rnd(int) | deliver a random number between 0 and <input> |
| not(int) | ones complement of <input> |
| abs(int) | absolute value of <input> |
| and(int,int) | for input (x,y), output = x & y |
| ior(int,int) | for input (x,y), output = x | y |
| xor(int,int) | for input (x,y), output = x exclusive or y |
| bit(int,int) | for input (x,y), output = bit x of y (0 is low order) |
| shr(int,int) | for input (x,y), output = shift x right y bits |
| shl(int,int) | for input (x,y), output = shift x left y bits |
| tst(table) | output = number of entries in the table tst also resets the sequential tget |
| tdx(table,str) | output = index number for key (second input) or 0 if the given key is not present |
| fix(real) | integer value of real number input |
| len(str) | length of input string |
| int(str) | integer value of string of digits, including the unitary plus or minus sign. The function skips leading blanks and also sets the sub variable to subscript of terminating (non-digit) byte or to len(str) + 1 |
| ors(str) | integer value of bit pattern in first 4 (or less) bytes of the string input |
| len(bstr) | byte length of padded bit string input |
| bln(bstr) | bit length of bit string input |
Functions with real number output
| Function | Output |
|---|---|
| flt(int) | convert integer value to real number |
| rnd(real) | deliver a random number between 0 and <input> |
| abs(real) | absolute value of <input> |
| dec(real) | decimal part of <input> |
| sin(real) | for input (x), output = sin(x) |
| cos(real) | for input (x), output = cos(x) |
| tan(real) | for input (x), output = tan(x) |
| ars(real) | for input (x), output = arcsin(x) |
| arc(real) | for input (x), output = arccos(x) |
| art(real) | for input (x), output = arctan(x) |
| exx(real) | for input (x), output = (e to the x power) |
| lnx(real) | for input (x), output = (log base e of x) |
| sqt(real) | for input (x), output = square root of x |
| pow(real,real) | for input (x,y), output = x to the y power (x,y > 0) |
| flt(str) | real value of string of digits, including the unitary plus or minus sign. The function skips leading blanks and also sets the sub variable to subscript of terminating (non-digit) byte or to len(str) + 1. |
Functions with string output
| Function | Output |
|---|---|
| pad(int) | add blanks to the end of the current right hand string, up to a length of <input> number. |
| zpd(int) | add nulls (the zero byte) to the end of the current right hand string, up to a length of <input> number. |
| chr(int) | single string character with a bit pattern that matches the lower eight bits of <input> |
| ch2(int) | two character string with a bit pattern that matches the lower sixteen bits of <input> |
| ch4(int) | four character string with a bit pattern that matches the <input> |
| oct(int) | ASCII octal representation of <input> |
| chs(int) | ASCII decimal representation of <input> including the unitary minus sign |
| hex(int) | ASCII hexidecimal representation of <input> |
| ch8(real) | eight character string with a bit pattern that matches the <input> |
| chs(real,int) | ASCII decimal representation of <real input> with <int input> digits to right of decimal. Includes unitary minus sign |
| chx(real,int) | ASCII floating point representation of <real input> with <int input> digits to right of decimal. Includes unitary minus sign |
| trm(str) | input string without the trailing blanks |
| mrt(str) | input string without the leading blanks |
| lcs(str) | input string with all letters converted to lower case |
| ucs(str) | input string with all letters converted to upper case |
| rev(str) | string with characters in the reverse order from the input string |
| rpl(str,s(n,2)) | create an output string from the first input string in following way: Working from left to right in the input string, search the string array s(i,1) (i = 1,...,n) for a match in the input string. If a match is found (at i), place s(i,2) in the output string and advance the test point in the input string by len(s(i,1)). If no match is found, copy the current byte to the output string and advance the test point one byte. |
| dup(str,int) | input string duplicated <int input> number of times |
| txt(s1,bs,int) | output string = s1{m..n-1} where m (>= int) is the subscript of first byte of the input string (at or beyond <int input>) which is not in the bit string set bs, and n (> m) is the subscript of the first byte of the input string (beyond m) which is in the bit string set bs. <int input> is set to the value n by this function. Essentially, characters in the bit string set bs are used to sub-divide or parse the input string. The function is designed for repeated calls until the input string is completely parsed.
The format for specifying the bit string set bs is: set(bstr) where bstr is a bit string. |
| txt(s1,bs) | same as previous function, except the special variable mpt is used in place of the third input. |
| txt(s1,[ ],int) | same as the first txt function, except the set [ ] is used instead of the bit string set. |
| txt(s1,[ ]) | same as the second txt function, except the set [ ] is used instead of the bit string set. |
| cby(bstr) | create output string with the same bit pattern as the input bit string (padded to the byte boundary with zeros) |
| upk(bstr,s2) | construct a string from the first <input> in the following way: 1 maps to s2{1} or 'x', 0 maps to s2{2} or ' '. |
| upk(bstr) | construct a string from the first <input> in the following way: 1 maps to 'x', 0 maps ' '. |
Functions with bit string output
| Function | Output |
|---|---|
| npd(int) | add ones to the end of the current right hand bit-string, up to a length of <input> number. |
| zpd(int) | add zeros to the end of the current right hand bit-string, up to a length of <input> number. |
| cbi(str) | create output bit string with the same bit pattern as the input string |
| pak(s1,s2) | construct a bit string from the first input string as follows: for each byte, if byte = s2{1} put in a one, otherwise put in a zero. |
| pak(str) | construct a bit string from the input string as follows: for each byte, if byte = 'x', put in a one, otherwise put in a zero. |
| trm(bstr) | input bit string without the trailing zeros |
| mrt(bstr) | input bit string without the leading zeros |
| rev(bstr) | bit string with bits in the reverse order from the input bit string |
| cmp(bstr) | 1's complement of input bit string |
| dup(bstr,int) | input bit string duplicated <int input> number of times |
| bnd(bstr,bstr) | output = intersection of two inputs |
| bor(bstr,bstr) | output = union of two inputs |
Function with a set output
| Function | Output |
|---|---|
| set(bstr) | create a set in the following way: Pad the input bit string with zeros up to a length of 256. For each of the 256 bits in the bit string, if the bit is a one, add the number of the position to the set; if the bit is a zero, do not add the number of the position to the set. |
Overloaded output
There are thirteen sets of ambiguous functions. In each case, there is a way for the compiler to distinguish which function is being called.
| Function | Output Type | ||
|---|---|---|---|
| 1. | rnd(int) | int | distinguished by |
| rnd(real) | real | output type. | |
| 2. | abs(int) | int | distinguished by |
| abs(real) | real | output type. | |
| 3. | len(str) | int | distinguished by |
| len(bstr) | int | input variable type. | |
| 4. | flt(int) | real | distinguished by |
| flt(str) | real | input variable type. | |
| 5. | zpd(int) | str | distinguish by |
| zpd(int) | bstr | output type. | |
| 6. | chs(int) | str | distinguish by number |
| chs(real,int) | str | of arguments. | |
| 7. | trm(str) | str | distinguish by |
| trm(bstr) | bstr | output type. | |
| 8. | mrt(str) | str | distinguish by |
| mrt(bstr) | bstr | output type. | |
| 9. | rev(str) | str | distinguish by |
| rev(bstr) | bstr | output type. | |
| 10. | dup(str) | str | distinguish by |
| dup(bstr) | bstr | output type. | |
| 11. | txt(s1,bs,int) | str | distinguish by type |
| txt(s1,bs) | str | of second argument | |
| txt(s1,[ ],int) | str | and by presence | |
| txt(s1,[ ]) | str | of third argument. | |
| 12. | upk(bstr,s2) | str | distinguish by number |
| upk(bstr) | str | of arguments. | |
| 13. | upk(s1,s2) | str | distinguish by number |
| upk(str) | str | of arguments. | |
Function example usage
We include some examples of how various functions work. The focus is mainly on those functions whose operation may not be clear from the description.
tst(table)
The tst(table) function. This function reports on the number of enteries in the table, and resets the counter for the sequentail version of the tget command. To demonstrate this function, we must fill a table with some items and use the sequential version of tget to retrieve them.
Program
---------------------
str a.10,b.10
int i
table X(1000)
loop for i = 1 to 10 /* create 10 entries in table
a = "Key " // chs(i) /* str a will contain the "key"
tput [X,a] Item ~i
repeat
loop for i = 1 to 3 /* get first 3 entries
tget [X] a b
putc ~a ~b
repeat
i = tst(X)
putc Number of entries = ~i
loop for i = 1 to 3 /* check to see that sequential
tget [X] a b /* counter has been reset
putc ~a ~b
repeat
run
Execution
-------------------------------------
** S=18, P=79, L=253, M=1418 **
Key 1 Item 1
Key 2 Item 2
Key 3 Item 3
Number of entries = 10
Key 1 Item 1
Key 2 Item 2
Key 3 Item 3
Ready for program
tdx(table,str)
The tdx(table,str) function. This function provides the index number in a table for a given "key". The number is 0 if there is no such key in the table. To demonstrate this function, we must fill a table with some key/record pairs and then use the tdx function to get their index numbers.
Program
---------------------
str a.10,b.10
int i,j
table X(1000)
loop for i = 1 to 10 /* create 10 entries in table
a = "Key " // chs(i) /* str a will contain the "key"
tput [X,a] Item ~i
repeat
loop for i = 1 to 3 /* get index for first 3 entries
a = "Key " // chs(i)
j = tdx(X,a)
putc key = ~a index = .w4 ~j ...
tget [X,j] b /* retrieve record via index
putc record = ~b
repeat
run
Execution
-------------------------------------
** S=15, P=75, L=255, M=1418 **
key = Key 1 index = 313 record = Item 1
key = Key 2 index = 58 record = Item 2
key = Key 3 index = 187 record = Item 3
Ready for program
fix(real)
The fix(real) function. The reason we need this function is that Zbex does not automatically convert real numbers to integers.
Program
---------------------
int i
real x
x = 456.789
i = fix(x)
putc real input = ~x integer output = ~i
run
Execution
-------------------------------------
** S=6, P=28, L=236, M=410 **
real input = 456.79 integer output = 456
Ready for program
len(str)
The len(str) function. When used on the right hand side of an assignment statement, this function gives the length of the string argument. What makes this function unusual is that it can also be used on the left hand side of an assignment statement to set the length of a string. This is particularly valuable when we use a string as a buffer for the read instruction, since the size of the block read = the length of the string.
Program
---------------------
str a.80
int i
a = "For the last time, Mr. Smee, take the princess home!"
i = len(a)
putc Length of string a is ~i
len(a) = 28
i = len(a)
putc New length of string a is ~i
putc String a = "~a "
run
Execution
-------------------------------------
** S=10, P=59, L=255, M=431 **
Length of string a is 52
New length of string a is 28
String a = "For the last time, Mr. Smee,"
Ready for program
int(str)
The int(str) function. This function reads a group of digits in a string and returns their value as an integer. The setting of the special variable sub to the subscript of the the terminating (non-digit) byte in the string allows this function to be called again to get the next number in the string.
Program
---------------------
str a.80
int i
a = "1000 500 -39 465 678687"
putc Getting numbers from a string
putc a = "~a "
putc Numbers
putc -------
sub = 0
loop while sub < len(a)
i = int(a{sub+1..})
putc .w7 ~i .w2t20 (terminating subscript = ~sub )
repeat
run
Execution
-------------------------------------
** S=13, P=72, L=248, M=431 **
Getting numbers from a string
a = "1000 500 -39 465 678687"
Numbers
-------
1000 (terminating subscript = 5)
500 (terminating subscript = 10)
-39 (terminating subscript = 19)
465 (terminating subscript = 25)
678687 (terminating subscript = 32)
Ready for program
ors(str)
The ors(str) function. This function reads the first four bytes of the string argument (less if the string is shorter) and creates an integer value from the bit pattern.
Program
---------------------
str a.4
int i
a = "."
i = ors(a)
putc a = "~a " .t13 i = ~i .t30x (hex ~i )
a = ".1"
i = ors(a)
putc a = "~a " .t13 i = ~i .t30x (hex ~i )
a = ".123"
i = ors(a)
putc a = "~a " .t13 i = ~i .t30x (hex ~i )
run
Execution
-------------------------------------
** S=12, P=95, L=249, M=412 **
a = "." i = 46 (hex 2e)
a = ".1" i = 11825 (hex 2e31)
a = ".123" i = 774976051 (hex 2e313233)
Ready for program
pad(int)
The pad(int) function. This function adds blanks to the end of the string on the right hand side of an assignment statement up to the length specified by the integer argument. If the string is already longer than the specified length, nothing is done.
Program
---------------------
str a.80,b.80
int i
a = "This is a short string"
b = "This is a slightly longgggerrrrrr string"
putc a = "~a "
a = a // pad(30)
putc a = "~a "
putc b = "~b "
b = b // pad(30)
putc b = "~b "
run
Execution
-------------------------------------
** S=11, P=54, L=262, M=452 **
a = "This is a short string"
a = "This is a short string "
b = "This is a slightly longgggerrrrrr string"
b = "This is a slightly longgggerrrrrr string"
Ready for program
ch4(int)
The ch4(int) function. This function is the opposite of the ors function. It creates a four byte string from the bit pattern of the integer argument.
Program
---------------------
str a.4
int i
i = 0x31323334 /* this is hexidecimal notation
a = ch4(i)
putc a = "~a "
run
Execution
-------------------------------------
** S=6, P=19, L=237, M=412 **
a = "1234"
Ready for program
chs(int)
The chs(int) function. This function constructs a string which is the ASCII decimal representation of the integer argument. We illustrate also the hex(int) function here.
Program
---------------------
str a.80,b.80
int i
a = ""
b = ""
loop for i = 500 to -300 step -100
a = a // chs(i) // " "
b = b // hex(i) // " "
repeat
putc a = "~a "
putc b = "~b "
run
Execution
-------------------------------------
** S=11, P=55, L=247, M=452 **
a = "500 400 300 200 100 0 -100 -200 -300 "
b = "1f4 190 12c c8 64 0 ffffff9c ffffff38 fffffed4 "
Ready for program
rpl(str,s(n,2))
The rpl(str,s(n,2)) function. This somewhat unwieldy function is intended to facilitate the translation of certain string patterns into alternate string patterns for large blocks of text at a time. rpl is short for replace. The second argument is an array of patterns and their replacements.
Program
---------------------
str a.500, b.500, c.10(1,2)
/* set up initial string for testing
a = "The purpose of this function is to facilitateCRthe"
a = a // " translation of certain string patterns intoCRother"
a = a // " string patterns. In this example, we willCRchange"
a = a // " a code for carriage return into the escapeCR"
a = a // "sequences which will generate real carriageCR"
a = a // "returns.CR"
/* set up conversion matrix
c(1,1) = "CR"
c(1,2) = chr(27) // "S" // chr(27) // "Y"
/* do the translation
b = rpl(a,c)
/* display results
putc ~b
run
Execution
-------------------------------------
The purpose of this function is to facilitate
the translation of certain string patterns into
other string patterns. In this example, we will
change a code for carriage return into the escape
sequences which will generate real carriage
returns.
Ready for program
txt(st1,bs,int)
The txt(s1,bs,int) function. This is the most complicated of the four forms of the txt function. The purpose of this function is to allow the rapid parsing of strings, based on a set of bytes one might call "delimiter bytes." In this version of the function, the set is determined by a bit string.
Program
---------------------
str a.100, b.100
bstr pset.256
int i
a = "Let us, please, ignor (i.e., disregard) all"
a = a // " non-alpha characters in our parse!! O.K.?"
pset = npd(65) // zpd(91) // npd(97) // zpd(123) // npd(256)
i = 0
loop while i < len(a)
b = txt(a, set(pset), i)
b = txt(a, [0..64,91..96,122..255], i) will also work
if b <> ""
putc ~b
end
repeat
run
Execution
-------------------------------------
** S=14, P=52, L=283, M=471 **
Let
us
please
ignor
i
e
disregard
all
non
alpha
characters
in
our
parse
O
K
Ready for program
upk(bstr,s2)
The upk(bstr,s2) function. This function creates a string with two types of characters. The pattern matches that of the bit string argument.
Program
---------------------
str a.50,b.2
bstr pattern.50(10)
int i
b = "▒█"
pattern(1) = "0001111111000"
pattern(2) = "0111111111110"
pattern(3) = "1110000000111"
pattern(4) = "1100110110011"
pattern(5) = "1100001000011"
pattern(6) = "1100100010011"
pattern(7) = "0110011100110"
pattern(8) = "0111000001110"
pattern(9) = "0001111111000"
loop for i = 1 to 9
a = upk(pattern(i), b)
putc ~a
repeat
run
Execution
═════════════════════════════════════
** S=18, P=90, L=267, M=456 **
███▒▒▒▒▒▒▒███
█▒▒▒▒▒▒▒▒▒▒▒█
▒▒▒███████▒▒▒
▒▒██▒▒█▒▒██▒▒
▒▒████▒████▒▒
▒▒██▒███▒██▒▒
█▒▒██▒▒▒██▒▒█
█▒▒▒█████▒▒▒█
███▒▒▒▒▒▒▒███
Ready for program
| Previous chapter Relations |
Zbex Manual |
Next Chapter Procedures |