home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 January: Mac OS SDK / Dev.CD Jan 97 SDK2.toast / Development Kits (Disc 2) / OpenDoc Development Framework / ODFDev / ODF / Found / FWString / FWCharIt.h < prev    next >
Encoding:
Text File  |  1996-09-17  |  9.4 KB  |  274 lines  |  [TEXT/MPS ]
  1. //========================================================================================
  2. //
  3. //    File:                FWCharIt.h
  4. //    Release Version:    $ ODF 2 $
  5. //
  6. //    Copyright:    (c) 1993 - 1996 by Apple Computer, Inc., all rights reserved.
  7. //
  8. //========================================================================================
  9.  
  10. #ifndef FWCHARIT_H
  11. #define FWCHARIT_H
  12.  
  13. #ifndef   FWEXCLIB_H
  14. #include "FWExcLib.h"
  15. #endif
  16.  
  17. #ifndef FWPRIDEB_H
  18. #include "FWPriDeb.h"
  19. #endif
  20.  
  21. #ifndef FWCHARAC_H
  22. #include "FWCharac.h"
  23. #endif
  24.  
  25. #ifndef SLLOCALE_H
  26. #include "SLLocale.h"
  27. #endif
  28.  
  29. #ifndef SLCHARIT_H
  30. #include "SLCharIt.h"
  31. #endif
  32.  
  33. //========================================================================================
  34. // Forward Declarations
  35. //========================================================================================
  36.  
  37. class FW_OMemoryRunReader;
  38. class FW_OMemoryRunWriter;
  39. class FW_OTextRunReader;
  40. class FW_OTextRunWriter;
  41.  
  42. //========================================================================================
  43. //                            Design Notes for Text Readers
  44. //
  45. //    Text readers are designed to be as fast and light-weight as possible.  We assume
  46. //    that in over 90% of the usage of Text readers, the reader will be used to make
  47. //    one sequential pass through the data structure, operating on one character at a time.
  48. //    The first design goal is therefore:
  49. //        1) Make GetCharacterAndAdvance be as efficient as possible.
  50. //    In order to achieve full efficiency, we need to minimize overhead for error checking
  51. //    for reading past the end of the data structure.  We therefore set this requirement:
  52. //        2) Rely on a clear contract to minimize overhead.  It is not necessary for
  53. //        iterators to fail gracefully when misused.
  54. //    As stated above, in 90% of the cases, the text is read in one forward pass.  However,
  55. //  reading backward through the text is a surprisingly large portion of the remaining
  56. //  10%, and if not supported, significantly reduces the usefulness of readers.  We
  57. //    therefore attempt to achieve this goal:
  58. //        3) Make "put back" a relatively efficient operation.  Make it possible to
  59. //        read backwards through the data structure.
  60. //    Often a client iterating over text will want to note the position of some character
  61. //    or token in the text.  We therefore set another goal:
  62. //        4) Support GetPosition ('tell') and SetPosition ('seek') operations.
  63. //    This last goal implies a specific need to handle the case where a client attempts to
  64. //    seek past the end of the text data structure.  In this case, to achieve efficiency,
  65. //    we invoke 2), by setting this requirement:
  66. //        5) It is acceptable to state in the contract that an attempt to SetPosition to
  67. //        an arbitrary position may fail.  However, a client can use GetLength to find
  68. //        the length of the data structure; it is safe to SetPosition to any value greater
  69. //        than or equal to zero, and less than the length of the data structure.
  70. //========================================================================================
  71.  
  72. //========================================================================================
  73. //    CLASS FW_CTextReader
  74. //
  75. //    A base class for iterators that read over a data structure containing characters.
  76. //
  77. //    It is possible to create a TextReader to read over any text data structure, as long
  78. //    as the following constraints are met:
  79. //
  80. //    1) It must be possible to get the total number of characters in the data structure
  81. //       at the time the text reader is constructed.
  82. //    1a) Of course, we assume that the length and content of the data structure does
  83. //        not change while the iterator is being used!
  84. //    2) The data members fStart, fLimit, and fNext are updated
  85. //
  86. //
  87. //    Invariant:
  88. //        ((fStart<=fNext) && (fNext<fLimit))
  89. //     || ((fStart-1==fNext) && (fBufferSum==0))
  90. //     || ((fNext==fLimit) && (fBufferSum==GetLength())
  91. //========================================================================================
  92.  
  93. class FW_CTextReader
  94. {
  95. public:
  96.     FW_DECLARE_AUTO(FW_CTextReader)
  97.  
  98.     // ----- General
  99.     
  100.     virtual ~ FW_CTextReader();
  101.     FW_CTextReader(FW_OTextRunReader* adoptedReader);
  102.     FW_CTextReader(FW_HTextReader useReader);
  103.     
  104.     operator FW_HTextReader()
  105.         { return fRep; }
  106.  
  107.     FW_ByteCount GetPosition();
  108.         // Get the current byte position, where 0 is first position in data structure.
  109.  
  110.     void SetPosition(FW_ByteCount position);
  111.         // Set the byte position to position.
  112.         // The result is undefined if position is outside the bounds of the data structure.
  113.  
  114.     FW_ByteCount GetByteLength();
  115.         // Get number of bytes in data structure.
  116.     
  117.     const char* PeekByte() const;
  118.         // Return a pointer to the current byte without advancing. Can be used for lookahead.
  119.  
  120.     void GetLocale(FW_Locale& locale) const;
  121.         // Return the data structure's locale.
  122.  
  123.     // ----- Character-by-character iteration
  124.  
  125.     void Advance();
  126.         // Advance by one character.
  127.         
  128.     void Backup();
  129.         // Backup by one character.
  130.     
  131.     FW_LChar PeekCharacter();
  132.         // Return the current character without advancing.  
  133.         // Can be used for lookahead.
  134.  
  135.     FW_LChar GetCharacterAndAdvance();
  136.         // Get the current character and advance.
  137.  
  138.     FW_LChar BackupAndGetCharacter();
  139.         // Backup and get previous character (byte).
  140.  
  141.     FW_LChar GetCharacterAndAdvance(FW_ByteCount& bytesInChar);
  142.         // Get the current character and advance.
  143.     
  144.     FW_LChar PeekCharacter(FW_ByteCount& bytesInChar);
  145.         // Return the current character without advancing. 
  146.  
  147.     FW_LChar BackupAndGetCharacter(FW_ByteCount& bytesInChar);
  148.         // Backup and get previous character.
  149.     
  150.     // ----- Run iteration
  151.     //     With run iteration, the client is responsible for translating between bytes and characters.
  152.     
  153.     void Advance(FW_ByteCount delta);
  154.         // Advance by delta bytes.
  155.         // It is client's responsiblity to ensure that delta bytes is a whole number of characters!
  156.         
  157.     void Backup(FW_ByteCount delta);
  158.         // Backup by delta bytes.
  159.         // It is client's responsiblity to ensure that delta bytes is a whole number of characters!
  160.     
  161.     void PeekRunAhead(const char*& start, FW_ByteCount& length);
  162.         // Peek ahead into current buffer of bytes without advancing.
  163.     
  164.     void PeekRunBehind(const char*& end, FW_ByteCount& length);
  165.         // Peek behind into current buffer of bytes without backing up.
  166.         // end points one past "current" byte!
  167.  
  168. private:
  169.  
  170. #ifdef FW_DEBUG
  171.     void ClassInvariants() const;
  172. #else
  173.     void ClassInvariants() const {}    // Let compiler optimize away the empty inline
  174. #endif
  175.  
  176. private:
  177.  
  178.     FW_HTextReader        fRep;
  179.     FW_OTextRunReader*    fAdoptedReader;
  180. };
  181.  
  182. //========================================================================================
  183. //    CLASS FW_CTextWriter
  184. //
  185. //    TextWriters are (intentionally) kept simpler than TextReaders.  We assume that there
  186. //    is no need to allow backing up in order to rewrite.  This results in a smaller and
  187. //    simpler interface.
  188. //========================================================================================
  189.  
  190. class FW_CTextWriter
  191. {
  192. public:
  193.     FW_DECLARE_AUTO(FW_CTextWriter)
  194.  
  195.     // ----- General
  196.     
  197.     virtual ~ FW_CTextWriter();
  198.         // Flush the current buffer.
  199.         // Writer destructors must do whatever may be necessary to restore text structure
  200.         // to valid state, e.g. restore NUL termination, cached length member, etc.
  201.  
  202.     FW_CTextWriter(FW_OTextRunWriter* adoptedWriter);
  203.     
  204.     FW_CTextWriter(FW_HTextWriter rep);
  205.     
  206.     operator FW_HTextWriter()
  207.         { return fRep; }
  208.     
  209.     FW_ByteCount GetPosition();
  210.         // Get the current byte position, where 0 is first position in data structure.
  211.  
  212.     // ----- Character-by-character iteration
  213.  
  214.     void PutCharacterAndAdvance(FW_LChar character, FW_ByteCount bytesInChar=0);
  215.         // Write the character into the data structure and advance to next position.
  216.         // If byte length of character is known, pass it along for efficiency.
  217.         // If byte length is not known, pass 0 and the length will be computed.
  218.  
  219.     // ----- Chunky iteration
  220.     
  221.     void WritePeek(char*& start, FW_ByteCount& length);
  222.         // Returns start address and length of buffer to write into.
  223.     
  224.     void WritePeekAdvance(char* start, FW_ByteCount bytesWritten);
  225.         // Inform iterator of number of bytes written into peek buffer
  226.         // start value must be same as returned by WritePeek
  227.         // No calls to PutCharacterAndAdvance between WritePeek and WritePeekAdvance!
  228.  
  229.     void FlushBuffer();
  230.         // Calls DoFlushBuffer to flush the current buffer, and updates fBufferSum.
  231.         // A subclass may want to call this function in it's destructor if it needs
  232.         // to defer final cleanup until after the buffer has been flushed.
  233.  
  234.   protected:
  235.   
  236.       void SetBufferSum(FW_ByteCount bufferSum);
  237.  
  238.     void FlushAndGetNextBuffer();
  239.         // Calls FlushBuffer and DoGetNextBuffer.
  240.         // Called when the buffer has filled up.
  241.  
  242. private:
  243.     FW_HTextWriter        fRep;
  244.     FW_OTextRunWriter*    fAdoptedWriter;
  245. };
  246.  
  247. //========================================================================================
  248. //    CLASS FW_CMemoryReader
  249. //========================================================================================
  250.  
  251. class FW_CMemoryReader : public FW_CTextReader
  252. {
  253. public:
  254.     virtual ~FW_CMemoryReader();
  255.     FW_CMemoryReader(const char * buffer, FW_ByteCount bytes);
  256.     static FW_OMemoryRunReader* MakeReader(char * buffer, FW_ByteCount length, FW_Locale* locale = NULL);
  257. };
  258.  
  259. //========================================================================================
  260. //    CLASS FW_CMemoryWriter
  261. //
  262. //    A class for writing into a buffer of characters.
  263. //========================================================================================
  264.  
  265. class FW_CMemoryWriter : public FW_CTextWriter
  266. {
  267. public:
  268.     virtual ~FW_CMemoryWriter();
  269.     FW_CMemoryWriter(char * buffer, FW_ByteCount capacity);
  270.     static FW_OMemoryRunWriter* MakeWriter(char * buffer, FW_ByteCount capacity);
  271. };
  272.  
  273. #endif
  274.