ezdsl.doc

Eazy Data Structures library for Delphi.

Declaration
  property DisposeData : TDisposeDataProc
Description
  The container's DisposeData procedure. If you don't 'override' it,
  the default one raises an exception if the container is a data owner
  and it tries to dispose of a data object.

  WARNING: your DisposeData procedure may be called with a nil pointer
  so please cater for this possibility and don't try to free a nil
  pointer. It doesn't work.

Declaration
  property DupData : TDupDataFunc
Description
  The container's DupData function. If you don't 'override' it, the
  default one raises an exception when it is used. DupData is used by
  the Clone constructor when the new container is a data owner.

Declaration
  property IsDataOwner : boolean
Description
  READ ONLY. True if the container was created as a data owner, False
  otherwise. It is not possible to change this property after the
  container has been created. Data owners will destroy data objects at
  certain times, e.g., during Empty.

Declaration
  property IsSorted : boolean
Description
  Returns true if the container is sorted, false otherwise.

  Setting the IsSorted property may be ignored depending on the
  container. Certain containers in EZDSL are always non-sorted and so
  setting IsSorted to true will be ignored. Other containers in EZDSL
  are always sorted and so setting IsSorted to false will be ignored.
  If the container's 'sortedness' attribute can be changed, then
  setting it to true will cause the data objects in the container to
  be reordered according to the Compare function.

    Container       IsSorted values
    -------------------------------
    TStack          false
    TQueue          false
    TDeque          false
    TLinkList       true or false
    TDList          true or false
    TSkipList       true
    TBinTree        false
    TBinSearchTree  true
    TrbSearchTree   true
    THashTable      false


Interfaced methods
------------------

Declaration
  constructor Create(DataOwner : boolean); virtual;
Description
  Creates the object. Descendants will (must) set the NodeSize field
  before calling this as an inherited constructor. If non-zero, this
  method gets a pointer to the relevant node store and stores it in a
  field in the container for use when allocating or deallocating
  nodes. If NodeSize is zero this constructor assumes that the
  descendant will be taking care of allocating & freeing nodes.  

  Create sets the internal count of items to zero.

  The DataOwner parameter determines whether the container is to own
  (i.e., can dispose of) its data objects. If true, then the container
  will dispose of data objects by calling DisposeData when required.

Declaration
  destructor Destroy; override;
Description
  Destroys the container. First it calls the virtual Empty method,
  enabling the descendant to clean up properly. If the container is a
  data owner, all data objects will be destroyed as well by calling
  DisposeData, Destroy detaches the container from the node store if
  one was being use for node allocation.

Declaration
  constructor Clone(Source : TAbstractContainer;
                    DataOwner : boolean; NewCompare : TCompareFunc);
                                                    virtual; abstract;
Description
  Constructor to create a 'clone' (ie an exact copy) of the Source
  container and all its data objects.  Descendants will override this
  constructor without fail. If you are going to use this method you
  must override the DupData function as well.  You may specify a new
  Compare function for the cloned container, in which case, if the
  container maintains a sorted order, the new container will have its
  data objects in another order. If DataOwner is true, the new
  container will own its data objects and hence all the objects in the
  original container will be duplicated. If false, the data objects
  (i.e., the pointers) will be copied over.  

Declaration
  procedure Empty; virtual; abstract;
Description
  Abstract method that empties the container; each container
  descendant will have its own preferred efficient method of doing
  this.

  NOTE: DisposeData will be called for all objects in the container if
  the container owns its data objects.  

Declaration
  function IsEmpty : boolean;
Description
  Returns true if the container is empty; i.e., it contains no data
  objects. The method is just a shorthand for checking that the Count
  property is zero.



TStack (EZDSLSTK.PAS)
----------------------------------------------------------------------
A stack is a LIFO container (last in first out): the last data object
pushed on will be the first to be popped off. You can also examine
(peek at) the next item to be popped off. However you cannot navigate
through the stack, the data objects underneath the top one are hidden
from you until you pop the ones above off.


Interfaced methods
------------------

Declaration
  constructor Create(DataOwner : boolean); override;
Description
  Creates the stack by calling the ancestor's Create after setting a
  node size of 8.  If DataOwner is true, the new stack will own its
  data objects. Stacks are created as unsorted objects (IsSorted will
  return false).

Declaration
  constructor Clone(Source : TAbstractContainer;
                    DataOwner : boolean; NewCompare : TCompareFunc);
                                                            override;
Description
  Creates a copy of a Source stack. If DataOwner is true, the data
  objects in the Source stack are duplicated for the new one. If
  false, the data objects are just copied over to the new stack. The
  data objects in the new stack will be popped off in the same order
  as the original stack.

  If Source is not a TStack instance an exception (escBadSource) is
  raised.

Declaration
  procedure Empty; override;
Description
  Repeatedly calls the Pop method until the stack is empty. If the
  stack is a data owner, DisposeData will be called for each data
  object to destroy it.

Declaration
  function Examine : pointer;
Description
  Returns the data object at the top of the stack without popping it. 

  In DEBUG mode, an assertion error (ascEmptyExamine) will occur if
  the stack is empty.  

Declaration
  function Pop : pointer;
Description
  Pops the data object from the top of the stack and returns it.

  In DEBUG mode, an assertion error (ascEmptyPop) will occur if the
  stack is empty.

Declaration
  procedure Push(aData : pointer);
Description
  Pushes the data object aData onto the top of the stack.



TQueue (EZDSLQUE.PAS)
----------------------------------------------------------------------
A queue is a FIFO container (first in first out): the first object put
in the queue will be the first popped, the last object will be the
last to be popped. You can examine (peek at) the next data object to
be popped.  However you cannot navigate through the queue.


Interfaced methods
------------------

Declaration
  constructor Create(DataOwner : boolean); override;
Description
  Creates the queue by calling the ancestor's Create after setting a
  node size of 8.  If DataOwner is true, the new queue will own its
  data objects.

Declaration
  procedure Append(aData : pointer);
Description
  Adds the data object aData to the tail end of the queue.

Declaration
  constructor Clone(Source : TAbstractContainer;
                    DataOwner : boolean; NewCompare : TCompareFunc);
                                                            override;
Description
  Creates a copy of the Source queue. If DataOwner is true, the data
  objects in the original queue will be duplicated for the cloned
  queue. If false, the data objects are copied. The data objects will
  be retrieved in the same order as the original queue.

Declaration
  procedure Empty; override;
Description
  Repeatedly calls the Pop method until the queue is empty. If the
  queue is a data owner, DisposeData will be called to destroy the
  data objects as they are popped.

Declaration
  function Examine : pointer;
Description
  Returns the data from the top of the queue without popping it.

  In DEBUG mode, an assertion error (ascEmptyExamine) will occur if
  the queue is empty.

Declaration
  function Pop : pointer;
Description
  Pops the data object from the front of the queue and returns it.
  Even if the queue is a data owner, the data object is still returned
  (it will not be destroyed).

  In DEBUG mode, an assertion error (ascEmptyPop) will occur if the
  queue is empty.



TDeque
----------------------------------------------------------------------
A deque (sometimes pronounced DECK, sometimes DEQUEUE) is a queue that
allows objects to be added to, or removed from the front or back of
the queue. This particular implementation of a deque just allows queue
jumpers, ie data objects can also be pushed into the front of the
queue, giving it stack-like behavior (Flamig calls this variant a
Staque, see references). It is descended from the basic TQueue and
inherits Pop and Append.


Interfaced methods
------------------

Declaration
  procedure Push(aData : pointer);
Description
  Pushes the data object aData to the front of the deque.



TPriorityQueue
----------------------------------------------------------------------
A priority queue is much like an ordinary queue, except that the
smallest data object in the queue will be popped first (rather than
the 'oldest'). Another name for a priority queue is a heap (not to be
confused with Delphi's heap where memory blocks are allocated and
freed).  As it imposes a sort order on the data objects, you must
override the Compare function.

If the Compare method returns values in the 'normal' sense (i.e.,
Compare returns a negative number if Data1 < Data2, 0 if Data1 =
Data2, and a positive number otherwise), then data objects will be
popped off smallest first, in other words, in increasing order.
However, if Compare returns values in the 'reverse' sense (i.e.,
returning negative if Data1 > Data2, etc), then elements will be
popped off largest first, in other words, in decreasing order. Thus by
carefully selecting Compare, this object will provide the classic min-
heap and max-heap data structures.

Notice that the well-known Heap Sort algorithm uses a structure of
this type, and in fact this structure could be used to provide a
generic sort routine. It will be faster than using a skip list for
example (the data objects are not held internally in a fully sorted
manner, they are just sorted in a 'loose' sense).


Interfaced methods
------------------

Declaration
  constructor Create(DataOwner : boolean);
Description
  Creates the priority queue by call