nucleus/library/basis/astring.h

   1 #ifndef ASTRING_CLASS
   2 #define ASTRING_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : astring                                                           *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *******************************************************************************
  10 * Copyright (c) 1992-$now By Author.  This program is free software; you can  *
  11 * redistribute it and/or modify it under the terms of the GNU General Public  *
  12 * License as published by the Free Software Foundation; either version 2 of   *
  13 * the License or (at your option) any later version.  This is online at:      *
  14 *     http://www.fsf.org/copyleft/gpl.html                                    *
  15 * Please send any updates to: fred@gruntose.com                               *
  16 \*****************************************************************************/
  17
  18 #include "base_string.h"
  19 #include "byte_array.h"
  20 #include "contracts.h"
  21
  22 #include <stdarg.h>
  23
  24 namespace basis {
  25
  26 //! Provides a dynamically resizable ASCII character string.
  27 /*!
  28   It mimics the standard (char *) type, but provides a slew of helpful
  29   methods as well as enforcing bounds checking on the underlying array.
  30 */
  31
  32 class astring
  33 : public virtual base_string,
  34   public virtual hoople_standard
  35 {
  36 public:
  37   astring();
  38     //!< constructs an empty string.
  39
  40   astring(const char *initial);
  41     //!< constructs a copy of the string passed in "initial".
  42
  43   astring(char c, int repeat);
  44     //!< constructs a string with "repeat" characters of "c" in it.
  45     /*!< if "c" is the null character (i.e., equal to zero), then the resulting
  46          string will have "repeat" space characters in it. */
  47
  48   astring(const astring &s);
  49     //!< Constructs a copy of the string "s".
  50
  51   astring(const base_string &initial);
  52     //!< constructs a string from the base class.
  53
  54   enum special_flag { UNTERMINATED = 62, SPRINTF = 84 };
  55   astring(special_flag way, const char *s, ...);
  56     //!< constructor that sports a few variable parameter constructions.
  57     /*!<
  58     For a flag of "UNTERMINATED", the constructor expects the third
  59     parameter to be an integer, and then it copies that number of
  60     characters from the C-string "s" without assuming that "s" is zero
  61     terminated.
  62
  63     For a flag of "SPRINTF", a string is constructed using the format specifier
  64     in "s" in a manner similar to the standard library "sprintf" function
  65     (see the standard library for <string.h>).  If there are no "%" codes in
  66     "s", then the constructor just copies "s" without modification.  If "%"
  67     codes are in the character array, then any additional arguments (...) are
  68     interpreted as they would be by sprintf.  The length of the
  69     constructed string is tailored to fit the actual contents.  If "s" is
  70     null, then the resulting string will be empty.  Currently, the "*"
  71     specifier for variable length fields is not supported. */
  72
  73   virtual ~astring();
  74     //!< destroys any storage for the string.
  75
  76   DEFINE_CLASS_NAME("astring");
  77
  78   virtual int comparator(const astring &s2) const;
  79     //!< helps to fulfill orderable contract.
  80
  81   int length() const;
  82     //!< Returns the current length of the string.
  83     /*!< The length returned does not include the terminating null character
  84     at the end of the string. */
  85
  86   int end() const { return length() - 1; }
  87     //!< returns the index of the last (non-null) character in the string.
  88     /*!< If there is no content in the string, then a negative value is
  89     returned. */
  90
  91   bool empty() const { return !length(); }
  92     //!< empty() reports if the string is empty, that is, of zero length().
  93   bool non_empty() const { return !empty(); }
  94     //!< non_empty() reports if the string has some contents.
  95   bool operator ! () const { return empty(); }
  96     //!< the negation operator returns true if the string is empty.
  97     /*!< it can be used in expressions in a readable way, for example:
  98       if (!my_string) { it_is_empty; } */
  99   bool t() const { return !empty(); }
 100     //!< t() is a shortcut for the string being "true", as in non-empty.
 101     /*!< the logic here is that the string is not false because it's not
 102     empty.  for example: if (my_string.t()) { it_is_not_empty; } */
 103
 104   static const astring &empty_string();
 105     //!< useful wherever empty strings are needed, e.g., function defaults.
 106     /*!< note that this is implemented in the opsystem library to avoid bad
 107     issues with static objects mixed into multiple dlls from a static
 108     library. */
 109
 110   virtual const char *observe() const;
 111     //!< observes the underlying pointer to the zero-terminated string.
 112     /*!< this does not allow the contents to be modified.  this method should
 113     never return NULL_POINTER. */
 114   const char *c_str() const { return observe(); }
 115     //!< synonym for observe.  mimics the STL method name.
 116   const char *s() const { return observe(); }
 117     //!< synonym for observe.  the 's' stands for "string", if that helps.
 118
 119   virtual char get(int index) const;
 120     //!< a constant peek at the string's internals at the specified index.
 121
 122   virtual char *access();
 123     //!< provides access to the actual string held.
 124     /*!< this should never return NULL_POINTER.  be very careful with the returned
 125     pointer: don't destroy or corrupt its contents (e.g., do not mess with
 126     its zero termination). */
 127   char *c_str() { return access(); }
 128     //!< synonym for access.  mimics the STL method.
 129   char *s() { return access(); }
 130     //!< synonym for access.
 131
 132   char &operator [] (int position);
 133     //!< accesses individual characters in "this" string.
 134     /*!< if the "position" is out of range, the return value is
 135     not meaningful. */
 136   const char &operator [] (int position) const;
 137     //!< observes individual characters in "this" string.
 138     /*!< if the "position" is out of range, the return value is
 139     not meaningful. */
 140
 141   virtual void put(int position, char to_put) { (*this)[position] = to_put; }
 142     //!< stores the character "to_put" at index "position" in the string.
 143
 144   astring &sprintf(const char *s, ...);
 145     //!< similar to the SPRINTF constructor, but works on an existing string.
 146     /*!< any existing contents in the string are wiped out. */
 147
 148   int convert(int default_value) const;
 149     //!< Converts the string into a corresponding integer.
 150     /*!< The conversion starts at index 0 in "this" string, and stores it in
 151     "value".  If a valid integer was found, it is returned.  otherwise, the
 152     "default_value" is returned.  NOTE: be careful of implicit conversions
 153     here; the "default_value" for any of these functions must either be an
 154     object of the exact type needed or must be cast to that type. */
 155   long convert(long default_value) const;
 156     //!< converts the string to a long integer.
 157   float convert(float default_value) const;
 158     //!< converts the string to a floating point number.
 159   double convert(double default_value) const;
 160     //!< converts the string to a double precision floating point number.
 161
 162   bool equal_to(const char *that) const;
 163     //!< returns true if "that" is equal to this.
 164
 165   bool iequals(const astring &that) const;
 166     //!< returns true if this is case-insensitively equal to "that".
 167   bool iequals(const char *that) const;
 168     //!< returns true if this is case-insensitively equal to "that".
 169
 170   bool compare(const astring &to_compare, int start_first,
 171           int start_second, int count, bool case_sensitive) const;
 172     //!< Compares "this" string with "to_compare".
 173     /*!< The "start_first" is where the comparison begins in "this" string,
 174     and "start_second" where it begins in the "to_compare".  The "count" is
 175     the number of characters to compare between the two strings.  If either
 176     index is out of range, or "count"-1 + either index is out of range, then
 177     compare returns false.  If the strings differ in that range, false is
 178     returned.  Only if the strings have identical contents in the range is
 179     true returned. */
 180
 181   bool begins(const astring &maybe_prefix) const
 182         { return compare(maybe_prefix, 0, 0, maybe_prefix.length(), true); }
 183     //!< Returns true if "this" string begins with "maybe_prefix".
 184
 185   bool ibegins(const astring &maybe_prefix) const
 186         { return compare(maybe_prefix, 0, 0, maybe_prefix.length(), false); }
 187     //!< a case-insensitive method similar to begins().
 188
 189   //! returns true if this string ends with "maybe_suffix".
 190   bool ends(const astring &maybe_suffix) const {
 191     const int diff = length() - maybe_suffix.length();
 192     return (diff >= 0) && compare(maybe_suffix, diff, 0, maybe_suffix.length(), true);
 193   }
 194   //!< a case-insensitive method similar to ends().
 195   bool iends(const astring &maybe_suffix) const {
 196     const int diff = length() - maybe_suffix.length();
 197     return (diff >= 0) && compare(maybe_suffix, diff, 0, maybe_suffix.length(), false);
 198   }
 199
 200   astring &operator = (const astring &s);
 201     //!< Sets the contents of this string to "s".
 202   astring &operator = (const char *s);
 203     //!< Sets the contents of this string to "s".
 204
 205   void reset() { zap(0, end()); }
 206     //!< clears out the contents string.
 207
 208   void reset(special_flag way, const char *s, ...);
 209     //!< operates like the constructor that takes a 'special_flag'.
 210
 211   void copy(char *to_stuff, int count) const;
 212     //!< Copies a maximum of "count" characters from this into "to_stuff".
 213     /*!< The target "to_stuff" is a standard C-string.  The terminating zero
 214     from this string is also copied.  BE CAREFUL: if "count"+1 is greater than
 215     the allocated length of the C-string "to_stuff", then an invalid memory
 216     write will occur.  keep in mind that the terminating zero will be put at
 217     position "count" in the C-string if the full "count" of characters are
 218     copied. */
 219   void stuff(char *to_stuff, int count) const { copy(to_stuff, count); }
 220     //!< a synonym for copy().
 221
 222   astring operator + (const astring &s) const;
 223     //!< Returns the concatenation of "this" and "s".
 224
 225   astring &operator += (const astring &s);
 226     //!< Modifies "this" by concatenating "s" onto it.
 227
 228   astring &operator += (const char *s);  // this is efficient.
 229     //!< synonym for the concatenation operator but uses a char pointer instead.
 230   astring operator + (const char *s) const { return *this + astring(s); }
 231     //!< synonym for the concatenation operator but uses a char pointer instead.
 232     // this method is not efficient.
 233
 234   astring &operator += (char c);  //!< concatenater for single characters.
 235
 236   int find(char to_find, int position = 0, bool reverse = false) const;
 237     //!< Locates "to_find" in "this".
 238     /*!<  find returns the index of "to_find" or "NOT_FOUND".  find starts
 239     looking at "position".  find returns "OUT_OF_RANGE" if the position is
 240     beyond the bounds of "this". */
 241   int find(const astring &to_find, int posn = 0, bool reverse = false) const;
 242     //!< finds "to_find" in this string.
 243
 244   int ifind(char to_find, int position = 0, bool reverse = false) const;
 245     //!< like the find() methods above, but case-insensitive.
 246   int ifind(const astring &to_find, int posn = 0, bool reverse = false) const;
 247     //!< like the find() methods above, but case-insensitive.
 248
 249   int find_any(const char *to_find, int position = 0,
 250           bool reverse = false) const;
 251     //!< searches for any of the characters in "to_find".
 252     /*!<  the first occurrence of any of those is returned, or a negative
 253     number is returned if no matches are found. */
 254   int ifind_any(const char *to_find, int position = 0,
 255           bool reverse = false) const;
 256     //!< searches case-insensitively for any of the characters in "to_find".
 257     /*!< the first occurrence of any of those is returned, or a negative number
 258     is returned if none are found. */
 259   int find_non_match(const char *to_find, int position = 0,
 260           bool reverse = false) const;
 261     //!< searches for any character that is not in "to_find" and returns index.
 262
 263   bool contains(const astring &to_find) const;
 264     //!< Returns true if "to_find" is contained in this string or false if not.
 265
 266   bool substring(astring &target, int start, int end) const;
 267     //!< a version that stores the substring in an existing "target" string.
 268
 269   astring substring(int start, int end) const;
 270     //!< Returns the segment of "this" between the indices "start" and "end".
 271     /*!< An empty string is returned if the indices are out of range. */
 272
 273   // helper methods similar to other string's choppers.
 274   astring middle(int start, int count);
 275     //!< returns the middle of the string from "start" with "count" characters.
 276   astring left(int count);
 277     //!< returns the left "count" characters from the string.
 278   astring right(int count);
 279     //!< returns the right "count" characters from the string.
 280
 281   void pad(int length, char padding = ' ');
 282     //!< makes the string "length" characters long.
 283     /*!< this string is padded with the "padding" character if the string is
 284     less than that length initially. */
 285   void trim(int length);
 286     //!< shortens the string to "length" if it's longer than that.
 287
 288   void insert(int position, const astring &to_insert);
 289     //!< Copies "to_insert" into "this" at the "position".
 290     /*!<  Characters at the index "position" and greater are moved over. */
 291   virtual void zap(int start, int end);
 292     //!< Deletes the characters between "start" and "end" inclusively.
 293     /*!< C++ array conventions are used (0 through length()-1 are valid).  If
 294     either index is out of bounds, then the string is not modified. */
 295
 296   void to_lower();
 297     //!< to_lower modifies "this" by replacing capitals with lower-case.
 298     /*!< every capital letter is replaced with the corresponding lower case
 299     letter (i.e., A becomes a). */
 300   void to_upper();
 301     //!< to_upper does the opposite of to_lower (that is, q becomes Q).
 302   astring lower() const;
 303     //!< like to_lower(), but returns a new string rather than modifying this.
 304   astring upper() const;
 305     //!< like to_upper(), but returns a new string rather than modifying this.
 306
 307   bool replace(const astring &tag, const astring &replacement);
 308     //!< replaces the first occurrence of "tag" text with the "replacement".
 309     /*!< true is returned if the "tag" was actually found and replaced. */
 310   bool replace_all(char to_replace, char new_char);
 311     //!< changes all occurrences of "to_replace" with "new_char".
 312   bool replace_all(const astring &to_replace, const astring &new_string);
 313     //! changes all occurrences of "to_replace" into "new_string".
 314
 315   void shrink();
 316     //!< resizes the string to its minimum possible length.
 317     /*!< this fixes any situations where a null character has been inserted
 318     into the middle of the string.  the string is truncated after the first
 319     null charater encountered and its size is corrected.  this also repairs
 320     any case where the string was originally longer than it is now. */
 321
 322   enum how_to_strip { FROM_FRONT = 1, FROM_END = 2, FROM_BOTH_SIDES = 3 };
 323     //!< an enumeration describing the strip operations.
 324
 325   void strip(const astring &strip_list, how_to_strip way = FROM_BOTH_SIDES);
 326     //!< strips all chars from "strip_list" out of "this" given the "way".
 327
 328   void strip_spaces(how_to_strip way = FROM_BOTH_SIDES)
 329           { strip(" ", way); }
 330     //!< removes excess space characters from string's beginning, end or both.
 331
 332   void strip_white_spaces(how_to_strip way = FROM_BOTH_SIDES)
 333           { strip(" \t", way); }
 334     //!< like strip_spaces, but includes tabs in the list to strip.
 335
 336   static bool matches(const astring &match_list, char to_match);
 337     //!< returns true if "to_match" is found in the "match_list" string.
 338
 339   int packed_size() const;
 340     //!< Reports the size required to pack this string into a byte array.
 341
 342   void pack(byte_array &target) const;
 343     //!< stores this string in the "target".  it can later be unpacked again.
 344   bool unpack(byte_array &source);
 345     //!< retrieves a string (packed with pack()) from "source" into this string.
 346     /*!< note that the string is grabbed from the array destructively; whatever
 347     portion of the byte array was used to store the string will be removed from
 348     the head of the array. */
 349
 350 //hmmm: rename this--it is not a simple icompare, but a strncasecmp analogue.
 351 //  int icompare(const astring &to_compare, int length = -1) const;
 352     //!< provides a case insensitive comparison routine.
 353     /*!< this uses the best methods available (that is, it uses a system
 354     function if one exists).  the string "to_compare" is compared with this
 355     string.  if the "length" is negative, then this entire string is compared
 356     with the entire string "to_compare".  otherwise, only "length" characters
 357     from this string are compared.  if this string is before "to_compare" in
 358     a lexicographic ordering (basically alphabetical), then a negative number
 359     is returned.  if this string is after "to_compare", then a positive number
 360     is returned.  zero is returned if the two strings are equal for the extent
 361     of interest. */
 362
 363 ///  int icompare(const char *to_compare, int length = -1) const;
 364     //!< a version of the above for raw character pointers.
 365
 366 ///  static int slow_strncasecmp(const char *first, const char *second,
 367 ///          int length = -1);
 368     //!< a replacement for strncasecmp on platforms without them.
 369     /*!< this is slow because it cannot rely on OS methods to perform the
 370     comparison.  if the "length" is negative, then the entire string "first"
 371     is compared to "second".  otherwise just "length" characters are compared.
 372     this follows the standard library strncasecmp method: the return value can
 373     be in three states: negative, zero and positive.  zero means the strings
 374     are identical lexicographically , whereas less than zero means
 375     "this_string" is less than "to_compare" and greater than zero means
 376     "this_string" is greater than "to_compare". */
 377
 378   // play-yard for implementing base class requirements.
 379
 380   // these implement the orderable and equalizable interfaces.
 381   virtual bool equal_to(const equalizable &s2) const;
 382   virtual bool less_than(const orderable &s2) const;
 383
 384   virtual base_string &concatenate_string(const base_string &s);
 385   virtual base_string &concatenate_char(char c);
 386   virtual base_string &assign(const base_string &s);
 387   virtual base_string &upgrade(const char *s);
 388   virtual bool sub_string(base_string &target, int start, int end) const;
 389   virtual bool sub_compare(const base_string &to_compare, int start_first,
 390       int start_second, int count, bool case_sensitive) const;
 391   virtual void insert(int position, const base_string &to_insert);
 392   virtual void text_form(base_string &state_fill) const;
 393
 394 private:
 395   byte_array c_character_manager;
 396     //!< hides the real object responsible for implementing much of the class.
 397
 398   // the real find methods.
 399   int char_find(char to_find, int position, bool reverse,
 400           bool case_sense) const;
 401   // if "invert_find" is true, then non-matches are reported instead of matches.
 402   int char_find_any(const astring &to_find, int position, bool reverse,
 403           bool case_sense, bool invert_find = false) const;
 404   int str_find(const astring &to_find, int posn, bool reverse,
 405           bool case_s) const;
 406
 407   // the functions below are used in the formatting string constructor.
 408 public:  // only for base_sprintf.
 409   astring &base_sprintf(const char *s, va_list &args);
 410 private:
 411   char *const *c_held_string;  //!< peeks into the actual pointer for debugging.
 412
 413   void seek_flag(const char *&traverser, char *flag_chars, bool &failure);
 414     //!< looks for optional flag characters.
 415   void seek_width(const char *&traverser, char *width_chars);
 416     //!< looks for optional width characters.
 417   void seek_precision(const char *&traverser, char *precision_chars);
 418     //!< looks for optional precision characters.
 419   void seek_modifier(const char *&traverser, char *modifier_char);
 420     //!< looks for optional modifier characters.
 421   void get_type_character(const char *&traverser, va_list &args,
 422         astring &output_string, const char *flag_chars,
 423         const char *width_chars, const char *precision_chars,
 424         const char *modifier_chars);
 425     /*!< the required character in a format specifier is either grabbed here or
 426     the other characters are put into the ouput string without formatting.
 427     the "X"_char variables should have been previously gathered by the
 428     seek_"X" functions. */
 429
 430   public: byte_array &get_implementation(); private: // for test programs only....
 431 };
 432
 433 //////////////
 434
 435 //! a_sprintf is a specialization of astring that provides printf style support.
 436 /*! it makes it much easier to call the SPRINTF style constructor but is
 437 otherwise identical to an astring. */
 438
 439 class a_sprintf : public astring
 440 {
 441 public:
 442   a_sprintf();
 443   a_sprintf(const char *initial, ...);
 444   a_sprintf(const astring &s);
 445 };
 446
 447 //////////////
 448
 449 typedef bool string_comparator_function(const astring &a, const astring &b);
 450   //!< returns true if the strings "a" and "b" are considered equal.
 451   /*!< this provides a prototype for the equality operation, which allows the
 452   notion of equality to be redefined according to a particular function's
 453   implementation. */
 454
 455 bool astring_comparator(const astring &a, const astring &b);
 456   //!< implements a string comparator that just does simple astring ==.
 457
 458 //////////////
 459
 460 void attach(byte_array &packed_form, const char *to_attach);
 461   //!< Packs a character string "to_attach" into "packed_form".
 462 bool detach(byte_array &packed_form, astring &to_detach);
 463   //!< Unpacks a character string "to_attach" from "packed_form".
 464
 465 } //namespace.
 466
 467 #endif
 468