Contents | < Browse | Browse >
9H. string and list linking functions
-------------------------------------
E provides for a set of functions that allows the creation of
linked list with the STRING and LIST datatype, or strings and lists
that were created with String() and List() respectively. As you may
know by now, strings and lists, complex datatypes, are pointers
to their respective data, and have extra fields to a negative offset
of that pointer specifying their current length and maxlength. the
offsets of these fields are PRIVATE. as an addition to those two,
any complex datatype has a 'next' field, which is set to NIL by
default, which may be used to build linked list of strings, for example.
in the following, I will use 'complex' to denote a ptr to a STRING
or LIST, and 'tail' to denote another such pointer, or one that already
has other strings linked to it. 'tail' may also be a NIL pointer,
denoting the end of a linked list.
[note: these String-list functions have nothing to do with E-lists or
 Lisp-Cell lists]
The following functions may be used:

	complex:=Link(complex,tail)

puts the value tail into the 'next' field of complex. returns again complex.
example:

DEF s[10]:STRING, t[10]:STRING
Link(s,t)

creates a linked list like:    s --> t --> NIL

	tail:=Next(complex)

reads the 'next' field of var complex. this may of course be NIL, or
a complete linked list. Calling Next(NIL) will result in NIL, so it's
safe to call Next when you're not sure if you're at the end of a linked list.

	tail:=Forward(complex,num)

same as Next(), only goes forward num links, instead of one, thus:

Next(c) = Forward(c,1)

You may safely call Forward() with a num that is way too large;
Forward will stop if it encounters NIL while searching links, and
will return NIL.

	DisposeLink(complex)

same as Dispose(), with two differences: it's only for strings and
lists allocated with String() or List(), and will automatically
de-allocate the tail of complex too. Note that large linked lists
containing strings allocated with String() as well as some allocated
locally or globally with STRING may also be de-allocated this way.

For a good example of how linked lists of strings may be put to
good use in real-life programs, see Src/Utils/D.e