7.7.  String Manipulation Routines

     There are basically three types of	strings	which an ADL
program	 uses.	The first type of string is the	compile-time
string (a string which was present in the ADL source file of
the  scenario).	  All  compile-time  strings have a positive
string ID and exist for	the duration of	program	execution.

     The second	type of	string is  the	"volatile"  run-time
string.	  Examples  of	this  type of string include strings
typed by the player and	strings	produced by the	builtin	rou-
tines  $subs,  $cat,  $read,  $name, $vname, $mname, $pname,
$num, and $chr (see also Sections 7.8  and  7.9).   Volatile
strings	 have  negative	 string	IDs and	are "flushed" at the
beginning of each turn (just before the	Daemon phase).

     The third type of string is the "non-volatile" run-time
string.	  These	 strings  also	have negative string IDs but
they are never "flushed".  These strings are produced by the
$savestr routine.  Note	that there is no easy way to distin-
guish volatile and non-volatile	run-time strings.

     In	the context of the $subs and $pos routines,  strings
are  indexed  starting	at  zero (the first character of the
string).  The following	routines operate  on  all  types  of
strings:

$eqst	( $eqst	str1 str2 ) -> Returns one if str1  has	 the
	same contents as str2 and zero otherwise.  Note	that
	this is	NOT the	same as	($eq str1 str2),  since	 the
	$eq only compares the string IDs of the	strings.

	Example:
		     The program:
			     ($setg str1 "hello")
			     ($setg str2 ($cat "he" "llo"))
			     (IF ($eqst	@str1 @str2) THEN
				     ($say "String 1 ==	string 2n")
			     )
			     (IF ($ne @str1 @str2) THEN
				     ($say "String ID 1	!= string ID 2n")
			     )

		     will produce the output:
			     String 1 == string	2
			     String ID 1 != string ID 2



$subs	( $subs	str start len )	-> Returns a  volatile	copy
	of  the	substring of str starting at start and going
	for len	characters.  If	len is 0, the suffix of	 str
	starting at start is returned.

	Example:
		     The program:
			     ($setg str	"Hello world")
			     ($say ($subs @str 0 5) "n")
			     ($say ($subs @str 6 0) "n")

		     will produce the output:
			     Hello
			     world



$leng	( $leng	str ) -> Returns the length of str.

	Example:
		     ($leng "Hello") is	5
		     ($leng "")	is 0



$cat	( $cat str1 str2 )  ->	Returns	 a  volatile  string
	which is the result of concatenating str1 and str2.

	Example:
		     ($cat "hello " "world") returns "hello world"



$pos	( $pos str1 str2 ) -> Returns the position  of	str1
	in str2.  If no	occurrence of str1 is found in str2,
	-1 is returned.

	Example:
		     ($pos "hello" "hello world") is 0
		     ($pos "Foobar" "bletch") is -1
		     ($pos "testing" "This is a	test") is -1
		     ($pos "is"	"This is a test") is 2



$read	( $read	) -> Returns a volatile	string which is	read
	from  the player's keyboard.  Note that	no prompt is
	automatically generated.

	Example:
		     ($say "What is your name? ")
		     ($setg MyName ($read))
		     ($say "Hello, " @MyName ",	welcome	to ADL!n")



$savestr( $savestr str ) -> Returns a non-volatile  copy  of
	str.   Note  that  str may be any string -- compile-
	time, volatile,	or non-volatile.

	Example:
		     ($setg MyName ($savestr @MyName))