# Zbex functions

 Previous chapterRelations ZbexManual Next ChapterProcedures

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.

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

```

### 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
```

### 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

```

### 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,"

```

### 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)
```

### 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)

```

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 "
putc a = "~a "
putc b = "~b "
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"
```

### 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"

```

### 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  "
```

### 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.

```

### 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
ignor
i
e
disregard
all
non
alpha
characters
in
our
parse
O
K

```

### 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 **
███▒▒▒▒▒▒▒███
█▒▒▒▒▒▒▒▒▒▒▒█
▒▒▒███████▒▒▒
▒▒██▒▒█▒▒██▒▒
▒▒████▒████▒▒
▒▒██▒███▒██▒▒
█▒▒██▒▒▒██▒▒█
█▒▒▒█████▒▒▒█
███▒▒▒▒▒▒▒███