OPUNIQUE - StringArray that maintains a single copy of each string
------------------------------------------------------------------
TurboPower Software
10/25/90

Introduction
--------------------------------------------------------------------------
OPUNIQUE implements the UniqueStringArray object, which is derived from
OPROOT's StringArray. The major difference in UniqueStringArray's behavior
occurs when you call AddString, specifying a string that's already been added
to the array. StringArray allocates additional space for a second copy of the
string and returns a unique index number. UniqueStringArray determines that
the string is already in the array and returns the index of the existing copy.

UniqueStringArray works in concert with the Tree object of the OPTREE unit,
also included here. The Tree is used to quickly determine whether a given
string is already in the StringArray. The space overhead of the Tree is fairly
small because each node contains only a Word index into the StringArray
itself.

Compatibility Issues
--------------------------------------------------------------------------
In order to efficiently implement the UniqueStringArray, two methods of
StringArray were made virtual. If you have OPRO version 1.03 or earlier,
you'll need to modify your OPROOT.PAS source code to add the keyword "virtual"
after the declaration for AddString and RemoveString.

The RemoveString method was added to the OPROOT StringArray in version 1.03.
If you have an earlier version, you'll need to comment out all OPUNIQUE.PAS
source code that refers to StringArray.RemoveString.

The Load and Store methods of UniqueStringArray are not meant to be called. At
this time stream support is not supplied for this object, because it would
require adding stream support to the Tree object as well.
UniqueStringArray.Load will always Fail and Store does nothing.

Using UniqueStringArray
--------------------------------------------------------------------------
UniqueStringArray is used like a StringArray in almost all respects. It offers
the following methods, whose brief descriptions indicate how the methods
differ from StringArray.

function AddString(St : String) : Word; virtual;
{-Add a new string, returning its index, or 0 if error}

As indicated above, AddString returns the index of the existing string if St
matches a string added already. Note that UniqueStringArray's AddString
method must also allocate a binary tree node in many cases. If there is
insufficient heap space to do so, AddString returns 0.

procedure Clear;
{-Remove all strings from array}

Clear calls StringArray.Clear and also Tree.Clear. StringArray.Clear leaves
the string buffers allocated but marks them empty. Tree.Clear deallocates
all tree nodes.

destructor Done; virtual;
{-Deallocate array}

Disposes of the binary tree and calls StringArray.Done.

function GetTreePtr : IndexTreePtr;
{-Return address of associated IndexTree}

Returns the address of the associated binary tree. You can then call the
Tree object's methods. See the WORDS.PAS example program.

constructor Init(StrMax, Amount : Word);
{-Allocate space for StrMax strings in Amount space}

Calls StringArray.Init and also initializes the binary tree.

{$IFDEF UseStreams}
constructor Load(var S : IdStream);
{-Load a binary packed array from a stream. NOT SUPPORTED}

This method always fails. Streams are not supported for the
UniqueStringArray at this time.

procedure RemoveString(Which : Word); virtual;
{-Remove specified string from array and pack character table}

Calls StringArray.RemoveString and the tree's Remove method as well. Note
that the method doesn't keep track of how many "users" of a given string
there are: the string is removed on the first call to RemoveString
regardless of how many times AddString was called.

procedure RemoveStringByName(St : String);
{-Remove named string}

This method finds the string St by lookup in the binary tree. If the string
is not found, RemoveStringByName does nothing. Otherwise, it calls
RemoveString.

{$IFDEF UseStreams}
procedure Store(var S : IdStream);
{-Write a packed array to a stream. NOT SUPPORTED}

This method does nothing. Streams are not supported for the
UniqueStringArray at this time.

The WORDS.PAS Example Program
--------------------------------------------------------------------------
WORDS.PAS is a simple demonstration of using UniqueStringArray. It reads a
text file, parses it into words, and adds the words to a UniqueStringArray.
When end of file is reached, WORDS dumps the UniqueStringArray in alphabetical
order. WORDS is limited to 5000 unique words maximum, or 64K bytes of packed
strings, whichever comes first.

Copyright Information
--------------------------------------------------------------------------
OPUNIQUE and OPTREE require Object Professional to compile. OPUNIQUE and
OPTREE may be distributed freely among owners of Object Professional and used
under the terms of the Object Professional license agreement.

For questions, suggestions, or problems regarding OPUNIQUE, contact Kim
Kokkonen at TurboPower. CompuServe ID 76004,2611