arrayObject.h
Engine/source/console/arrayObject.h
Classes:
class
A data structure holding indexed sequences of key/value pairs for script use.
class
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