List object

KCML has a simple list object implemented through a dynamic object instantiated by CREATE and manipulated with the OBJECT notation.

The list is a doubly linked list of element objects with the list maintaining pointers to the head and tail. The elements are objects created using the CreateElement() factory method. Values stored in the elements with the value$ property are normally simple UTF-8 strings. To store binary values, especially RECORDs, use the SetRecord(BYREF x$) and GetRecord(BYREF x$) methods.

Element objects created on one list can be used on another list.

DIM OBJECT L, OBJECT x, i
OBJECT L = CREATE "dynamic", "list"
L.estimate = 10
FOR i = 1 TO 10
	OBJECT x = L.CreateElement($PRINTF("key%d", i))
	x.value$ = $PRINTF("text for element %d", i)
	L.Append(OBJECT x)
END FOR
PRINT "There are";L.length;"elements in the list"

When an element object is created it can optionally be given a key value which must be a unicode string and be unique in the list. The list object uses a hash index to access elements by key and his index resizes itself automatically but, optionally, if you know how many elements will be in the index you can pass this hint by setting the estimate property of the object to that size before the first element is added to the list. This allows KCML to size the index correctly in advance.

The list is normally maintained in the order of insertion. It can be traversed, starting with the head or the tail properties of the list object, using the next and previous properties of an element.

OBJECT x = L.head
WHILE OBJECT x <> NULL DO
	PRINT x.key$
	OBJECT x = x.Next
WEND

The Index(n) method will walk the list to find the n^th element counted from 1. Thus .Index(1) represents the head of the list. If n is negative then it counts from the tail of the list. This method will return NULL for index values that do not occur in the list.

It can also be traversed in sorted key order, provided all the elements have keys, using FOR OBJECT. If some or all of the elements don't have keys then the list is traversed in the order of insersion.

FOR OBJECT x IN L
	PRINT x.key$
NEXT OBJECT x

For more information see the page on CREATE and the full specification of methods and properties here.

Compatibility

This object was introduced in KCML 6.40. The estimate property and autosizing of the hash index was added for 6.90