It has three main components:
1. Type TList
This is the generic list that uses a TNode type which is just a pointer to the next node, a pointer to the previous node and a pointer to the data.
Only pointers to the items are kept in this list and they are stored is an Any pointer. So any kind of data can be stored but you must manage that items memory.
Nodes are created for each item using the New keyword. Those node memory is freed using delete in the destructor (or in the delete_node method).
2 #Macro __MAKE_LIST__(V, T, CT)
This is a macro to make it easier to use the list. This macro creates a separate type that extends the TList type and implements various methods that utilize the type of data you are storing.
The macro parameters are:
V - the name of the list variable ex my_list
T - the type of the variable ex string
CT - the type cast used in comparison operations
V for Variable name requires no explanation. T for type are is the type of object you are storing. This can be an intrinsic type, like a String or an Integer, or it can be a UDT. CT for Cast Type is used to tell the macro what to cast the pointer to the item as when making comparisons.
In the following example the type test is used for paramter T. The cast operator must be overloaded in the type and that must be supplied to the macro. In this case the cast to string is overloaded.
Code: Select all
Type test
As String s
As Integer x, y
Declare Operator cast()
End Type
Operator test.cast() As String
Return this.s
End Operator
Code: Select all
If item = Cast(CT , *Cast(T Ptr, node->pData)) ThenThis macro is identical to __MAKE_LIST__ except that it requires that the UDT data type stored in the list extends the type IComparable. Type IComparable is defined at the top of the code. It declares an abstract function called compareto. Your UDT must declare and define that funcion. The function is used for comparison operations. The function returns a -1 if instance (this) item is < search iitem ( o), 0 if instance item = search item, or 1 if instance item > search item. The function has a return type of the enum ComparisonResult which is also defined at the top of the code.
The macro versions have the advantage of managing the item memory for you. New T items are created and deleted without the user necessarily having to handle it. So you don't have to create new objects and remember to free their memory.
TList defines these methods:
Code: Select all
' for_each - Iterate each element of the list.
' - Each element is passed as a parameter to the call_back sub
Declare Sub for_each(Byval call_back As Sub(Byval node As Any Ptr))
' get_node_at_inex - return the n-1th (index) node from root_node
Declare Function get_node_at_index(Byval index as Integer) As TNode Ptr
' sink - set node as the root node
' - Returns true if successful
Declare Function sink(Byval node as TNode Ptr) as Boolean
' sink - set the node that contains item as the root node
' - compareto is a sub used to compare item with node->pdata items until a match is found
' - Returns true if successful
Declare Function sink(Byval item as Any Ptr, Byval compareto As Function(Byval list_item As Any Ptr, Byval search_item As Any Ptr ) As Boolean) As Boolean ' float item to top (front) of list
' float - set node as the front_node
' - Returns true if successful
Declare Function float(Byval node As TNode Ptr) as Boolean
' float - set the node that contains item as the front node
' - compareto is a sub used to compare item with node->pdata items until a match is found
' - Returns true if successful
Declare Function float(Byval item as Any Ptr, Byval compareto As Function(Byval list_item As Any Ptr, Byval search_item As Any Ptr ) As Boolean) As Boolean ' float item to top (front) of list
' push - append a new node to the tail of the list (this is the same as append_item() and in fact simply calls append_item)
' - returns true is successful
Declare Function push(Byval item As Any Ptr) As Boolean
' insert_head - insert a new node with pdata = item as a root node
' - Returns true if successful
Declare Function insert_head(Byval item As Any Ptr) As Boolean
' insert_before - insert a new node with pdata = item into the list immediately prior to next_node
' - Returns true if successful
Declare Function insert_before(Byval next_node As TNode Ptr, Byval item As Any Ptr) As Boolean
' insert_after - insert a new node with pdata = item into the list immediately after prev_node
' - Returns true if successful
Declare Function insert_after(Byval prev_node As TNode Ptr, Byval item as Any Ptr) As Boolean
' append_item - append a new node with pdata = item onto the list
' - Returns true if successful
Declare Function append_item(Byval item As Any Ptr) As Boolean
' delete_node - remove node from the list and free its memory
' - Returns true if successful
Declare Function delete_node(Byval node As TNode Ptr) as Boolean
' pop - delete the front_node from the list, free its memory, and return a pointer to its pdata item
Declare Function pop() As Any Ptr
' find_item - iterate the node list until a pdata item matches parameter item.
' - the call back sub parameter is used to compare items
' - returns the pdata item or null if no match is found
Declare Function find_item(Byval item As Any Ptr, Byval compareto As Function(Byval list_item As Any Ptr, Byval search_item As Any Ptr ) As Boolean) As Any Ptr
' find_item - iterate the node list until a pdata item matches parameter item.
' - paramter item is a type that extends IComparable and therefore defines a compareto sub used to find a match
' - returns the pdata item or null if no match is found
Declare Function find_item(Byval item As IComparable Ptr, Byref node As TNode Ptr = NULL) As Any Ptr
Code: Select all
' item_at - returns a reference to an item that is at index
Declare Property item_at(Byval index as integer) Byref As T
' clear_items - delete all nodes and their items and free their memory
' - returns true if successful
Declare Function clear_items() As Boolean
' delete_item - delete the node->pdata item that matches parameter item and delete that node as well
' - returns true if successful
Declare Function delete_item(Byval item as T) As Boolean
' append_item - create a new node and new pdata item
' - set the new items values to the parameter item values
' - set byref parameter pItem to the new item
' - return true if successful
Declare Function append_item(Byval item as T, Byval pItem As T Ptr = 0) as Boolean
' append_item - create a new node and set its pdata to parameter item
' - return true if successful
Declare Function append_item(Byval item as T Ptr) As Boolean
' for_each - iterate the item list by sending each nodes pdata item to the parameter call_back sub
Declare Sub for_each(Byval Call_back As Sub(Byval item as T Ptr))
' get_item_at_node - return the item at parameter index
Declare Function get_item_at_index(Byval index As Uinteger) As T Ptr
' sink - set the node containing paramter item as the root node
' - return true if successful
Declare Function sink(Byval item as T) As Boolean
' sink - set the node at parameter index as the root node
' - return true if successful
Declare Function sink(Byval index as integer) As Boolean
' float - set the node containing parameter item as the root node
' - return true if successful
Declare Function float(Byval item as T) As Boolean
' float - set the node at parameter index as the root node
' - return true if successful
Declare Function float(Byval index as integer) As Boolean
' insert_head - create a new node and a new item for its pdata
' - set the new items data to the parameter items data
' - return true if successful
Declare Function insert_head(Byval item As T, Byval pitem As T Ptr = 0) As Boolean
' insert_head - create a new node and set its pdata to parameter item
' - set the new node as the root node
' - return true if successful
Declare Function insert_head(Byval item As T Ptr) As Boolean
' insert_after - create a new node and a new item for its pdata
' - set the items data to parameter new_item
' - insert the new node after the node containing prev_item as its pdata
' - return true if successful
Declare Function insert_after(Byval prev_item As T, Byval new_item As T) As Boolean
' insert_after - create a new node and set its pdata to parameter new_item
' - insert the new node after the node containing prev_item as its pdata
' - return true if successful
Declare Function insert_after(Byval prev_item As T, Byval new_item As T ptr) As Boolean
' insert_before - create a new node and a new item for its pdata
' - set the items data to parameter new_item
' - insert the new node before the node containing prev_item as its pdata
' - return true if successful
Declare Function insert_before(Byval next_item As T, Byval new_item As T) As Boolean
' insert_after - create a new node and set its pdata to parameter new_item
' - insert the new node before the node containing prev_item as its pdata
' - return true if successful
Declare Function insert_before(Byval next_item As T, Byval new_item As T ptr) As Boolean
' pop - delete the tail node return its item
Declare Function pop() As T ptr
' push - create a new node and a new T item for its pdata
' - set the new items data to the parameter item data
' - append new node to list
' - return true if successful
Declare Function push(Byval item As T) As Boolean
' push - create a new node and set its pdata item to the parameter item
' - append the new node to the list
' - return true if successful
Declare Function push(Byval item As T Ptr) As Boolean
#Ifndef __ICTList__
' find_item - return item that matches parameter item using cast to CT (cast type) for comparison
' - set byref parameter node to the node containing matching item
Declare Function find_item(Byval item As CT, Byref node As TNode Ptr = 0) As T Ptr ' node will be filled with a pointer to a TNode that contains item
#Endif
' find_item - return item that matches parameter item using parameter items comparison function
Declare Function find_item(Byval item As IComparable Ptr, Byref node As TNode Ptr = 0) As T Ptr