home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / World_Of_Computer_Software-02-385-Vol-1of3.iso / o / opuniq.zip / OPUNIQUE.DOC < prev    next >
Text File  |  1990-10-25  |  5KB  |  119 lines
  1. OPUNIQUE - StringArray that maintains a single copy of each string
  2. ------------------------------------------------------------------
  3. TurboPower Software
  4. 10/25/90
  5.  
  6. Introduction
  7. --------------------------------------------------------------------------
  8. OPUNIQUE implements the UniqueStringArray object, which is derived from
  9. OPROOT's StringArray. The major difference in UniqueStringArray's behavior
  10. occurs when you call AddString, specifying a string that's already been added
  11. to the array. StringArray allocates additional space for a second copy of the
  12. string and returns a unique index number. UniqueStringArray determines that
  13. the string is already in the array and returns the index of the existing copy.
  14.  
  15. UniqueStringArray works in concert with the Tree object of the OPTREE unit,
  16. also included here. The Tree is used to quickly determine whether a given
  17. string is already in the StringArray. The space overhead of the Tree is fairly
  18. small because each node contains only a Word index into the StringArray
  19. itself.
  20.  
  21. Compatibility Issues
  22. --------------------------------------------------------------------------
  23. In order to efficiently implement the UniqueStringArray, two methods of
  24. StringArray were made virtual. If you have OPRO version 1.03 or earlier,
  25. you'll need to modify your OPROOT.PAS source code to add the keyword "virtual"
  26. after the declaration for AddString and RemoveString.
  27.  
  28. The RemoveString method was added to the OPROOT StringArray in version 1.03.
  29. If you have an earlier version, you'll need to comment out all OPUNIQUE.PAS
  30. source code that refers to StringArray.RemoveString.
  31.  
  32. The Load and Store methods of UniqueStringArray are not meant to be called. At
  33. this time stream support is not supplied for this object, because it would
  34. require adding stream support to the Tree object as well.
  35. UniqueStringArray.Load will always Fail and Store does nothing.
  36.  
  37. Using UniqueStringArray
  38. --------------------------------------------------------------------------
  39. UniqueStringArray is used like a StringArray in almost all respects. It offers
  40. the following methods, whose brief descriptions indicate how the methods
  41. differ from StringArray.
  42.  
  43. function AddString(St : String) : Word; virtual;
  44.   {-Add a new string, returning its index, or 0 if error}
  45.  
  46.   As indicated above, AddString returns the index of the existing string if St
  47.   matches a string added already. Note that UniqueStringArray's AddString
  48.   method must also allocate a binary tree node in many cases. If there is
  49.   insufficient heap space to do so, AddString returns 0.
  50.  
  51. procedure Clear;
  52.   {-Remove all strings from array}
  53.  
  54.   Clear calls StringArray.Clear and also Tree.Clear. StringArray.Clear leaves
  55.   the string buffers allocated but marks them empty. Tree.Clear deallocates
  56.   all tree nodes.
  57.  
  58. destructor Done; virtual;
  59.   {-Deallocate array}
  60.  
  61.   Disposes of the binary tree and calls StringArray.Done.
  62.  
  63. function GetTreePtr : IndexTreePtr;
  64.   {-Return address of associated IndexTree}
  65.  
  66.   Returns the address of the associated binary tree. You can then call the
  67.   Tree object's methods. See the WORDS.PAS example program.
  68.  
  69. constructor Init(StrMax, Amount : Word);
  70.   {-Allocate space for StrMax strings in Amount space}
  71.  
  72.   Calls StringArray.Init and also initializes the binary tree.
  73.  
  74. {$IFDEF UseStreams}
  75. constructor Load(var S : IdStream);
  76.   {-Load a binary packed array from a stream. NOT SUPPORTED}
  77.  
  78.   This method always fails. Streams are not supported for the
  79.   UniqueStringArray at this time.
  80.  
  81. procedure RemoveString(Which : Word); virtual;
  82.   {-Remove specified string from array and pack character table}
  83.  
  84.   Calls StringArray.RemoveString and the tree's Remove method as well. Note
  85.   that the method doesn't keep track of how many "users" of a given string
  86.   there are: the string is removed on the first call to RemoveString
  87.   regardless of how many times AddString was called.
  88.  
  89. procedure RemoveStringByName(St : String);
  90.   {-Remove named string}
  91.  
  92.   This method finds the string St by lookup in the binary tree. If the string
  93.   is not found, RemoveStringByName does nothing. Otherwise, it calls
  94.   RemoveString.
  95.  
  96. {$IFDEF UseStreams}
  97. procedure Store(var S : IdStream);
  98.   {-Write a packed array to a stream. NOT SUPPORTED}
  99.  
  100.   This method does nothing. Streams are not supported for the
  101.   UniqueStringArray at this time.
  102.  
  103. The WORDS.PAS Example Program
  104. --------------------------------------------------------------------------
  105. WORDS.PAS is a simple demonstration of using UniqueStringArray. It reads a
  106. text file, parses it into words, and adds the words to a UniqueStringArray.
  107. When end of file is reached, WORDS dumps the UniqueStringArray in alphabetical
  108. order. WORDS is limited to 5000 unique words maximum, or 64K bytes of packed
  109. strings, whichever comes first.
  110.  
  111. Copyright Information
  112. --------------------------------------------------------------------------
  113. OPUNIQUE and OPTREE require Object Professional to compile. OPUNIQUE and
  114. OPTREE may be distributed freely among owners of Object Professional and used
  115. under the terms of the Object Professional license agreement.
  116.  
  117. For questions, suggestions, or problems regarding OPUNIQUE, contact Kim
  118. Kokkonen at TurboPower. CompuServe ID 76004,2611
  119.