Lists (full name linked lists) are similar to arrays in that they store multiple similar items of data. However,
they are different in the way you use them and their structure. List items can be anywhere in memory, so they
include extra information about where to find the next and previous items in the list - these are used by the
Blitz commands you use to move around the list. The maximum number of items in the list and the type of each item
are specified when you create the array. Note that a list can contain less than the maximum number of items, which
is different from an array where all the items are always used. (This structure is shown below, with each each box
representing a single item of data, right arrows are connections to the next item and left arrows are
connections to the previous item.)
Creating a list is similar to creating an array. Again, you use the Dim command,
you give the list a name, specify the type, and the maximum number of items you would like to store in the list.
You also add the List command (in the position shown below).
 |
Dim List bar$(100) ; Creates a List of strings, called bar, with a maximum of 101 items
|
Notice that you have to tell Blitz the maximum number of items in a List, even though
the contents and number of items that are being used at any time are dynamic. This is
one of the main problems with Lists in Blitz. There are ways round this (using alternative
methods for lists), but these are more advanced and will be dicussed later.
Items in lists are not accessed in the same way as arrays. You MUST NOT access list items
using an index in brackets after the list name. Instead, you work on whatever the current item in the
list is, and you access it like this:
|
bar$() = "Hell world"
NPrint bar$()
|
Notice that although you do not use an index, you must put the brackets on the list name so that Blitz
knows you mean to use a list instead of a normal variable.
When you create a list, it starts off completely empty. So we first need to create items in the list
before we can even begin to think about working with the current item. To create items in lists, you use
the commands which add an item to a list: AddFirst, AddItem and AddLast.
Each of these commands return true if the item could be created, and false if the item creation failed
(lack of memory, list already full, etc). You should always check the result of these commands to make sure
you have successfully created a new item in the array (and we'll show you how to do that in the Program Flow
topic). If the item was created successfully, the current item is set to the new item you have added.
One of the maini advantages of using a list structure is that is is a lot faster to add and remove
items in a dynamic way than with arrays. These three commands allow you to add items at the start,
end and anywhere inside a list.
The following pieces of code show what happens to the list structure when various items are added. The current
item is outlined in red, and new items are a mix of red and green:
|
Dim List bar$(10) | List created. Contents: |
|
; Add a new item after the current item (in
; this case will be added as first item in list)
AddItem bar$() |  |
|
; Store some value in current item
bar$() = "my" |  |
|
; Adds a new item to the very start of the list
AddFirst bar$() |  |
|
bar$() = "This" |  |
|
; Adds a new item after the current item (in
; this case will be added as second item in list)
AddItem bar$() |  |
|
bar$() = "is" |  |
|
; Adds a new item to the very end of the list
AddLast bar$() |  |
|
bar$() = "list" |  |
Now that you have some items in your list, you need to know how to move around the list so you can select
the correct current item for manipulating. The following commands can be used to navigate lists in Blitz:
- FirstItem listname() - sets the current item to be the first item in the list. Returns true if successful, false if the list is empty.
- LastItem listname() - sets the current item to the last item in the list. Returns true if successful, false if the list is empty.
- NextItem listname() - sets the current item to the next item in the list. Returns true if successful, false if there is no next item (i.e. we are already at the end of the list).
- PrevItem listname() - sets the current item to the previous item in the list. Returns true if successful, false if there is no previous item (i.e. we are already at the start of the list).
- ResetList listname() - sets the current item to be before the first item in the list. So you do not actually have a current item, but this makes lists easier to process using loops and the NextItem command (using NextItem directly after a ResetList will put the current item to the first item in the list). Does not return any value.
An example of these commands (add this onto the bottom of the previous example code and try running it):
| Code | List contents |
; Set current item to before first item
ResetList bar$() |  |
|
; Go to the first/start item in the list
NextItem bar$()
NPrint bar$() |  |
|
; Move onto the next item
NextItem bar$()
NPrint bar$() |  |
|
; Go back to previous item
PrevItem bar$()
NPrint bar$() |  |
|
; Go to the last item in the list
LastItem bar$()
NPrint bar$()
MouseWait |  |
You also need to know how to remove items from the list. Blitz will automatically remove all items from a list when the
program exits, but one of the advantages of lists are that it is easy to add new and remove items. There are only two commands
for doing this:
- KillItem listname() - removes the current item from the list.
- ClearList listname() - removes all items from the list. The current item is obviously not set after using this command, until you add more items to the list.
| Code | List contents |
; Set current item to first itemFirstItem bar$() |  |
|
; Remove it
KillItem bar$()
; Set current item to before first itemResetList bar$() |  |
|
; Move onto the next item
NextItem bar$()
NPrint bar$() |  |
|
; Go to the last item in the list
NextItem bar$()
NPrint bar$() |  |
Finally, there are some special commands which you can use to navigate lists. These allow you to "remember"
positions anywhere in the list and jump back to them at a later stage. They are implemented like a stack, so the most recent item
you have stored will be the first item brought back.
- ItemStackSize NumberOfItems - Sets the maximum number of list items that can be stored on the item stack. Defaults to 8.
- PushItem listname() - Stores the current item from the list specified by "listname()" on the item stack.
- PopItem listname() - Recalls the most recent item stored on the stack. The listname() used here must match the one used in the most recent call to the PushItem command.
Examples of these three commands are shown below, with their affects on the list structure and the contents of the list item stack.
The current list item is shown in red.
| Code | List contents | Stack |
; Set item stack size (not always necessary,
; as it will default to 8)
ItemStackSize 4 |
|
; Move to first item and push onto stack
FirstItem bar$()
PushItem bar$() |  |  |
|
; Push another item onto the stack
NextItem bar$()
PushItem bar$() |  |  |
|
; And finally a third item
NextItem bar$()
PushItem bar$() |  |  |
|
; Move to another item to see the
; effect of popping items off the stack
FirstItem bar$() | | |
|
; Restore item from the stack and print it
PopItem bar$()
NPrint bar$() | | |
|
; Restore item from the stack and print it
PopItem bar$()
NPrint bar$() | | |
|
; Restore item from the stack and print it
PopItem bar$()
NPrint bar$()
MouseWait
End | | |
|