9B. strings and string functions

E has a datatype STRING. This is a string, from now on called 'Estring',
that may be modified and changed in size, as opposed to normal 'strings',
which will be used here for any zero-terminated sequence. Estrings are
downward compatible with strings, but not the other way around, so if an
argument requests a normal string, it can be either of them. If an Estring
is requested, don't use normal strings. Example of usage:

DEF s[80]:STRING, n                -> s is an estring with a maxlen of 80
ReadStr(stdout,s)                  -> read input from the console
n:=Val(s)                          -> get a number out of it
  -> etc.

Note that all string functions will handle cases where string tends to
get longer than the maximum length correctly;

StrAdd(s,'this string is longer than 5 characters',ALL)

s will contain just 'this '.
A string may also be allocated dynamically from system memory
with the function String(), (note: the pointer returned from this function
must always be checked against NIL)


DEF s[80]:STRING     is equivalent to     DEF s     and     s:=String(10)


compares two strings. len must be the number of bytes to compare,
or 'ALL' if the full length is to be compared. Returns TRUE or FALSE
(len is a default argument (see  6F ))


copies the string into the estring. If len=ALL, all will be copied.
returns the estring.


same as StrCopy(), only now the string is concatenated to the end.
returns the estring.


calculates the length of any zero-terminated string


returns the length of an estring


returns the maximum length of a estring


similar to WriteF, only now output goes to estring instead of stdout.

StringF(s,'result: \d\n',123)

's' will be 'result: 123\n'
returns the estring, and length as second returnvalue.


fills estring with the last n characters of the second estring
returns the estring.


copies any number of characters (including all if len=ALL) from
position pos in string to estring
NOTEZ BIEN: in all string related functions where a position in a
string is used, the first character in a string has position 0,
not 1, as is common in languages like BASIC.
returns the estring.


finds an integer encoded in ascii out of a string. Leading spaces/tabs
etc. will be skipped, and also hexadecimal numbers (1234567890ABCDEFabcdef)
and binary numbers (01) may be read this way if they are preceded by a
"$" or a "%" sign respectively. A minus "-" may indicate a negative integer.
Val() returns the number of characters read in the second argument, which
must be given by reference (<-!!!), or can be received as second returnvalue.
If "read" returns 0 (value will be 0 too) then the string did not contain an
integer, or the value was too sizy to fit in 32bit. "read" may be NIL.

examples of strings that would be parsed correctly:
'-12345', '%10101010', '   -$ABcd12'

these would return both as "value" and in read a 0:
'', 'hello!'


searches string1 for the occurrence of string2, possibly starting from
another position than 0. Returned is the offset at which the substring
was found, else -1.


returns the *address* of the first character in a string, i.e., after
leading spaces, tabs etc.

	UpperStr(string)     and      LowerStr(string)

changes the case of a string.
TAKE NOTE: these functions modify the contents of 'string', so they may
only be used on estrings, and strings that are part of your programs data.
Effectively this means that if you obtain the address of a string through
some amiga-system function, you must first StrCopy() it to a string of
your program, then use these functions.
they return the string.


will read a string (ending in ascii 10) from any file or stdout.
ok contains -1 if an error occurred, or an EOF was reached.
Note: the contents of the string read so far is still valid.
Also note that, like Inp() Out(), etc. this function makes use
of unbuffered 1.3 style IO, and thus may be slow. The dos.library
Fgets() function forms a nice alternative.


manually sets the length of a string. This is only handy when you read
data into the estring by a function other then an E string function,
and want to continue using it as an Estring. For example, after
using a function that just puts a zero-terminated string at the
address of estring, use   SetStr(mystr,StrLen(mystr))  to make
it manipulatable again. If the string is too long, SetStr does nothing
(this should always be prevented).


'Array String Copy' copies string2 into the memory area denoted by string1.
string1 is typically not an estring but an ARRAY. size is the total #of chars
string1 can hold, i.e. if you write 5 and string2='helloworld', string1 will
be 'hell' + 0termination.


'Ordered String Compare' returns 1 if string2>string1, 0 for equal and -1
for less. only max chars are compared.

for string linking functions (see  9H )