CoreUtils/ZString.h

#ifndef __ZString_h__
#define __ZString_h__

#include <string.h>
#include <string>
#include <ostream>
#include <vector>

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 split(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();

      ///
      ///
      ///

      ZString(const char *data);

      ///
      /// Consructor providing the initial setup of the ZString object.
      ///

      ZString(char *data, size_t length);

      ZString(const char *data, size_t length);

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

      ZString(const ZString &zstring);

      ///
      /// Consructor from a string.
      ///

      ZString(std::string string);

      ///
      /// 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);
      friend std::ostream& operator<<(std::ostream& os, const std::string& string);
      friend std::ostream& operator+(std::ostream& os, const ZString& zstring);

      bool operator<(const ZString &valuex) const;
      bool operator>(const ZString &valuex) const;
      bool operator==(const ZString &valuex) const;

      ///
      /// 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);

      ///
      ///
      ///

      std::vector<ZString> &split(std::string 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(const char *include);

      ///
      ///
      ///

      ZString getTokenExclude(const char *exclude);

      ZString getTokenExclude(std::string 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(char *value);

      ///
      ///
      ///

      bool equals(ZString &zstring);

      ///
      ///
      ///

      bool equals(std::string &string);

      ///
      /// Advance the cursor the length of the provided value if the value at
      /// the cursor position is equal to the value provided.
      ///

      bool ifNext(const char *value);

      int ifEqualsCount(ZString &comparator);

      ///
      /// 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);

      ///
      ///
      ///

      void reset();

      ///
      ///
      ///

      char charAt(int index);

      ///
      ///
      ///

      bool ifCRLF();

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

      bool isCharacter(char ch, const char *string);

   };

}

#endif