1 /*!**************************************************************************** 2 3 @file PVRTMap.h 4 @copyright Copyright (c) Imagination Technologies Limited. 5 @brief A simple and easy-to-use implementation of a map. 6 7 ******************************************************************************/ 8 #ifndef __PVRTMAP_H__ 9 #define __PVRTMAP_H__ 10 11 #include "PVRTArray.h" 12 13 /*!*************************************************************************** 14 @class CPVRTMap 15 @brief Expanding map template class. 16 @details A simple and easy-to-use implementation of a map. 17 *****************************************************************************/ 18 template <typename KeyType, typename DataType> 19 class CPVRTMap 20 { 21 public: 22 23 /*!*********************************************************************** 24 @brief Constructor for a CPVRTMap. 25 @return A new CPVRTMap. 26 *************************************************************************/ CPVRTMap()27 CPVRTMap() : m_Keys(), m_Data(), m_uiSize(0) 28 {} 29 30 /*!*********************************************************************** 31 @brief Destructor for a CPVRTMap. 32 *************************************************************************/ ~CPVRTMap()33 ~CPVRTMap() 34 { 35 //Clear the map, that's enough - the CPVRTArray members will tidy everything else up. 36 Clear(); 37 } 38 Reserve(const PVRTuint32 uiSize)39 EPVRTError Reserve(const PVRTuint32 uiSize) 40 { 41 //Sets the capacity of each member array to the requested size. The array used will only expand. 42 //Returns the most serious error from either method. 43 return PVRT_MAX(m_Keys.SetCapacity(uiSize),m_Data.SetCapacity(uiSize)); 44 } 45 46 /*!*********************************************************************** 47 @brief Returns the number of meaningful members in the map. 48 @return Number of meaningful members in the map. 49 *************************************************************************/ GetSize()50 PVRTuint32 GetSize() const 51 { 52 //Return the size. 53 return m_uiSize; 54 } 55 56 /*!*********************************************************************** 57 @brief Gets the position of a particular key/data within the map. 58 If the return value is exactly equal to the value of 59 GetSize() then the item has not been found. 60 @param[in] key Key type 61 @return The index value for a mapped item. 62 *************************************************************************/ GetIndexOf(const KeyType key)63 PVRTuint32 GetIndexOf(const KeyType key) const 64 { 65 //Loop through all the valid keys. 66 for (PVRTuint32 i=0; i<m_uiSize; ++i) 67 { 68 //Check if a key matches. 69 if (m_Keys[i]==key) 70 { 71 //If a matched key is found, return the position. 72 return i; 73 } 74 } 75 76 //If not found, return the number of meaningful members. 77 return m_uiSize; 78 } 79 80 /*!*********************************************************************** 81 @brief Returns a pointer to the Data at a particular index. 82 If the index supplied is not valid, NULL is returned 83 instead. Deletion of data at this pointer will lead 84 to undefined behaviour. 85 @param[in] uiIndex Index number 86 @return Data type at the specified position. 87 *************************************************************************/ GetDataAtIndex(const PVRTuint32 uiIndex)88 const DataType* GetDataAtIndex(const PVRTuint32 uiIndex) const 89 { 90 if (uiIndex>=m_uiSize) 91 return NULL; 92 93 return &(m_Data[uiIndex]); 94 } 95 96 /*!*********************************************************************** 97 @brief If a mapping already exists for 'key' then it will return 98 the associated data. If no mapping currently exists, a new 99 element is created in place. 100 @param[in] key Key type 101 @return Data that is mapped to 'key'. 102 *************************************************************************/ 103 DataType& operator[] (const KeyType key) 104 { 105 //Get the index of the key. 106 PVRTuint32 uiIndex = GetIndexOf(key); 107 108 //Check the index is valid 109 if (uiIndex != m_uiSize) 110 { 111 //Return mapped data if the index is valid. 112 return m_Data[uiIndex]; 113 } 114 else 115 { 116 //Append the key to the Keys array. 117 m_Keys.Append(key); 118 119 //Create a new DataType. 120 DataType sNewData; 121 122 //Append the new pointer to the Data array. 123 m_Data.Append(sNewData); 124 125 //Increment the size of meaningful data. 126 ++m_uiSize; 127 128 //Return the contents of pNewData. 129 return m_Data[m_Keys.GetSize()-1]; 130 } 131 } 132 133 /*!*********************************************************************** 134 @brief Removes an element from the map if it exists. 135 @param[in] key Key type 136 @return Returns PVR_FAIL if item doesn't exist. 137 Otherwise returns PVR_SUCCESS. 138 *************************************************************************/ Remove(const KeyType key)139 EPVRTError Remove(const KeyType key) 140 { 141 //Finds the index of the key. 142 PVRTuint32 uiIndex=GetIndexOf(key); 143 144 //If the key is invalid, fail. 145 if (uiIndex==m_uiSize) 146 { 147 //Return failure. 148 return PVR_FAIL; 149 } 150 151 //Decrement the size of the map to ignore the last element in each array. 152 m_uiSize--; 153 154 //Copy the last key over the deleted key. There are now two copies of one element, 155 //but the one at the end of the array is ignored. 156 m_Keys[uiIndex]=m_Keys[m_uiSize-1]; 157 158 //Copy the last data over the deleted data in the same way as the keys. 159 m_Data[uiIndex]=m_Data[m_uiSize-1]; 160 161 //Return success. 162 return PVR_SUCCESS; 163 } 164 165 /*!*********************************************************************** 166 @brief Clears the Map of all data values. 167 *************************************************************************/ Clear()168 void Clear() 169 { 170 //Set the size to 0. 171 m_uiSize=0; 172 m_Keys.Clear(); 173 m_Data.Clear(); 174 } 175 176 /*!*********************************************************************** 177 @brief Checks whether or not data exists for the specified key. 178 @param[in] key Key type 179 @return Whether data exists for the specified key or not. 180 *************************************************************************/ Exists(const KeyType key)181 bool Exists(const KeyType key) const 182 { 183 //Checks for a valid index for key, if not, returns false. 184 return (GetIndexOf(key) != m_uiSize); 185 } 186 187 private: 188 189 190 CPVRTArray<KeyType> m_Keys; /*!< Array of all the keys. Indices match m_Data. */ 191 192 CPVRTArray<DataType> m_Data; /*!< Array of pointers to all the allocated data. */ 193 194 PVRTuint32 m_uiSize; /*!< The number of meaningful members in the map. */ 195 }; 196 197 #endif // __PVRTMAP_H__ 198 199 /***************************************************************************** 200 End of file (PVRTMap.h) 201 *****************************************************************************/ 202 203