Merge branch 'release-2.140.101'
[feisty_meow.git] / 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