ezdsl.doc

Delphi数据结构分析源码

=====================================

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;
  ascFreeNilNode    = ezdsStartOffset+20;
  ascNewNodeSize0   = ezdsStartOffset+21;
  ascFreeNodeSize0  = ezdsStartOffset+22;
  ascEmptyExamine   = ezdsStartOffset+23;
  ascEmptyPop       = ezdsStartOffset+24;
  ascDeleteEdges    = ezdsStartOffset+25;
  ascExamineEdges   = ezdsStartOffset+26;
  ascInsertEdges    = ezdsStartOffset+27;
  ascReplaceEdges   = ezdsStartOffset+28;
  ascAlreadyAtEnd   = ezdsStartOffset+29;
  ascAlreadyAtStart = ezdsStartOffset+30;
  ascCannotJoinHere = ezdsStartOffset+31;
  ascCannotJoinData = ezdsStartOffset+32;
  ascSplitEdges     = ezdsStartOffset+33;
  ascOutOfRange     = ezdsStartOffset+34;
  ascExamineLeaf    = ezdsStartOffset+35;
  ascBadSkipLevel   = ezdsStartOffset+36;

Various string constants defining error and assertion conditions.
The strings themselved are held in EZDSLCTS.RES in a stringtable. 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.

const
  skMaxLevels = 16;

The maximum number of levels in a skip list. A skip list node will
never have more than this number of forward pointers.

type
  TChild = (CLeft, CRight);

For binary trees: flags for left and right children.

type
  TCompareFunc = function (Data1, Data2 : pointer) : integer of object;

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.

type
  TDisposeDataProc = procedure (aData : pointer) of object;

Procedure prototype for disposing a data object. The routine you write
must be a method of a class.

type
  TDupDataFunc = function (aData : pointer) : pointer of object;

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.

type
  TIterator = function  (C : TAbstractContainer; aData : pointer;
                         ExtraData : pointer) : boolean;

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.

type
  TListCursor = longint;

Navigation cursor for TDList and TSkipList (double linked & skip
lists).

type
  TTraversalType = (ttPreOrder, ttInOrder, ttPostOrder, ttLevelOrder);

For binary trees: the different methods of traversing their nodes.

type
  TTreeCursor = longint;

Navigation cursor for TBinTree and descendants (binary trees).

type
  TEZString = string[255];
  PEZString = ^TEZString;

Essentially for compatibility between Delphi 1 and Delphi 2/3: these
provide a much needed single type for short strings.

======================================================================

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.

======================================================================

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, the
  default one raises an exception when Compare is used. Note that you
  should only override it if it is required. For the single and doubly
  linked lists, for example, setting the Compare property forces the
  list to be sorted. For those containers that are sorted anyway, you
  must provide a Compare routine for the container.
  Setting the Compare property forces the container's data objects to
  be sorted according to that routine.

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 routine may be called with a nil pointer
           so please cater for this possibility and don't try to free
           a nil pointer.

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.

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.


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

Declaration
  constructor Create(DataOwner : boolean); virtual;
Description
  Creates the object. Descendants must set the NodeSize field before
  calling this as inherited constructor. If non-zero, this method
  gets a pointer to the relevent node store (if zero the descendant
  will be taking care of allocating/freeing nodes).  Sets the
  internal item counter to zero.  The DataOwner parameter determines
  whether the container is to own (ie can dispose of) its data
  objects.

Declaration
  destructor Destroy; override;
Description
  Destroys the container by calling the Empty method, detaches itself
  from the node store.

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.

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; ie it contains no data
  objects.


======================================================================

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.

Declaration
  constructor Clone(Source : TAbstractContainer;
                    DataOwner : boolean; NewCompare : TCompareFunc);
                                                            override;
Description
  Creates a copy of a Source stack.

Declaration
  procedure Empty; override;
Description
  Repeatedly calls the Pop method (disposing of the data object
  returned if a data owner) until the stack is empty.

Declaration
  function Examine : pointer;
Description