NAME

usr - subprogram which returns a value

SYNOPSIS

sub usrName[(Arg[, Arg]. . .)] static

. 
. 
. 
[[let] usrName = Expr]
. 
. 
. 
[exit sub]
. 
. 
. 

end sub

DESCRIPTION

A usr function definition is an extension of a subprogram definition in which the subprogram returns a value (see sub).  This construct defines a function whose name begins with "usr." The function name must be a valid variable name.  Elsewhere in the program, the function thus defined may be executed by specifying arguments and referencing the function name with a function call in an expression or in a call statement (see call). 

Within a function, the function’s value is initially set to zero or the null string (depending on the type of the function).  The value of the function may be assigned a new value by the execution of a let statement in the left-hand side of which appears the name of the function.  Execution of the function continues until the appearance of an exit sub or the end sub statement.  If the function was called from an expression, the value of the function is returned and used in evaluating the expression. 

EXAMPLE

The subprogram:

	sub usrhash%(name$, n%, name$(1), link%(1), new%) static
		static i%, j%

		i% = 0
		for j% = 1% to len(name$)
			i% = i% + i% xor asc(mid$(name$, j%, 1))
		next j%
		i% = (i% and 32767) mod n% + 1
		while link%(i%) and name$ <> name$(i%)
			i% = link%(i%)
		wend
		if link%(i%) = 0 then
			name$(i%) = name$
			link%(i%) = new%
			new% = new% + 1
		end if
		usrhash% = i%
	end sub

is a general purpose hash table function.  The arrays "name$" and "link%" are the name and link fields of the data structure elements.  "n%" is the length of the hash table per se.  "new%" is the next available element.  When this function is called, an attempt is made to locate the element with the name given by "name$." If it can not be located, a new element is created and the name is set.  In any case, the index of the element is returned. 

This function could have as easily been coded in C:

	#include <basic/string.h>
	#include <basic/array.h>

	short INThash(name, n, names, links, new)
	struct string *name;
	short *n, *new;
	struct array *names, *links;
	{
		short i, j;
		struct string asgstr();

		for (i = 0, j = 0; j < name->str_len; j++)
			i <<= 1, i ^= name->str_text[j];
		i = (i & 32767) % *n + 1;
		while (links->arr_ptr.arr_int[i] &&
			cmpstr(name, names->arr_ptr.arr_str + i))
			i = links->arr_ptr.arr_int[i];
		if (!links->arr_ptr.arr_int[i])
			names->arr_ptr.arr_str[i] = asgstr(name),
			links->arr_ptr.arr_int[i] = (*new)++;
		return (i);
	}

The cmpstr and asgstr functions are described in the Run-Time Support Library section of this manual. 

SEE ALSO

call, sub

USAGE NOTES

Usr is implemented in Basmark QuickBASIC in a form similar to Microsoft BASIC but is intended for use with high-level language subroutines which are referenced symbolically. 

Usr function names between Basmark QuickBASIC and the C language correspond as follows (where "name" is any valid name):

Basmark QuickBASIC	C

usrname%		INTname
usrname!		FLTname
usrname#		DBLname
usrname$		STRname

For further information on interfacing with C, consult the Run-Time Support Library section of this manual. 

from The Basmark QuickBASIC Programmer’s Manual by Lawrence Leinweber