arrayObject.h

Engine/source/console/arrayObject.h

More...

Classes:

class

A data structure holding indexed sequences of key/value pairs for script use.

Detailed Description

  1
  2//-----------------------------------------------------------------------------
  3// Copyright (c) 2012 GarageGames, LLC
  4//
  5// Permission is hereby granted, free of charge, to any person obtaining a copy
  6// of this software and associated documentation files (the "Software"), to
  7// deal in the Software without restriction, including without limitation the
  8// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  9// sell copies of the Software, and to permit persons to whom the Software is
 10// furnished to do so, subject to the following conditions:
 11//
 12// The above copyright notice and this permission notice shall be included in
 13// all copies or substantial portions of the Software.
 14//
 15// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 16// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 17// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 18// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 19// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 20// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 21// IN THE SOFTWARE.
 22//-----------------------------------------------------------------------------
 23
 24#ifndef _ARRAYOBJECT_H_
 25#define _ARRAYOBJECT_H_
 26
 27#ifndef _SIMBASE_H_
 28#include "console/simBase.h"
 29#endif
 30
 31// This class is based on original code by community
 32// member Daniel Neilsen:
 33//
 34// http://www.garagegames.com/community/resources/view/4711
 35
 36
 37/// A data structure holding indexed sequences of key/value pairs for script use.
 38class ArrayObject : public SimObject
 39{
 40   typedef SimObject Parent;
 41
 42protected:
 43
 44   struct Element
 45   {
 46      String key;
 47      String value;
 48      Element() { }
 49      Element( const String& _key, const String& _value ) : key(_key), value(_value) { }
 50   };
 51
 52   bool mCaseSensitive;
 53   S32 mCurrentIndex;
 54   
 55   /// The array of key/value pairs.
 56   Vector< Element> mArray;
 57   
 58   /// @name Sorting
 59   /// @{
 60
 61   static bool smDecreasing;
 62   static bool smCaseSensitive;
 63   static const char* smCompareFunction;
 64
 65   static S32 QSORT_CALLBACK _valueCompare( const void *a, const void *b );
 66   static S32 QSORT_CALLBACK _valueNumCompare( const void *a, const void *b );
 67   static S32 QSORT_CALLBACK _keyCompare( const void *a, const void *b );
 68   static S32 QSORT_CALLBACK _keyNumCompare( const void *a, const void *b );
 69   static S32 QSORT_CALLBACK _keyFunctionCompare( const void* a, const void* b );
 70   static S32 QSORT_CALLBACK _valueFunctionCompare( const void* a, const void* b );
 71   
 72   /// @}
 73
 74   static bool _addKeyFromField( void *object, const char *index, const char *data );
 75
 76public:
 77  
 78   ArrayObject();
 79
 80   /// @name Data Query 
 81   /// @{
 82   
 83   /// Returns true if string handling by the array is case-sensitive.
 84   bool isCaseSensitive() const { return mCaseSensitive; }
 85
 86   bool isEqual( const String &valA, const String &valB ) const
 87   {
 88      return valA.equal( valB, isCaseSensitive() ? String::Case : String::NoCase );
 89   }
 90
 91   /// Searches the array for the first matching value from the 
 92   /// current array position.  It will return -1 if no matching
 93   /// index is found.
 94   S32 getIndexFromValue( const String &value ) const;
 95
 96   /// Searches the array for the first matching key from the current
 97   /// array position.  It will return -1 if no matching index found.
 98   S32 getIndexFromKey( const String &key ) const;
 99   
100   /// Returns the key for a given index.
101   /// Will return a null value for an invalid index
102   const String& getKeyFromIndex( S32 index ) const;
103
104   /// Returns the value for a given index.
105   /// Will return a null value for an invalid index
106   const String&  getValueFromIndex( S32 index ) const;
107   
108   ///
109   S32 getIndexFromKeyValue( const String &key, const String &value ) const;
110
111   /// Counts the number of elements in the array
112   S32 count() const { return mArray.size(); }
113
114   /// Counts the number of instances of a particular value in the array
115   S32 countValue( const String &value ) const;
116
117   /// Counts the number of instances of a particular key in the array
118   S32 countKey( const String &key ) const;
119
120   /// @}
121
122   /// @name Data Alteration
123   /// @{
124
125   /// Adds a new array item to the end of the array
126   void push_back( const String &key, const String &value );
127
128   /// Adds a new array item to the front of the array
129   void push_front( const String &key, const String &value );
130
131   /// Adds a new array item to a particular index of the array
132   void insert( const String &key, const String &value, S32 index );
133
134   /// Removes an array item from the end of the array
135   void pop_back();
136
137   /// Removes an array item from the end of the array
138   void pop_front();
139
140   /// Removes an array item from a particular index of the array
141   void erase( S32 index );
142
143   /// Clears an array
144   void empty();
145
146   /// Moves a key and value from one index location to another.
147   void moveIndex( S32 prev, S32 index );
148
149   /// @}
150
151   /// @name Complex Data Alteration
152   /// @{
153
154   /// Removes any duplicate values from the array
155   /// (keeps the first instance only)
156   void uniqueValue();
157
158   /// Removes any duplicate keys from the array
159   /// (keeps the first instance only)
160   void uniqueKey();
161
162   /// Makes this array an exact duplicate of another array
163   void duplicate( ArrayObject *obj );
164
165   /// Crops the keys that exists in the target array from our current array
166   void crop( ArrayObject *obj );
167
168   /// Appends the target array to our current array
169   void append( ArrayObject *obj );
170
171   /// Sets the key at the given index
172   void setKey( const String &key, S32 index );
173
174   /// Sets the key at the given index
175   void setValue( const String &value, S32 index );
176
177   /// This sorts the array.
178   /// @param valtest  Determines whether sorting by value or key.
179   /// @param asc      Determines if sorting ascending or descending.
180   /// @param numeric  Determines if sorting alpha or numeric search.
181   void sort( bool valtest, bool asc, bool numeric );
182   
183   /// This sorts the array using a script callback.
184   /// @param valtest  Determines whether sorting by value or key.
185   /// @param asc      Determines if sorting ascending or descending.
186   /// @param callbackFunctionName Name of the script function.
187   void sort( bool valtest, bool asc, const char* callbackFunctionName );
188
189   /// @}
190
191   /// @name Pointer Manipulation
192   /// @{
193
194   /// Moves pointer to arrays first position
195   S32 moveFirst();
196
197   /// Moves pointer to arrays last position
198   S32 moveLast();
199
200   /// Moves pointer to arrays next position
201   /// If last position it returns -1 and no move occurs;
202   S32 moveNext();
203
204   /// Moves pointer to arrays prev position
205   /// If first position it returns -1 and no move occurs;
206   S32 movePrev();
207
208   /// Returns current pointer index.
209   S32 getCurrent() const { return mCurrentIndex; }
210
211   ///
212   void setCurrent( S32 idx );
213
214   /// @}
215
216
217   /// @name Data Listing
218   /// @{
219
220   /// Echos the content of the array to the console.
221   void echo();
222
223   /// @}
224
225   // SimObject
226   DECLARE_CONOBJECT( ArrayObject );
227   DECLARE_CATEGORY( "Core" );
228   DECLARE_DESCRIPTION( "An object storing an indexed sequence of key/value pairs." );
229   
230   static void initPersistFields();
231};
232
233#endif // _ARRAYOBJECT_H_
234