Contents | Index | < Browse | Browse >
2.4 Lists

  Lists contain items (elements) of a certain data type, similar to arrays. But
  in contrast to arrays, they are not addressed by indices. One of the items
  in the list is the current one that can be accessed at the moment. To access
  the other items, you can move forward or backwards in the list by the
  functions "NextItem" and "PrevItem". Once you seek over the boundaries, those
  functions return false and there is no valid current list item until you
  start from the beginning of the list or seek in the other direction again.
  
  The benefit of lists over arrays is that you can easily add or remove
  items with a minimum overhead and without bookkeeping which element is
  currently used. Lists are ideal for objects in a game, which often appear
  and disapear and all of them have to be processed every frame.

  Lists are declared by using "List" and the "Dim" instruction:
  +-----------------------------------------------------------------------------
  | 
  | Dim List name.t(n)
  | 
  +-----------------------------------------------------------------------------

  name is now an empty list of type .t, with maximum of n items.
  The list is referred by using the round brackets without index.
  Items are handled by the following functions:
  +-----------------------------------------------------------------------------
  | 
  | AddItem(name())           ; add a new item at the current position and
  |                           ; make it the current item
  | KillItem name()           ; remove the current item from the list
  | NextItem(name())          ; seek to the next item
  | PrevItem(name())          ; seek to the previous item
  | ResetList name()          ; seek before the first item
  | FirstItem(name())         ; seek to the first item
  | LastItem(name())          ; seek to the last item
  | ClearList name()          ; remove all items from list
  | SortList(name()[,field])  ; sort the list according the field name,
  |                           ; if it is a newtype
  | PushItem name()           ; push the current position to stack
  | PopItem name()            ; pop the current position from stack
  |
  +-----------------------------------------------------------------------------

  Example:
  +-----------------------------------------------------------------------------
  | 
  | Dim List Race.s(5)           ; declare a list of strings called Race
  | 
  | If AddItem(Race()) Then Race() = "Human"
  | If AddItem(Race()) Then Race() = "Elve"
  | IF AddItem(Race()) Then Race() = "Dwarf"
  | 
  | ResetList Race()             ; go before the first item
  | While NextItem(Race())       ; print out all items
  |   NPrint Race()
  | Wend
  | 
  | ClearList Race()             ; remove all items
  |
  +-----------------------------------------------------------------------------

2.4.1 Dynamic Lists

  If a List is declared with a "maximum" of 0 elements, its size is dynamic and
  only limited by the memory of the machine.

2.4 Seek Recursively Through Lists
  
  Let us imagine you have the following situation:
  You seek through a list and process a certain item. Now you have to call a
  subroutine (function or gosub) that needs to seek through the same list too.
  After returning from the subroutine, the current list item would be probably
  not the one you were processing.
  To solve this problem, every list has a "stack". You can push your current
  item on this stack (well actually a pointer to it), and pop it from stack
  again once the subroutine returns. You can then continue processing this item
  or seeking through the list from that position.
  

Contents | Index | < Browse | Browse >