nucleus/library/structures/string_array.h

   1 #ifndef STRING_ARRAY_CLASS
   2 #define STRING_ARRAY_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : string_array                                                      *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *******************************************************************************
  10 * Copyright (c) 1993-$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 "object_packers.h"
  19
  20 #include <basis/astring.h>
  21 #include <basis/byte_array.h>
  22 #include <basis/functions.h>
  23
  24 namespace structures {
  25
  26 //! An array of strings with some additional helpful methods.
  27
  28 class string_array
  29 : public basis::array<basis::astring>,
  30   public virtual basis::packable,
  31   public virtual basis::equalizable
  32 {
  33 public:
  34   string_array(int number = 0, const basis::astring *initial_contents = NULL_POINTER)
  35           : basis::array<basis::astring>(number, initial_contents,
  36                 EXPONE | FLUSH_INVISIBLE) {}
  37     //!< Constructs an array of "number" strings.
  38     /*!< creates a list of strings based on an initial "number" of entries and
  39     some "initial_contents", which should be a regular C array of astrings
  40     with at least as many entries as "number". */
  41
  42   //! a constructor that operates on an array of char pointers.
  43   /*! be very careful with the array to ensure that the right number of
  44   elements is provided. */
  45   string_array(int number, const char *initial_contents[])
  46       : basis::array<basis::astring>(number, NULL_POINTER, EXPONE | FLUSH_INVISIBLE) {
  47     for (int i = 0; i < number; i++) {
  48       put(i, basis::astring(initial_contents[i]));
  49     }
  50   }
  51
  52   string_array(const basis::array<basis::astring> &to_copy)
  53       : basis::array<basis::astring>(to_copy) {}
  54     //!< copy constructor that takes a templated array of astring.
  55
  56   DEFINE_CLASS_NAME("string_array");
  57
  58   //! Prints out a formatted view of the contained strings and returns it.
  59   basis::astring text_format(const basis::astring &separator = ",",
  60           const basis::astring &delimiter = "\"") const {
  61     basis::astring to_return;
  62     for (int i = 0; i < length(); i++) {
  63       to_return += delimiter;
  64       to_return += get(i);
  65       to_return += delimiter;
  66       if (i < last())
  67         to_return += separator;
  68     }
  69     return to_return;
  70   }
  71
  72   basis::astring text_form() const { return text_format(); }
  73     //!< A synonym for the text_format() method.
  74
  75 //hmmm: extract as re-usable equality operation.
  76
  77   //! Compares this string array for equality with "to_compare".
  78   bool equal_to(const equalizable &to_compare) const {
  79     const string_array *cast = cast_or_throw(to_compare, *this);
  80     if (length() != cast->length())
  81       return false;
  82     for (int i = 0; i < length(); i++)
  83       if (cast->get(i) != get(i))
  84         return false;
  85     return true;
  86   }
  87
  88   //! locates string specified and returns its index, or negative if missing.
  89   int find(const basis::astring &to_find) const {
  90     for (int i = 0; i < length(); i++) {
  91       if (to_find.equal_to(get(i))) return i;
  92     }
  93     return basis::common::NOT_FOUND;
  94   }
  95
  96   //! Returns true if all of the elements in this are the same in "second".
  97   /*! The array "second" can have more elements, but must have all of the
  98   items listed in this string array. */
  99   bool prefix_compare(const string_array &second) const {
 100     if (second.length() < length()) return false;
 101     if (!length()) return false;
 102     for (int i = 0; i < length(); i++)
 103       if ((*this)[i] != second[i]) return false;
 104     return true;
 105   }
 106
 107   //! Packs this string array into the "packed_form" byte array.
 108   virtual void pack(basis::byte_array &packed_form) const
 109       { pack_array(packed_form, *this); }
 110
 111   //! Unpacks a string array from the "packed_form" byte array.
 112   virtual bool unpack(basis::byte_array &packed_form)
 113       { return unpack_array(packed_form, *this); }
 114
 115   //! Returns the number of bytes this string array would consume if packed.
 116   virtual int packed_size() const {
 117     int to_return = sizeof(int) * 2;  // length packed in, using obscure.
 118     for (int i = 0; i < length(); i++)
 119       to_return += get(i).length() + 1;
 120     return to_return;
 121   }
 122 };
 123
 124 } //namespace.
 125
 126 #endif
 127