Contents | < Browse | Browse >
9C. lists and list functions
----------------------------

Lists are like strings, only they consist of LONGs, not CHARs.
They may also be allocated either global, local or dynamic:

DEF mylist[100]:LIST         /* local or global */
DEF a
a:=List(10)                  /* dynamic */

(note that in the latter case, pointer 'a' may contain NIL)
Just as strings may be represented as constants in expressions, lists
have their constant equivalent:

[1,2,3,4]

The value of such an expression is a pointer to an already initialised list.
Special feature is that they may have dynamic parts, i.e, which will
be filled in at runtime:

a:=3
[1,2,a,4]

moreover, lists may have some other type than the default LONG, like:

[1,2,3]:INT
[65,66,67,0]:CHAR                    /* equivalent with   'ABC'   */
['topaz.font',8,0,0]:textattr
OpenScreenTagList(NIL,[SA_TITLE,'MyScreen',TAG_DONE])

As shown in the latter examples, lists are extremely useful with
system functions: they are downward compatible with an ARRAY OF LONG,
and object-typed ones can be used wherever a system function needs
a pointer to some structure, or an array of those.
Taglists and vararg functions may also be used this way.
NOTEZ BIEN: all list functions only work with LONG lists, typed-lists
are only convenient in building complex data structures and expressions.

As with strings, a certain hierarchy holds:
list variables -> constant lists -> array of long/ptr to long
When a function needs an array of long you might just as well give a list
as argument, but when a function needs a listvar, or a constant list,
then an array of long won't do.

It's important that one understands the power of lists and in particular
typed-lists: these can save you lots of trouble when building just
about any data-structure. Try to use these lists in your own programs,
and see what function they have in the example-programs.

summary:

[<item>,<item>,... ]		immediate list (of LONGs, use with listfuncs)
[<item>,<item>,... ]:<type>	typed list (just to build data structures)

If <type> is a simple type like INT or CHAR, you'll just have the
initialised equivalent of ARRAY OF <type>, if <type> is an object-name,
you'll be building initialised objects, or ARRAY OF <object>, depending
on the length of the list.

If you write    [1,2,3]:INT   you'll create a data structure of 6 bytes,
of 3 16bit values to be precise. The value of this expression then
is a pointer to that memory area. Same works if, for example, you have
an object like:

OBJECT myobject
  a:LONG, b:CHAR, c:INT
ENDOBJECT

writing    [1,2,3]:myobject     would then mean creating a data structure
in memory of 8 bytes, with the first four bytes being a LONG with value 1,
the following byte a CHAR with value 2, then a pad byte, and the last
two bytes an INT (2 bytes) with value 3. you could also write:

[1,2,3,4,5,6,7,8,9]:myobject

you would be creating an ARRAY OF myobject with size 3. Note that such
lists don't have to be complete (3,6,9 and so on elements), you may
create partial objects with lists of any size

One last note on data size: on the amiga, you may rely on the fact that
a structure like 'myobject' has size 8, and that it has a pad byte
to have word (16bit) alignment. It is however very likely that an
E-compiler for 80x86 architectures will not use the pad byte and make
it a 7byte structure, and that an E-compiler for a sun-sparc architecture
(if I'm not mistaken) will try to align on 32bit boundaries, thus make
it a 10 or 12 byte structure. Some microprocessors (they are rare, but
they exist) even use (36:18:9) as numbers of bits for their types
(LONG:INT:CHAR), instead of (32:16:8) as we're used to. So don't make too
great an assumption on the structure of OBJECTs and LISTs if you want to
write code that stands a chance of being portable or doesn't rely on side
effects.

	ListCopy(listvar,list,num=ALL)

Copies num elements from list to listvar. example:
DEF mylist[10]:LIST
ListCopy(mylist,[1,2,3,4,5],ALL)
returns listvar.

	ListAdd(listvar,list,num=ALL)

Copies num items of list to the tail of listvar.
returns listvar.

	ListCmp(list,list,num=ALL)

Compares two lists, or some part of them.

	len:=ListLen(list)

Returns length of list, like     ListLen([a,b,c])    would return 3

	max:=ListMax(listvar)

returns maximum possible length of a listvar.

	value:=ListItem(list,index)

functions as    value:=list[index]    with the difference that
list may also be a constant value instead of a pointer. This is
very useful in situations like this where we directly want to
use a list of values:

WriteF(ListItem(['ok!','no mem!','no file!'],error))

this prints an errormessage according to "error". it's similar to:

DEF dummy:PTR TO LONG
dummy:=['ok!','no mem!','no file!']
WriteF(dummy[error])

	SetList(listvar,newlen)

manually sets the length of a list. This will only be useful when you read
data into the list by a function other then a list-specific function,
and want to continue using it as a true list.

for list functions that make use of quoted expressions (see  11C ).
for list linking functions (see  9H ).