The functions in this category are divided in the following classes:

• stacks;
• queues;
• bit maps;
• arrays;
• sets;
• AVL trees.

Stacks

These functions can be used to deal with LIFO queues.

STACKCREATE([el1[, el2..]])

creates a new stack with the specified items; same as using STACKNEW() followed by PUSH(el1), PUSH(el2), etc.; returns the handle to the new stack

STACKNEW()

creates a new stack and returns its handle; it is necessary to invoke STACKFREE on the handle as soon as the stack is no longer needed

STACKFREE(pHandle)

frees the memory for the stack pHandle; returns 0 on success, -1 if the handle is invalid

STACKDUP(pHandle)

returns the handle of a new stack which is the exact copy of the stack pHandle; returns -1 if pHandle is invalid

STACKHEIGHT(pHandle)

returns the number of items in the stack, -1 if the handle is invalid

PUSH(pHandle, exp1[, exp2..])

pushes the items exp1, exp2.. in the stack; returns 0 on success, -1 if the handle is invalid

POP(pHandle)

returns the item on top of pHandle and removes it; returns an empty string if the handle is invalid or the stack is empty

STACKTOP(pHandle, nOffset)

returns the item at nOffset from the top of the stack, without removing it; if nOffset is 0, this function is the same as POP without item removal; STACKTOP returns an empty string if the handle is invalid or nOffset is greater than or equal to the number of items in the stack

STACKDEL(pHandle, nOffset, nNumber)

deletes nNumber items from the stack, starting from nOffset; returns the number of items removed if the operation was successfull, -1 otherwise; if nOffset is 0 and nNumber is 1, this function is the same as POP where the returned value is discarded

STACKINS(pHandle, nOffset, exp1[, exp2..])

pushes exp1, exp2.. in the stack from nOffset; returns 0 if the operation is successfull, -1 otherwise; if nOffset is 0, this functions is the same as PUSH

Queues

These functions can be used to deal with FIFO queues.

QUEUECREATE([el1[, el2..]])

creates a new queue containing the specified items; same as calling QUEUENEW() followed by ENQUEUE(el1), ENQUEUE(el2), etc.; returns the handle to the newly created queue

QUEUENEW()

creates a new queue and returns its handle; it is necessary to invoke QUEUEFREE on the handle as soon as the queue is no longer needed

QUEUEDUP(qHandle)

returns the handle of a new queue which is the exact copy of the queue identified by qHandle; returns -1 if qHandle is invalid

QUEUEFREE(qHandle)

frees the memory associated to the queue qHandle; returns 0 if the operation was succesfull, -1 if the handle is invalid

QUEUELEN(qHandle)

returns the length of the specified queue, -1 if the handle is invalid

ENQUEUE(qHandle, exp1[, exp2..])

inserts the items exp1, exp2.. into the queue identified by qHandle; returns 0 on success, -1 if the handle is invalid

DEQUEUE(qHandle)

returns the item at the beginning of the queue identified by qHandle and removes it; returns an empty string if the handle is invalid or if the queue is empty

QUEUETOP(qHandle, nOffset)

returns the item at nOffset from the beginning of the queue, without removing it; if nOffset is 0, this function is similar to DEQUEUE, but without removal

QUEUEDEL(qHandle, nOffset, nNumber)

removes nNumber items from the queue, starting at nOffset from the beginning; returns the number of items removed on success, -1 otherwise; if  nOffset is 0 and nNumber is 1, this function is similar to DEQUEUE (the return value is ignored)

QUEUEINS(qHandle, nOffset, exp1[, exp2..])

inserts the items exp1, exp2.. in the queue, starting at nOffset from the beginning of the queue; returns 0 on success, -1 otherwise; if nOffset is 0, this function is similar to ENQUEUE

OENQUEUE(qHandle, exp1[, exp2..])

inserts at the beginning of the queue identified by qHandle the items exp1, exp2..; returns 0 on success, -1 if the handle is invalid

ODEQUEUE(qHandle)

returns the item at the end of the queue identified by qHandle and removes it; returns an empty string if the handle is invalid or the queue is empty

OQUEUETOP(qHandle, nOffset)

returns the item at nOffset from the end of the queue, without removing it; if nOffset is 0, this function is similar to ODEQUEUE (but without removal)

OQUEUEDEL(qHandle, nOffset, nNumber)

removes nNumber items starting at position nOffset from the end of the queue; returns the number of items removed on success, -1 otherwise; if nOffset is 0 and nNumber is 1, this function is similar to ODEQUEUE (return value is ignored)

OQUEUEINS(qHandle, offset, exp1[, exp2..])

inserts exp1, exp2, .. in the queue, starting at nOffset from the end of the queue; returns 0 if the operation is successfull, -1 otherwise; if nOffset is 0, this function is similar to OENQUEUE

Bit maps

The bitmap functions allow to keep many boolean values using a little memory (1 byte for 8 items, starting with offset 0).

BITMAPNEW()

creates a new bitmap and returns its handle; all the items are 0 (== false) at the beginning; the user should invoke BITMAPFREE on the handle as soon as the bitmap is no longer necessary

BITMAPDUP(bHandle)

returns the handle to a new bitmap, which is the exact copy of the bitmap corresponding to bHandle; returns -1 if bHandle is invalid

BITMAPSET(bHandle, nNumber, nBit)

sets the status for item nNumber (>= 0) in the bitmap bHandle to the value of nBit (0 or non-0); returns -1 if bHandle is invalid or nNumber is negative, 0 otherwise

BITMAPRSET(bHandle, nOffset, nNumber, nBit)

sets the status for items nOffset, nOffset+1, .., nOffset+nNumber-1 (nOffset >= 0) in the bitmap bHandle to the value nBit (0 or non-0); returns -1 if bHandle is invalid or nOffset is negative, 0 otherwise

BITMAPGET(bHandle, nOffset)

returns the status for item nOffset (>= 0) in the bitmap bHandle; returns -1 if bHandle is invalid or nOffset is negative, 0 otherwise

BITMAPPACK(bHandle)

packs the bitmap, freeing the memory reserved for the last items whose value is 0; returns -1 if the handle is invalid, 0 otherwise

BITMAPRESET(bHandle)

sets all the items to 0, but does not free the handle; returns -1 if the handle is invalid, 0 otherwise

BITMAPFREE(bHandle)

frees the memory reserved to the bitmap bHandle (the handle becomes no longer valid); returns -1 if the specified handle is invalid, 0 otherwise

BITMAPTOSTR(bHandle)

returns the string underlying the bitmap; if bHandle is invalid, returns an empty string

BITMAPFROMSTR(c)

returns the handle of a new bitmap, which is created from the string c

TIFFPACK([@]c)

packs the string c according to TIFF 4.0

TIFFUNPACK([@]c)

unpacks string c, which was compressed according to TIFF 4.0

TIFFPACK and TIFFUNPACK can be used on any string, even though they are especially useful in this context.

Arrays

Arrays in Proteus are one-dimensional; an array is not a variable, but a memory structure accessed using a handle. The number of items in an array is limited by the largest positive integer number.
An array is created using VECNEW, which is invoked specifying the number of items which the array will hold: the specified parameter cannot be negative.
It is possible to create arrays without items, because using VECSIZE they can be later enlarged (this functions allows also to shrink arrays).
All the items are initially set to "" = 0 = 0.0; the function VECSET is used to modify the value of an item, which can be retrieved using VECGET.
VECLEN returns the number of items in the array.

Item indexes go from 1 to the size specified by VECNEW or the last call to VECSIZE. To free the memory reserved for the array, use VECFREE.

VECCREATE([exp[,exp..]])

creates an array holding all the specified items; if no item is specified, the array is created empty; this function returns the handle of the array

VECNEW(n)

creates an array of n null items; returns the handle of the array or -1 if n < 0

VECDUP(vHandle)

returns the handle to a new array, which is the exact copy of the array corresponding to vHandle; returns -1 if vHandle is invalid

VECSIZE(vHandle, nLength)

changes the size of the array vHandle to nLength; if nLength < 0 or vHandle is invalid, returns -1, otherwise the new size of the array

VECLEN(vHandle)

returns the number of items in vHandle, or -1 if vHandle is invalid

VECFREE(vHandle)

frees the memory reserved for the array vHandle; returns 0 if successfull, -1 if vHandle is invalid

VECSET(vHandle, nOffset, exp)

sets to exp the value of the item at nOffset (> 0) in the array vHandle; returns -1 if vHandle is invalid or nOffset is out of range, 0 otherwise

VECGET(vHandle, nOffset)

returns the value of the item at nOffset (> 0) in the array vHandle, a null value if vHandle is invalid or nOffset is out of range

VECDEL(vHandle, nOffset, nNumber)

deletes nNumber items from the array vHandle starting from nOffset (included)

VECINS(vHandle, nOffset, nNumber)

inserts nNumber items into the array vHandle starting from nOffset (included)

VECLAST(vHandle)

returns the last item of the array vHandle; same as VECGET(h, VECLEN(h))

VECSHRINK(vHandle)

decreases by one the size of the array vHandle; same as VECSIZE(h, DEC(VECLEN(h)))

VECAPPEND(vHandle, exp1[, exp2..])

appends the items exp1, exp2, .. to the end of the array vHandle (the size is increased by the number of the items added)

VECJOIN(vHandle, cSeparator)

returns a string with all the items in vHandle separated by the first character in cSeparator; this function returns an empty string if vHandle is invalid

VECSPLIT(c, cSeparators)

creates an array holding all the tokens (=sequences of characters) in c delimited by characters in cSeparators; returns the handle of the new array (which is empty only if c or cSeparators are empty).
NOTE: Unlike dynamic and static tokenizers, this function adds an item for each encountered separator (an item can be empty).
e.g. VECSPLIT("1,2,,4,5", ",") determines the array {[1] [2] [] [4] [5]}, holding 5 items, while NUMTOKEN("1,2,,4,5", ",") = 4

VECREXSPLIT(c, xExp)

creates an array holding all the tokens (=sequences of characters) in c delimited by characters that match the extended regular expression xExp; this function returns the handle of the new array (which is empty only if c is empty). See also VECSPLIT

VECREXISPLIT(c, xExp)

creates an array holding all the tokens (=sequences of characters) in c delimited by characters that match the extended regular expression xExp (case-insensitive comparison); this function returns the handle of the new array (which is empty only if c is empty). See also VECSPLIT

VECREXMATCH(c, xExp)

returns the handle of an array holding the substrings of c that match the extended regular expression xExp

VECREXIMATCH(c, xExp)

returns the handle of an array holding the substrings of c that match the extended regular expression xExp (case-insensitive comparison)

VECTOSET(vHandle)

returns the handle of a new set created from the array vHandle by considering the odd items as labels and the even items as values; returns -1 if vHandle is invalid

VECTOAVL(vHandle)

returns the handle of a new AVL tree created from the array vHandle by considering the odd items as labels and the even items as values; returns -1 if vHandle is invalid

You can search and sort arrays by using the following functions:

SORT(vHandle, nSortType, nDirection)

sorts the array vHandle according to nSortType and nDirection (two integers); nSortType determines the type of sorting (see common.prt):

Constant	Value	Meaning
SORT_STRING	0	sort as strings (case-sensitive)
SORT_INTEGER	1	sort as integers
SORT_FLOAT	2	sort as floating point numbers
SORT_DATE	3	sort as dates
SORT_ISTRING	4	sort as strings (case-unsensitive)
	other	same as 0

nDirection determines the direction for sorting:

Constant	Value	Meaning
SORT_DESCENDING	0	descending
SORT_ASCENDING	1	ascending

This function returns -1 if the handle is invalid, 0 otherwise

SCAN(vHandle, nSearchType, exp)

does a linear search on the array vHandle for the value exp by using the comparison determined by nSearchType (see common.prt):

Constant	Value	Meaning
SORT_STRING	0	string (case-sensitive)
SORT_INTEGER	1	integer
SORT_FLOAT	2	floating point number
SORT_DATE	3	date
SORT_ISTRING	4	string (case-insensitive)
SORT_MATCH	5	string (MATCH)
SORT_IMATCH	6	string (IMATCH)
SORT_REXMATCH	7	string (REXMATCH)
SORT_REXIMATCH	8	string (REXIMATCH)
	other	same as 0

This function returns -1 if the handle is invalid, 0 if the expression was not found, the corresponding index in the array otherwise

BSEARCH(vHandle, nSearchType, exp)

does a binary search on the array vHandle, assuming that it is already ordered; the type of comparison is determined by nSearchType, whose values are the same used by SCAN, except for 5..8 (MATCH, IMATCH, REXMATCH and REXIMATCH do not establish a relative sort order):

Constant	Value	Meaning
SORT_STRING	0	string (case-sensitive)
SORT_INTEGER	1	integer
SORT_FLOAT	2	floating point number
SORT_DATE	3	date
SORT_ISTRING	4	string (case-unsensitive)

This function returns -1 if the handle is invalid, 0 if the expression was not found, the corresponding index in the array otherwise

SORTUDF(vHandle, FUNC)

sorts the array vHandle by using the UDF FUNC; this function must accept two parameters, corresponding to the two items to be compared, and return:

• 0 the items are equal
• <0 item #1 precedes item #2
• >0 item #1 follows item #2

SCANUDF(vHandle, exp, FUNC)

does a linear search for exp on the array vHandle by using the UDF FUNC; FUNC takes two parameters and returns 0 if and only if the item currently evaluated corresponds to the value of exp; returns -1 if the handle is invalid, 0 if the expression was not found, the corresponding index in the array otherwise

BSEARCHUDF(vHandle, exp, FUNC)

does a binary search for exp on the array vHandle, assuming that it is ordered according to the underlying order determined by the UDF FUNC; this function takes two parameters, corresponding to the two items to be compared, and returns:

• 0 the items are equal
• <0 item #1 precedes item #2
• >0 item #1 follows item #2

This function returns -1 if the handle is invalid, 0 if the expression was not found, the corresponding index in the array otherwise

All the functions using UDF (SORTUDF, SCANUDF, BSEARCHUDF) require the name of a function, without parenthesis or parameters; this name must be specified literally, it can not be included in a string. The UDF must be defined (before or after) as accepting two parameters.

Sets

The functions on sets allows to insert and retrieve items by using a key, which can be a string, an integer or a floating point number. A set in Proteus is similar to an associative array in Perl™.

SETNEW()

creates an empty set and returns its handle

SETCREATE([lab,exp[lab2,exp2..]])

creates a new set holding the specified items; if the number of specified parameters is odd, the last item takes a null value; this function returns the handle of the newly created set

SETDUP(sHandle)

returns the handle of a new set, which is the exact copy of the set corresponding to sHandle; returna -1 if sHandle is invalid

SETFREE(sHandle)

frees the memory reserved for the set sHandle; returns -1 if sHandle is invalid, 0 otherwise

SETSET(sHandle, key, value)

adds to the set sHandle the item (key, value); returns -1 if sHandle is invalid, 0 otherwise; if the set already contained an item with the same key, updates its value

SETGET(sHandle, key)

returns the value associated to key in the set sHandle, an empty string on error

SETBELONG(sHandle, key)

returns 1 if key belongs to the set sHandle, 0 if it does not, -1 if sHandle is invalid

SETDEL(sHandle, key)

removes the item associated to key in the set corresponding to sHandle; returns 1 if the item was succesfully removed, 0 if the item was not found, -1 if sHandle is invalid

SETLENGTH(sHandle)

returns the number of items in the set sHandle (-1 if the handle is invalid)

SETFIRST(sHandle)

positions the pointer to the first element in the set; returns 0 if the set is empty, -1 if sHandle is invalid, a value greater than 0 otherwise; the first item is not necessarily the first item introduced

SETNEXT(sHandle)

moves the pointer to the next item in the set; this function is used together with SETCURKEY and SETCURVAL. The items are not returned in the order they were added to the set. The functions SETDUP, SETFREE, SETSET, SETGET, SETBELONG, SETDEL, SETFIRST, SETVALUES, SETTOVEC can change the current position; this function returns 0 if there was a wrap (the pointer was repositioned to the first item), -1 if sHandle is invalid, a number different from 0 otherwise

SETCURKEY(sHandle)

returns the key for the current item, an empty string if sHandle is invalid or the set is empty

SETCURVAL(sHandle)

returns the value for the current item, an empty string if sHandle is invalid or the set is empty

SETKEYS(sHandle)

returns the handle of an array holding all the keys in the set sHandle; returns -1 if sHandle is invalid

SETVALUES(sHandle)

returns the handle of an array holding all the values in the set sHandle; returns -1 if sHandle is invalid

SETTOVEC(sHandle)

returns the handle of an array created from the set sHandle, -1 if sHandle is invalid; the new array holds the labels as odd items, the values as even items.

To scan all the items in a set, use the following procedure:

; S is the handle of an existing set
IF SETFIRST(S)
  REPEAT
    CONSOLELN "(" SETCURKEY(S) ", " SETCURVAL(S) ")"
  UNTIL NOT(SETNEXT(S))
FI

AVL trees

The functions on AVL trees allow to quickly insert and retrieve items by using a key, which can be a string, an integer or a floating point number. An AVL tree is a balanced binary tree, in which the difference between the lengths of every left and right subtree of each node is at most 1; AVL trees are so called from the names of their inventors: Adelson, Velskii and Landis. The most peculiar feature of these data structures is that the longest path from the root to each node is at most 2 log n; checking if an item belongs to the tree, inserting or removing a new item have O(log n) complexity, where n is the number of items in the tree.
AVL trees allow to do searches and substitutions very quickly, but have an higher cost if compared to hash sets when inserting or removing items (if this operation triggers a rebalancing of the tree); they are preferable if the application being designed does a lot more searches and substitutions than insertions/deletions. AVL trees allow, moreover, to immediately obtain a list (ordered by key) of all the items. For further information, see the books by Wirth and others.
AVL trees are very useful, powerful and easy to use: with very little effort, they allow to sort items and do quick searches.

AVLNEW()

creates an empty tree and returns its handle

AVLCREATE([lab,exp[lab2,exp2..]])

returns the handle of a new AVL tree holding the specified items; if the number of parameters is odd, the last item will have a null value

AVLDUP(aHandle)

creates a copy of the specified tree; returns a new handle, or -1 if aHandle is invalid

AVLFREE(aHandle)

frees the memory reserved for the tree; returns 0 on success, -1 if the handle is invalid

AVLSET(aHandle, lab, exp)

inserts an item in the tree; returns -1 if aHandle is invalid, 0 if the item was inserted, 1 if it was updated

AVLGET(aHandle, lab)

returns the value for lab in the tree aHandle, an empty string (= 0 = 0.0) on error (invalid aHandle or item not found)

AVLBELONG(aHandle, lab)

returns 1 if the item belongs to the three, 0 otherwise; returns -1 if aHandle is invalid

AVLDEL(aHandle, lab)

deletes an item from the tree; returns -1 if aHandle is invalid, 0 if the item was not found, 1 if it was removed

AVLLENGTH(aHandle)

returns the number of items in the tree, -1 if aHandle is invalid

AVLKEYS(aHandle)

returns the handle of a new array holding the keys of the items in the tree; returns -1 if aHandle is invalid

AVLVALUES(aHandle)

returns the handle of a new array holding the values of the items in the tree; returns -1 if aHandle is invalid

AVLTOVEC(aHandle)

returns the handle of a new array holding the keys (odd indexes) and the values (even indexes) of all the items in the tree aHandle; returns -1 if aHandle is invalid

AVLTRAVERSE(aHandle, udffunction)

pre-order traverse of the tree aHandle. The UDF udffunction is called on each item and must accept only two parameters: label and value; it returns 0 (continue with the next item) or 1 (stop). AVLTRAVERSE returns -1 if aHandle is invalid, 0 if the tree was completely traversed, 1 if the UDF requested to stop. Item labels are returned in ascending order; see also AVLRTRAVERSE

AVLRTRAVERSE(aHandle, udffunction)

post-order traverse of the tree aHandle. The UDF udffunction is called on each item and must accept only two parameters: label and value; it returns 0 (continue with the next item) or 1 (stop). AVLRTRAVERSE returns -1 if aHandle is invalid, 0 if the tree was completely traversed, 1 if the UDF requested to stop. Item labels are returned in descending order; see also AVLTRAVERSE