ezdsl.doc

Eazy Data Structures library for Delphi.

        dispose of the memory held by the data object. For stacks and
        queues Delete is known as Pop.

Erase	unlinks a data object from a container and also disposes
        the memory held by the object (if the container owns its data
        objects, that is).

Examine	returns the data object at the 'current position' of
        the container. Current position is defined in different ways
        for different containers: for a stack or queue it is the head
        of the stack or queue for example.

Empty	empties the container by calling Erase for all data
        objects.

IsEmpty	returns true if there are no data objects in the
        container, false if there is at least one.

Iterate	calls its action routine for each data object in the
        container.

Clone	creates an exact duplicate of a data container. All the
        data objects within the container are also duplicated if the
        new container is going to be a data owner, else only the
        pointers to the data objects are copied over. Note that an
        "exact lookalike" copy might not be created, a clone of a
        binary search tree might not look the same, even though all
        the nodes are in sorted InOrder sequence.

Join	adds all the data objects in one container to another (in
        a fashion that makes sense according to the container type).
        The emptied container is disposed of.

Split	splits a container into two, moving all the data objects
        from the split point to a newly created container of the same
        type is the first. In this version of EZDSL, Split has not
        been implemented for binary trees.



Global Types, Constants and Variables
----------------------------------------------------------------------

Declaration
  const
    ezdsStartOffset = $E2D5;
    escTooManyItems   = ezdsStartOffset+1;
    escInsInvalidHere = ezdsStartOffset+2;
    escDelInvalidHere = ezdsStartOffset+3;
    escInsertDup      = ezdsStartOffset+4;
    escTreeStackError = ezdsStartOffset+5;
    escTreeQueueError = ezdsStartOffset+6;
    escCannotMoveHere = ezdsStartOffset+7;
    escIncompatible   = ezdsStartOffset+8;
    escNoCompare      = ezdsStartOffset+9;
    escNoDupData      = ezdsStartOffset+10;
    escNoDisposeData  = ezdsStartOffset+11;
    escBadSource      = ezdsStartOffset+12;
    escIndexError     = ezdsStartOffset+13;
    escBadCaseSwitch  = ezdsStartOffset+14;
    escKeyNotFound    = ezdsStartOffset+15;
    escTableFull      = ezdsStartOffset+16;
    escTableHasData   = ezdsStartOffset+17;
    escSortNeedsCmp   = ezdsStartOffset+18;
    escCmpNeeded      = ezdsStartOffset+19;

    ascFreeNilNode    = ezdsStartOffset+50;
    ascNewNodeSize0   = ezdsStartOffset+51;
    ascFreeNodeSize0  = ezdsStartOffset+52;
    ascEmptyExamine   = ezdsStartOffset+53;
    ascEmptyPop       = ezdsStartOffset+54;
    ascDeleteEdges    = ezdsStartOffset+55;
    ascExamineEdges   = ezdsStartOffset+56;
    ascInsertEdges    = ezdsStartOffset+57;
    ascReplaceEdges   = ezdsStartOffset+58;
    ascAlreadyAtEnd   = ezdsStartOffset+59;
    ascAlreadyAtStart = ezdsStartOffset+60;
    ascCannotJoinHere = ezdsStartOffset+61;
    ascCannotJoinData = ezdsStartOffset+62;
    ascSplitEdges     = ezdsStartOffset+63;
    ascOutOfRange     = ezdsStartOffset+64;
    ascExamineLeaf    = ezdsStartOffset+65;
    ascBadSkipLevel   = ezdsStartOffset+66;
    ascIsSortedList   = ezdsStartOffset+67;
    ascIsNotSortedList= ezdsStartOffset+68;
    ascHashFuncIsNil  = ezdsStartOffset+69;
Description
  Various string constants defining error and assertion conditions.
  The constants are defined in EZDSLCTS.PAS. The strings themselves
  are defined in EZDSLCTS.RC in a stringtable, and compiled into the
  EZDSLCTS.R16 resource file for Delphi 1, and EZDSLCTS.R32 for the
  32-bit Delphis. As Windows only allows one stringtable per
  application ezdsStartOffset can be altered to any constant value so
  that the string constants don't clash with your current application.

Declaration
  const
    skMaxLevels = 16;
Description
  The maximum number of levels in a skip list. A skip list node will
  never have more than this number of forward pointers. Defined in
  EZDSLBSE.PAS.

Declaration
  type
    TChild = (CLeft, CRight);
Description
  For binary trees: flags for left and right children. Defined in
  EZDSLBSE.PAS.

Declaration
  type
    TCompareFunc = function (Data1, Data2 : pointer) : integer 
                                                     of object;
Description
  Function prototype for comparing two data objects. The function must
  return a negative number if Data1 is less than Data2, 0 if they are
  equal, and a positive number if Data1 is greater than Data2. The
  routine you write must be a method of a class.  Defined in
  EZDSLBSE.PAS.

Declaration
  type
    TDisposeDataProc = procedure (aData : pointer) of object;
Description
  Procedure prototype for disposing a data object. The routine you
  write must be a method of a class. Defined in EZDSLBSE.PAS.

Declaration
  type
    TDupDataFunc = function (aData : pointer) : pointer of object;
Description
  Function prototype for duplicating data objects. The function must
  create a duplicate to the aData data object and return it as the
  function result.  If the duplication fails for some reason, then the
  function must raise an exception. The routine you write must be a
  method of a class. Defined in EZDSLBSE.PAS.

Declaration
  type
    TIterator = function (C : TAbstractContainer; aData : pointer;
                          ExtraData : pointer) : boolean;
Description
  Function prototype for an Iterate method iterator. C is the
  container whose Iterate method was called. aData is the current data
  object. ExtraData is the extra pointer you passed to Iterate. The
  function must return true if Iterate is to continue iterating, false
  if Iterate is to stop immediately.  Defined in EZDSLBSE.PAS.

Declaration
  type
    TListCursor = longint;
Description
  Navigation cursor for TDList and TSkipList (double linked & skip
  lists). Defined in EZDSLBSE.PAS.

Declaration
  type
    TTraversalType = (ttPreOrder, ttInOrder, ttPostOrder, ttLevelOrder);
Description
  For binary trees: the different methods of traversing their nodes.
  Defined in EZDSLBSE.PAS.

Declaration
  type
    TTreeCursor = longint;
Description
  Navigation cursor for TBinTree and descendants (binary trees).
  Defined in EZDSLBSE.PAS.

Declaration
  type
    TEZString = string[255];
    PEZString = ^TEZString;
Description
  Essentially for compatibility between Delphi 1 and Delphi 2/3: these
  provide a much needed single type for short strings. Defined in
  EZDSLSUP.PAS.



Stand-alone routines (all within EZDSLSUP.PAS)
----------------------------------------------------------------------

Declaration
  function  EZIntCompare(Data1, Data2 : pointer) : integer;
Description
  Intended as a compare function for containers: compares two
  longints.

Declaration
  procedure EZIntDisposeData(aData : pointer);
Description
  Intended as a data disposal procedure for containers: disposes a
  longint. In other words, does nothing!

Declaration
  function  EZIntDupData(aData : pointer) : pointer;
Description
  Intended as a data duplication function for containers:  duplicates
  a longint. Essentially it returns aData.

Declaration
  function  EZStrNew(const S : string) : PEZString;
Description
  Allocates a memory block on the heap, copies S to it, and returns
  the pointer to the memory block. Exactly equivalent to NewStr in
  Delphi 1.0. In Delphi 2/3 EZStrNew provides a pointer to a short
  string, not a long string.

Declaration
  procedure EZStrDispose(PS : PEZString);
Description
  Disposes of a string allocated on the heap by EZStrNew.

Declaration
  function  EZStrCompare(Data1, Data2 : pointer) : integer;
Description
  Intended as a compare function for containers: compares two
  strings in case-sensitive manner. The strings are assumed to have
  been assigned with the EZStrNew routine, in other words are short
  strings in Delphi 2/3.

Declaration
  procedure EZStrDisposeData(aData : pointer);
Description
  Intended as a data disposal procedure for containers: disposes a
  string. The string is assumed to have been assigned with the
  EZStrNew routine.

Declaration
  function  EZStrDupData(aData : pointer) : pointer;
Description
  Intended as a data duplication function for containers:  duplicates
  a string. The string is assumed to have been assigned with the
  EZStrNew.



Exception classes
----------------------------------------------------------------------
EZDSL defines two exception classes.

   EEZContainerError = class(Exception);

This is the ancestor exception class for the EZDSL library. All run-
time exceptions are of this type.

   EEZAssertionError = class(EEZContainerError);

This is the assertion exception class. It is only used in DEBUG mode.



TAbstractContainer (EZDSLBSE.PAS)
----------------------------------------------------------------------
This type is an abstract container class, an ancestor to all the other
containers. Most methods have to be or must be overridden, but it
forms a base object from which more complex objects can be derived.
Please review the descriptions of the properties defined below; the
most important are Compare, and DisposeData; DupData is only required
if you are going to be cloning containers.

Do not create an instance of this object type.


Properties
----------

Declaration
  property Count : longint
Description
  READ ONLY. The number of data objects in the container.

Declaration
  property Compare : TCompareFunc
Description
  The container's Compare function. If you don't 'override' it by
  setting the property to a function in your code, the default one
  raises an exception when Compare is used. 

  If a container's IsSorted property  returns true, the Compare
  property must be set.

  If there are data objects present in the container, and the
  container is sorted, then setting the Compare property will cause
  the container to be sorted according to the new Compare function.

  For non-sorted containers, the Compare function will be used in a
  search to determine whether the data object you are looking for is
  present or not. In this restricted case, Compare is just used for
  its zero (i.e., equal) and non-zero (i.e., not equal) results.
  Setting Compare in a non-sorted container has no immediate effect.

  Note that the THashTable container does not use the Compare function
  under any circumstances.