CoreUtils/ZString.h

#ifndef __ZString_h__
#define __ZString_h__

#include "includes"

namespace coreutils {

   ///
   /// Use the ZString object when advanced parsing algorithms are required to simplify
   /// parsing. ZString is not a backing store and requires that any referenced buffer 
   /// or objects are retained throughout the life of the object. Additionally, ZString
   /// is non-destructive to its underlying references.
   ///
   /// ZString provides several methods to reference and parse the content. First method
   /// is parse(ZString delimiter) which will return a vector of ZString which contains
   /// references to the parts of the string split by the provided delimiter. The delimiter
   /// portion is omitted from the results.
   ///
   /// Second method involves a cursor which is a pointer to data contained within the 
   /// ZString and is used to point to the current parsing point. Several methods are
   /// provided to advance through the parsing based upon content and rule checks. 
   ///

   class ZString {

    public:

      ///
      /// Consructor providing an empty ZString..
      ///
      
      ZString();

      ///
      /// Copy constructor.
      ///

      ZString(const ZString&);

      ///
      ///
      ///
      
      ZString(const char *data);
      
      ///
      /// Consructor providing the initial setup of the ZString object.
      ///

      ZString(char *data, size_t length);

      ///
      /// Consructor providing a copy of a ZString.
      ///

      ZString(ZString &zstring);

      ///
      /// A friend method used to write the value of the ZString from the cursor
      /// point to an ostream using the << syntax.
      ///

      friend std::ostream& operator<<(std::ostream& os, const ZString& zstring);
    
      ///
      /// Return a vector of ZString objects which contain the parts established
      /// by using the split method and passing a delimiter value. 
      ///

      std::vector<ZString> & getList();

      ///
      /// Return the integer value of the ZString from the cursor to the first 
      /// non-numeric character. 
      ///
      
      int asInteger();
      
      ///
      /// Return the value of the ZString from the cursor to the end.
      ///

      std::string str();

      ///
      /// Return the current value of the ZString as a string of 
      /// specified length.
      ///

      std::string str(int len);

      ///
      ///
      ///

      std::vector<ZString> split(ZString delimiter, size_t maxSize = 0);

      ///
      /// Use getTokenInclude with a list of character to allow the forwarding
      /// of the cursor through the data until a character that is not in the 
      /// include string is not encountered in the ZString data.  
      ///

      ZString getTokenInclude(char *include);

      ///
      ///
      ///

      ZString getTokenExclude(char *exclude);

      ///
      /// Use the [] operator to retrieve values delimited by the split method.
      ///

      ZString operator[](int index);

      ///
      /// Return true if the ZString cursor is at the end of the data.
      ///

      bool eod();

      ///
      ///
      ///
      
      bool equals(const char *value);
      
      ///
      ///
      ///
      
      bool equals(ZString zstring);
      
      ///
      /// Advance the cursor the length of the provided value if the value at
      /// the cursor position is equal to the value provided.
      ///

      bool ifNext(char *value);

      ///
      /// Advance the cursor through the ZString for each whitespace character
      /// encountered.
      ///

      int skipWhitespace();

      ///
      ///
      ///

      ZString goeol();

      ///
      /// Return a block of data as a ZString from the cursor location for
      /// the number of bytes specified by size. 
      ///

      ZString readBlock(size_t size);

      ///
      /// Return a pointer to the beginning of the ZString data.
      ///

      char* getData(); 

      ///
      /// Return the length of the ZString. 
      ///

      size_t getLength();
      
      ///
      /// Set this ZString to have the same data space as the ZString pointer
      /// passed into the method.
      ///
      
      void setZString(ZString zstring);

    private:
      char *data;
      size_t length;
      char *cursor;
      std::vector<ZString> list;

   };

}

#endif