Starlib: How the list primitives work.

Throughout starlib, there are many places where a linked list is used. In every one of those cases, the following primitive methods can be used on that list. There are really two different classes that use lists. There is the List<> class and the ASTlist<> class. ASTlist is a class derived from the base class List. Both classes are template classes.

The main difference between ASTlist and List are are so minor that as a user of this library, you can ignore the differences. The ASTlist was developed to keep track of some extra information that is needed when handling lists of nodes in a the STAR tree, but the differences do not show on the surface, and you can behave as if the two classes act the same way:

A list has a concept of its "current" position. Each list can only have one such "current" position.

(Throughout the following list, "T" refers to the type that the instantiation of List<> or ASTlist<> was created to hold.)

• constructors
  The default constructor for a List creates an empty list. There is also a copy constructor that copies the contents of one List into a new one.

• void AddToEnd(T addme)
void AddToEnd(const List &addme)
  This method adds a new object to the end of the list. There is an overloaded version that will accept another List as the parameter - this copies the entire contents of the passed list onto the end of this list.

  Currently there is no provision for adding things to the middle of the list, only at the end.

• void FreeList()
  Removes the contents of the list, but not the list itself. (In other words, it resets the list back to being empty.)

• void RemoveCurrent()
  Removes the current node from the list. The 'current' pointer moves to the next object in the list after the deleted one.

• void AlterCurrent(T setToMe)
  Replaces the current node of the list with the given value.

• void MemorizeCurrent()
  This method tells the object to remember where its current pointer is, so it can be restored to that position later. Each object of type List can only remember one such value at a time.

• void RestoreCurrent()
  Restores a list to the position it was at when MemorizeCurrent() was called. (see above).

• int Length() const
  Returns the number of nodes in the list.

• bool Lookup(T findMe)
  Searches for an object that is equal to the object passed (If the class passed has had its '==' operator redifined, then the redefined version will be used for this check.) If the object is found in the list, true is returned.

• bool SeekTo(T findMe)
  Like Lookup(), but it also moves the current pointer to the location given.

• void Reset()
  Moves the current to the start of the list.

• void Next()
void Prev()
  These methods move the current to the next or previous node in the list.

• bool AtEnd()
  , bool AtStart()
  Returns true if the current has passed the end of the list for AtEnd(), or is at the start of the list for AtStart()

• T Current() const
  Returns a copy of the contents of the current node of the list.

• T Last() const
  Returns a copy of the last element of the list.

• operator ==
  The '==' operator is overridden so that it is possible to compare two lists and ask "Do these lists have the same contents?"