9.5.4 List functions

There are a number of list functions which are very similar to the string functions (see 9.5.2 String functions). Remember that E-lists are the list equivalents of E-strings, i.e., they can be altered and extended safely without exceeding their bounds. As with E-strings, E-lists are downwardly compatible with lists. Therefore, if a function requires a list as a parameter you can supply a list or an E-list. But if a function requires an E-list you cannot use a list in its place.

List(maxsize)

Allocates memory for an E-list of maximum size maxsize and returns a pointer to the list data. It is used to make space for a new E-list, like a LIST declaration does. The following code fragments are (as with String) practically equivalent:

  DEF lt[46]:LIST

  DEF lt:PTR TO LONG
  lt:=List(46)

You need to check that the return value from List is not NIL before you use it as an E-list. Like String, the memory allocated using List is deallocated using DisposeLink (see 11.3.5 System support functions).

ListCmp(list1,list2,length=ALL)

Compares list1 with list2 (they can both be normal or E-lists). Works just like StrCmp does for E-strings, so, for example, the following comparisons all return TRUE:

  ListCmp([1,2,3,4],   [1,2,3,4])
  ListCmp([1,2,3,4],   [1,2,3,7], 3)
  ListCmp([1,2,3,4,5], [1,2,3],   3)

ListCopy(e-list,list,length=ALL)

Works just like StrCopy, and the following example shows how to initialise an E-list:

  DEF lt[7]:LIST, x
  x:=4
  ListCopy(lt, [1,2,3,x])

As with StrCopy, an E-list cannot be over-filled using ListCopy.

ListAdd(e-list,list,length=ALL)

Works just like StrAdd, so this next code fragment results in the E-list lt becoming the E-list version of [1,2,3,4,5,6,7,8].

  DEF lt[30]:LIST
  ListCopy(lt, [1,2,3,4])
  ListAdd(lt, [5,6,7,8])

ListLen(list)

Works just like StrLen, returning the length of list. There is no E-list specific length function.

ListMax(e-list)

Works just like StrMax, returning the maximum length of the e-list.

SetList(e-list,length)

Works just like SetStr, setting the length of e-list to length.

ListItem(list,index)

Returns the element of list at index. For example, if lt is an E-list (so a PTR TO LONG) then ListItem(lt,n) is the same as lt[n]. This function is most useful when the list is not an E-list; for example, the following two code fragments are equivalent:

  WriteF(ListItem(['Fred','Barney','Wilma','Betty'], name))

  DEF lt:PTR TO LONG
  lt:=['Fred','Barney','Wilma','Betty']
  WriteF(lt[name])

Go to the Next or Previous section, the Detailed Contents, or the Amiga E Encyclopedia.