 | PixelLight 0.9.11-R1 Copyright (C) 2002-2012 by The PixelLight Team Last modified Thu Feb 23 2012 14:08:52 |  | The content of this PixelLight
document is published under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported |
|
PixelLightAPI
.
|
00001 /*********************************************************\ 00002 * File: Container.h * 00003 * 00004 * Copyright (C) 2002-2012 The PixelLight Team (http://www.pixellight.org/) 00005 * 00006 * This file is part of PixelLight. 00007 * 00008 * PixelLight is free software: you can redistribute it and/or modify 00009 * it under the terms of the GNU Lesser General Public License as published by 00010 * the Free Software Foundation, either version 3 of the License, or 00011 * (at your option) any later version. 00012 * 00013 * PixelLight is distributed in the hope that it will be useful, 00014 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00016 * GNU Lesser General Public License for more details. 00017 * 00018 * You should have received a copy of the GNU Lesser General Public License 00019 * along with PixelLight. If not, see <http://www.gnu.org/licenses/>. 00020 \*********************************************************/ 00021 00022 00023 #ifndef __PLCORE_CONTAINER_CONTAINER_H__ 00024 #define __PLCORE_CONTAINER_CONTAINER_H__ 00025 #pragma once 00026 00027 00028 //[-------------------------------------------------------] 00029 //[ Includes ] 00030 //[-------------------------------------------------------] 00031 #include "PLCore/Container/Iterable.h" 00032 00033 00034 //[-------------------------------------------------------] 00035 //[ Namespace ] 00036 //[-------------------------------------------------------] 00037 namespace PLCore { 00038 00039 00040 //[-------------------------------------------------------] 00041 //[ Classes ] 00042 //[-------------------------------------------------------] 00043 /** 00044 * @brief 00045 * Abstract container class 00046 * 00047 * @note 00048 * - A container can contain duplicates 00049 */ 00050 template <class ValueType> 00051 class Container : public Iterable<ValueType> { 00052 00053 00054 //[-------------------------------------------------------] 00055 //[ Public virtual Container functions ] 00056 //[-------------------------------------------------------] 00057 public: 00058 /** 00059 * @brief 00060 * Checks whether the container is complete empty 00061 * 00062 * @return 00063 * 'true' if the container is empty, else 'false' 00064 */ 00065 virtual bool IsEmpty() const = 0; 00066 00067 /** 00068 * @brief 00069 * Returns the number of elements 00070 * 00071 * @return 00072 * Number of container elements 00073 */ 00074 virtual uint32 GetNumOfElements() const = 0; 00075 00076 /** 00077 * @brief 00078 * Returns the size of a single container element (in bytes) 00079 * 00080 * @return 00081 * Size of a single container element (in bytes) 00082 */ 00083 virtual uint32 GetElementSize() const = 0; 00084 00085 /** 00086 * @brief 00087 * Returns the total size of all container elements (in bytes) 00088 * 00089 * @return 00090 * Total size of all container elements (in bytes) 00091 * 00092 * @remarks 00093 * You can NOT assume that GetElementSize()*GetNumOfElements() = GetSize() is 00094 * always true. For instance the Bitset implementation will store the bits tightly packed 00095 * and therefore in this case GetElementSize()*GetNumOfElements() != GetSize(). 00096 * GetSize() will only give you a hind how many bytes are currently required to store 00097 * all elements WITHOUT further implementation dependent things like pointers from one 00098 * to the next element. 00099 */ 00100 virtual uint32 GetSize() const = 0; 00101 00102 /** 00103 * @brief 00104 * Clears the whole container 00105 */ 00106 virtual void Clear() = 0; 00107 00108 /** 00109 * @brief 00110 * Returns whether the given element is within the container or not 00111 * 00112 * @param[in] Element 00113 * Element to check 00114 * 00115 * @return 00116 * 'true' if the element is within the container, else 'false' 00117 */ 00118 virtual bool IsElement(const ValueType &Element) const = 0; 00119 00120 /** 00121 * @brief 00122 * Returns the index of an element (first appearance) 00123 * 00124 * @param[in] Element 00125 * Element to get the index from 00126 * 00127 * @return 00128 * Index of the given element, < 0 if it's not in the container 00129 */ 00130 virtual int GetIndex(const ValueType &Element) const = 0; 00131 00132 /** 00133 * @brief 00134 * Returns an element 00135 * 00136 * @param[in] nIndex 00137 * Index of the element to return 00138 * 00139 * @return 00140 * Reference to the element at the given index, reference to the 'Null'-object on error 00141 */ 00142 virtual ValueType &Get(uint32 nIndex) const = 0; 00143 00144 /** 00145 * @brief 00146 * Returns an element 00147 * 00148 * @param[in] nIndex 00149 * Index of the element to return 00150 * 00151 * @return 00152 * Reference to the element at the given index, reference to the 'Null'-object on error 00153 */ 00154 virtual ValueType &operator [](uint32 nIndex) const = 0; 00155 00156 /** 00157 * @brief 00158 * Replaces an element (first appearance) through another element 00159 * 00160 * @param[in] Element1 00161 * Element to replace 00162 * @param[in] Element2 00163 * The element which should replace the old one 00164 * 00165 * @return 00166 * 'true' if all went fine, else 'false' (maybe 'Element1' is not within the container?) 00167 */ 00168 virtual bool Replace(const ValueType &Element1, const ValueType &Element2) = 0; 00169 00170 /** 00171 * @brief 00172 * Replaces an element at the given index through another element 00173 * 00174 * @param[in] nIndex 00175 * Index of the element to replace 00176 * @param[in] Element 00177 * The element which should replace the old one 00178 * 00179 * @return 00180 * 'true' if all went fine, else 'false' (maybe invalid index?) 00181 */ 00182 virtual bool ReplaceAtIndex(uint32 nIndex, const ValueType &Element) = 0; 00183 00184 /** 00185 * @brief 00186 * Appends an element to the container 00187 * 00188 * @return 00189 * Reference to the new element, reference to the 'Null'-object on error 00190 */ 00191 virtual ValueType &Add() = 0; 00192 00193 /** 00194 * @brief 00195 * Appends an element to the container 00196 * 00197 * @param[in] Element 00198 * Element to add 00199 * 00200 * @return 00201 * Reference to the new element, reference to the 'Null'-object on error 00202 */ 00203 virtual ValueType &Add(const ValueType &Element) = 0; 00204 00205 /** 00206 * @brief 00207 * Adds elements from a given C-array 00208 * 00209 * @param[in] pElements 00210 * Pointer to C-array with the elements to add, if a null pointer, nothing is done 00211 * @param[in] nCount 00212 * Number of elements to add, the given C-array MUST have at least nCount elements! 00213 * 00214 * @return 00215 * Number of added elements -> if the array is full and resizing is not allowed, this 00216 * number may differ from the given nCount 00217 */ 00218 virtual uint32 Add(const ValueType *pElements, uint32 nCount) = 0; 00219 00220 /** 00221 * @brief 00222 * Appends an element to the container 00223 * 00224 * @param[in] Element 00225 * Element to add 00226 * 00227 * @return 00228 * This container 00229 */ 00230 virtual Container<ValueType> &operator +=(const ValueType &Element) = 0; 00231 00232 /** 00233 * @brief 00234 * Appends an container to this container 00235 * 00236 * @param[in] lstContainer 00237 * Container to add 00238 * @param[in] nStart 00239 * Index the copy operation should start 00240 * @param[in] nCount 00241 * Number of elements to copy, if 0 copy all elements of lstContainer behind nStart 00242 * 00243 * @return 00244 * 'true' if all went fine, else 'false' 00245 */ 00246 virtual bool Add(const Container<ValueType> &lstContainer, uint32 nStart = 0, uint32 nCount = 0) = 0; 00247 00248 /** 00249 * @brief 00250 * Appends an container to this container 00251 * 00252 * @param[in] lstContainer 00253 * Container to add 00254 * 00255 * @return 00256 * This container 00257 */ 00258 virtual Container<ValueType> &operator +=(const Container<ValueType> &lstContainer) = 0; 00259 00260 /** 00261 * @brief 00262 * Appends an element to the container at the given index 00263 * 00264 * @param[in] nIndex 00265 * Index were to add the new element, if < 0 add at end, must be <= 'GetNumOfElements()' 00266 * 00267 * @return 00268 * Reference to the new element, reference to the 'Null'-object on error (maybe invalid index?) 00269 * 00270 * @note 00271 * - If the given index is equal to 'GetNumOfElements()' the element is appended at the end of the container 00272 * - The container is only enlarged by one element, this means that if 'GetNumOfElements()' is currently 0 00273 * and you give an index of 5 the container is NOT automatically resized to 6 elements! 00274 */ 00275 virtual ValueType &AddAtIndex(int nIndex) = 0; 00276 00277 /** 00278 * @brief 00279 * Appends an element to the container at the given index 00280 * 00281 * @param[in] Element 00282 * Element to add 00283 * @param[in] nIndex 00284 * Index were to add the new element, if < 0 add at end, must be <= 'GetNumOfElements()' 00285 * 00286 * @return 00287 * Reference to the new element, reference to the 'Null'-object on error (maybe invalid index?) 00288 * 00289 * @see 00290 * - AddAtIndex() above 00291 */ 00292 virtual ValueType &AddAtIndex(const ValueType &Element, int nIndex) = 0; 00293 00294 /** 00295 * @brief 00296 * Removes an element (first appearance) from the container 00297 * 00298 * @param[in] Element 00299 * Element to remove 00300 * 00301 * @return 00302 * 'true' if all went fine, else 'false' (maybe 'Element' is not within the container?) 00303 */ 00304 virtual bool Remove(const ValueType &Element) = 0; 00305 00306 /** 00307 * @brief 00308 * Removes the element at the given index from the container 00309 * 00310 * @param[in] nElement 00311 * Index of the element to remove 00312 * 00313 * @return 00314 * 'true' if all went fine, else 'false' (maybe invalid index?) 00315 */ 00316 virtual bool RemoveAtIndex(uint32 nElement) = 0; 00317 00318 /** 00319 * @brief 00320 * Removes an element from the container 00321 * 00322 * @param[in] Element 00323 * Element to remove 00324 * 00325 * @return 00326 * This container 00327 */ 00328 virtual Container<ValueType> &operator -=(const ValueType &Element) = 0; 00329 00330 /** 00331 * @brief 00332 * Removes the elements of an container from this container 00333 * 00334 * @param[in] lstContainer 00335 * Container to remove the elements from this container 00336 * @param[in] nStart 00337 * Index the remove operation should start 00338 * @param[in] nCount 00339 * Number of elements to remove, if 0 remove all elements of lstContainer behind nStart 00340 * 00341 * @return 00342 * 'true' if all went fine, else 'false' 00343 */ 00344 virtual bool Remove(const Container<ValueType> &lstContainer, uint32 nStart = 0, uint32 nCount = 0) = 0; 00345 00346 /** 00347 * @brief 00348 * Removes the elements of an container from this container 00349 * 00350 * @param[in] lstContainer 00351 * Container to remove the elements from this container 00352 * 00353 * @return 00354 * This container 00355 */ 00356 virtual Container<ValueType> &operator -=(const Container<ValueType> &lstContainer) = 0; 00357 00358 /** 00359 * @brief 00360 * Makes this container to a copy of another container 00361 * 00362 * @param[in] lstContainer 00363 * Container to copy from 00364 * @param[in] nStart 00365 * Index the copy operation should start 00366 * @param[in] nCount 00367 * Number of elements to copy, if 0 copy all elements of lstContainer behind nStart 00368 * 00369 * @return 00370 * 'true' if all went fine, else 'false' 00371 */ 00372 virtual bool Copy(const Container<ValueType> &lstContainer, uint32 nStart = 0, uint32 nCount = 0) = 0; 00373 00374 /** 00375 * @brief 00376 * Makes this container to a copy of another container 00377 * 00378 * @param[in] lstContainer 00379 * Container to copy from 00380 * 00381 * @return 00382 * Reference to this instance 00383 */ 00384 virtual Container<ValueType> &operator =(const Container<ValueType> &lstContainer) = 0; 00385 00386 /** 00387 * @brief 00388 * Compares two containers 00389 * 00390 * @param[in] lstContainer 00391 * Container to compare with 00392 * @param[in] nStart 00393 * Index the compare operation should start 00394 * @param[in] nCount 00395 * Number of elements to compare, if 0 compare all elements of lstContainer behind nStart 00396 * 00397 * @return 00398 * 'true' if both containers are equal, else 'false' 00399 */ 00400 virtual bool Compare(const Container<ValueType> &lstContainer, uint32 nStart = 0, uint32 nCount = 0) const = 0; 00401 00402 /** 00403 * @brief 00404 * Compares two containers 00405 * 00406 * @param[in] lstContainer 00407 * Container to compare with 00408 * 00409 * @return 00410 * 'true' if both containers are equal, else 'false' 00411 */ 00412 virtual bool operator ==(const Container<ValueType> &lstContainer) const = 0; 00413 00414 /** 00415 * @brief 00416 * Compares two containers 00417 * 00418 * @param[in] lstContainer 00419 * Container to compare with 00420 * 00421 * @return 00422 * 'true' if both containers are not equal, else 'false' 00423 */ 00424 virtual bool operator !=(const Container<ValueType> &lstContainer) const = 0; 00425 00426 00427 }; 00428 00429 00430 //[-------------------------------------------------------] 00431 //[ Namespace ] 00432 //[-------------------------------------------------------] 00433 } // PLCore 00434 00435 00436 #endif // __PLCORE_CONTAINER_CONTAINER_H__
|