 | PixelLight 0.9.11-R1 Copyright (C) 2002-2012 by The PixelLight Team Last modified Thu Feb 23 2012 14:09:01 |  | The content of this PixelLight
document is published under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported |
|
PixelLightAPI
.
|
00001 /*********************************************************\ 00002 * File: StringBuffer.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_STRINGBUFFER_H__ 00024 #define __PLCORE_STRINGBUFFER_H__ 00025 #pragma once 00026 00027 00028 //[-------------------------------------------------------] 00029 //[ Includes ] 00030 //[-------------------------------------------------------] 00031 #include "PLCore/String/StringBufferManager.h" 00032 00033 00034 //[-------------------------------------------------------] 00035 //[ Namespace ] 00036 //[-------------------------------------------------------] 00037 namespace PLCore { 00038 00039 00040 //[-------------------------------------------------------] 00041 //[ Classes ] 00042 //[-------------------------------------------------------] 00043 /** 00044 * @brief 00045 * Abstract base class that contains the buffer for a string 00046 * 00047 * @note 00048 * - Implementation of the bridge design pattern, this class is the implementor of the 'String' abstraction 00049 */ 00050 class StringBuffer { 00051 00052 00053 //[-------------------------------------------------------] 00054 //[ Friends ] 00055 //[-------------------------------------------------------] 00056 friend class String; 00057 friend class StringBufferManager; 00058 00059 00060 //[-------------------------------------------------------] 00061 //[ Protected static data ] 00062 //[-------------------------------------------------------] 00063 protected: 00064 static PLCORE_API StringBufferManager Manager; /**< String buffer manager */ 00065 00066 00067 //[-------------------------------------------------------] 00068 //[ Protected functions ] 00069 //[-------------------------------------------------------] 00070 protected: 00071 /** 00072 * @brief 00073 * Constructor 00074 * 00075 * @param[in] nLength 00076 * Length of the string buffer (excluding the terminating zero) 00077 * @param[in] nMaxLength 00078 * Maximum available length of the string buffer (excluding the terminating zero) 00079 */ 00080 StringBuffer(uint32 nLength, uint32 nMaxLength, uint8 nType); 00081 00082 /** 00083 * @brief 00084 * Destructor 00085 */ 00086 virtual ~StringBuffer(); 00087 00088 /** 00089 * @brief 00090 * Returns the length of the string buffer (excluding the terminating zero, NEVER 0!) 00091 * 00092 * @return 00093 * Length of the string buffer, NEVER 0! 00094 */ 00095 PLCORE_API uint32 GetLength() const; 00096 00097 /** 00098 * @brief 00099 * Increases the reference count 00100 * 00101 * @return 00102 * Current reference count 00103 */ 00104 uint32 AddReference(); 00105 00106 /** 00107 * @brief 00108 * Decreases the reference count 00109 * 00110 * @return 00111 * Current reference count 00112 */ 00113 uint32 Release(); 00114 00115 /** 00116 * @brief 00117 * Gets the current reference count 00118 * 00119 * @return 00120 * Current reference count 00121 */ 00122 uint32 GetRefCount() const; 00123 00124 00125 //[-------------------------------------------------------] 00126 //[ Public virtual StringBuffer functions ] 00127 //[-------------------------------------------------------] 00128 public: 00129 /** 00130 * @brief 00131 * Returns the internal string format 00132 * 00133 * @return 00134 * Internal string format (type: "String::EFormat") 00135 */ 00136 virtual uint32 GetFormat() const = 0; 00137 00138 /** 00139 * @brief 00140 * Returns an ASCII string buffer version of the current string 00141 * 00142 * @return 00143 * ASCII string buffer version of the current string, NEVER a null pointer! (can be THIS) 00144 * 00145 * @remarks 00146 * This string buffer keeps a reference to the ASCII string buffer as long as 00147 * this string buffer content is NOT manipulated. (ASCII version becomes 'dirty') 00148 */ 00149 virtual StringBufferASCII *GetASCII() = 0; 00150 00151 /** 00152 * @brief 00153 * Returns an Unicode string buffer version of the current string 00154 * 00155 * @return 00156 * Unicode string buffer version of the current string, NEVER a null pointer! (can be THIS) 00157 * 00158 * @remarks 00159 * This string buffer keeps a reference to the Unicode string buffer as long as 00160 * this string buffer content is NOT manipulated. (Unicode version becomes 'dirty') 00161 */ 00162 virtual StringBufferUnicode *GetUnicode() = 0; 00163 00164 /** 00165 * @brief 00166 * Returns an UTF8 string buffer version of the current string 00167 * 00168 * @return 00169 * UTF8 string buffer version of the current string, NEVER a null pointer! (can be THIS) 00170 * 00171 * @remarks 00172 * This string buffer keeps a reference to the UTF8 string buffer as long as 00173 * this string buffer content is NOT manipulated. (UTF8 version becomes 'dirty') 00174 */ 00175 virtual StringBufferUTF8 *GetUTF8() = 0; 00176 00177 /** 00178 * @brief 00179 * Returns the number of bytes the string buffer is using (excluding the terminating zero, NEVER 0!) 00180 * 00181 * @return 00182 * The number of bytes the string buffer is using, NEVER 0! 00183 */ 00184 virtual uint32 GetNumOfBytes() const = 0; 00185 00186 /** 00187 * @brief 00188 * Returns a clone of this string buffer 00189 * 00190 * @return 00191 * Clone of this string buffer, a null pointer on terrible error 00192 * 00193 * @note 00194 * - The internal memory is also cloned 00195 * - The clone has no initial reference 00196 */ 00197 virtual StringBuffer *Clone() const = 0; 00198 00199 /** 00200 * @brief 00201 * Returns a duplicate of this string buffer 00202 * 00203 * @return 00204 * Duplicate of this string buffer, a null pointer on terrible error 00205 * 00206 * @remarks 00207 * Unlike Clone(), this function ONLY returns a duplicate if the string buffer 00208 * is shared between multiple strings, else a pointer to this string buffer is returned. 00209 */ 00210 virtual StringBuffer *Duplicate() = 0; 00211 00212 /** 00213 * @brief 00214 * Compares this string and the given one lexicographically 00215 * 00216 * @param[in] szString 00217 * String to compare with 00218 * @param[in] nLength 00219 * Length of the given string (excluding the terminating zero, if another format NEVER 0!) 00220 * 00221 * @return 00222 * 'true' if this string is less than the given one 00223 */ 00224 virtual bool IsLessThan(const char szString[], uint32 nLength) const = 0; 00225 virtual bool IsLessThan(const wchar_t szString[], uint32 nLength) const = 0; 00226 00227 /** 00228 * @brief 00229 * Compares this string and the given one lexicographically 00230 * 00231 * @param[in] szString 00232 * String to compare with 00233 * @param[in] nLength 00234 * Length of the given string (excluding the terminating zero, if another format NEVER 0!) 00235 * 00236 * @return 00237 * 'true' if this string is greater than the given one 00238 */ 00239 virtual bool IsGreaterThan(const char szString[], uint32 nLength) const = 0; 00240 virtual bool IsGreaterThan(const wchar_t szString[], uint32 nLength) const = 0; 00241 00242 /** 00243 * @brief 00244 * Compare function (case sensitive) 00245 * 00246 * @param[in] szString 00247 * String to compare with 00248 * @param[in] nLength 00249 * Length of the given string (excluding the terminating zero, NEVER 0!) 00250 * @param[in] nPos 00251 * Start position within this string (MUST be valid!) 00252 * @param[in] nCount 00253 * Number of characters to compare, if 0 compare all characters 00254 * 00255 * @return 00256 * 'true' if the two strings are identical, else 'false' 00257 */ 00258 virtual bool Compare(const char szString[], uint32 nLength, uint32 nPos, uint32 nCount) const = 0; 00259 virtual bool Compare(const wchar_t szString[], uint32 nLength, uint32 nPos, uint32 nCount) const = 0; 00260 00261 /** 00262 * @brief 00263 * Compare function (case insensitive) 00264 * 00265 * @param[in] szString 00266 * String to compare with 00267 * @param[in] nLength 00268 * Length of the given string (excluding the terminating zero, NEVER 0!) 00269 * @param[in] nPos 00270 * Start position within this string (MUST be valid!) 00271 * @param[in] nCount 00272 * Number of characters to compare, if 0 compare all characters 00273 * 00274 * @return 00275 * 'true' if the two strings are identical, else 'false' 00276 */ 00277 virtual bool CompareNoCase(const char szString[], uint32 nLength, uint32 nPos, uint32 nCount) const = 0; 00278 virtual bool CompareNoCase(const wchar_t szString[], uint32 nLength, uint32 nPos, uint32 nCount) const = 0; 00279 00280 /** 00281 * @brief 00282 * Determines whether the string is alphabetic or not 00283 * 00284 * @return 00285 * 'true' if the string is alphabetic (or empty) 00286 * 00287 * @note 00288 * - Examples: 'abc' is alphabetic while 'abc12' or 'ab-c' are not 00289 */ 00290 virtual bool IsAlphabetic() const = 0; 00291 00292 /** 00293 * @brief 00294 * Determines whether the string is alpha-numeric or not 00295 * 00296 * @return 00297 * 'true' if the string is alpha-numeric (or empty) 00298 * 00299 * @note 00300 * - Examples: 'abc', '12' or 'abc12' are alpha-numeric while 'abc-12' is not 00301 */ 00302 virtual bool IsAlphaNumeric() const = 0; 00303 00304 /** 00305 * @brief 00306 * Determines whether the string is numeric 00307 * 00308 * @return 00309 * 'true' if the string is numeric (or empty) 00310 * 00311 * @note 00312 * - Examples: '5' or '0' are numeric, 00313 * while '5.1', '.', 'AD', '3D', '5,5', '5.2.8' are not 00314 */ 00315 virtual bool IsNumeric() const = 0; 00316 00317 /** 00318 * @brief 00319 * Checks whether the given string is a substring of this string or not 00320 * 00321 * @param[in] szString 00322 * String to check 00323 * @param[in] nLength 00324 * Length of the given string (excluding the terminating zero, if another format NEVER 0!) 00325 * 00326 * @return 00327 * 'true', if the given string is a substring of this string, else 'false' 00328 */ 00329 virtual bool IsSubstring(const char szString[], uint32 nLength) const = 0; 00330 virtual bool IsSubstring(const wchar_t szString[], uint32 nLength) const = 0; 00331 00332 /** 00333 * @brief 00334 * Returns the index of the substring if contained in this string 00335 * 00336 * @param[in] szString 00337 * String to check 00338 * @param[in] nPos 00339 * Start position within this string (MUST be valid!) 00340 * @param[in] nLength 00341 * Length of the given string (excluding the terminating zero, if another format NEVER 0!) 00342 * 00343 * @return 00344 * Index of the substring if found within this string, < 0 on error 00345 */ 00346 virtual int IndexOf(const char szString[], uint32 nPos, uint32 nLength) const = 0; 00347 virtual int IndexOf(const wchar_t szString[], uint32 nPos, uint32 nLength) const = 0; 00348 00349 /** 00350 * @brief 00351 * Searches from backwards for the index of the substring within this string 00352 * 00353 * @param[in] szString 00354 * String to check 00355 * @param[in] nPos 00356 * Start position within this string (MUST be valid!) 00357 * @param[in] nLength 00358 * Length of the given string (excluding the terminating zero, NEVER 0!) 00359 * 00360 * @return 00361 * Index of the substring if found within this string, < 0 on error 00362 */ 00363 virtual int LastIndexOf(const char szString[], int nPos, uint32 nLength) const = 0; 00364 virtual int LastIndexOf(const wchar_t szString[], int nPos, uint32 nLength) const = 0; 00365 00366 /** 00367 * @brief 00368 * Get a substring from the string 00369 * 00370 * @param[in] nPos 00371 * Start position (MUST be valid!) 00372 * @param[in] nCount 00373 * Number of characters to copy (MUST be valid!) 00374 * 00375 * @return 00376 * The substring (without any initial reference) 00377 */ 00378 virtual StringBuffer *GetSubstring(uint32 nPos, uint32 nCount) const = 0; 00379 00380 /** 00381 * @brief 00382 * Change all characters to lower case 00383 * 00384 * @return 00385 * This string buffer if nothing was changed, else new string buffer (without any initial reference) 00386 */ 00387 virtual StringBuffer *ToLower() = 0; 00388 00389 /** 00390 * @brief 00391 * Change all characters to upper case 00392 * 00393 * @return 00394 * This string buffer if nothing was changed, else new string buffer (without any initial reference) 00395 */ 00396 virtual StringBuffer *ToUpper() = 0; 00397 00398 /** 00399 * @brief 00400 * Delete a substring 00401 * 00402 * @param[in] nPos 00403 * Start position of deletion (MUST be valid!) 00404 * @param[in] nCount 00405 * Number of characters to delete (MUST be valid!) 00406 * 00407 * @return 00408 * The new string buffer (without any initial reference) 00409 */ 00410 virtual StringBuffer *Delete(uint32 nPos, uint32 nCount) = 0; 00411 00412 /** 00413 * @brief 00414 * Appends a string at the end of the current string 00415 * 00416 * @param[in] szString 00417 * String to insert (NEVER empty!) 00418 * @param[in] nCount 00419 * Number of characters to add (MUST be valid!) 00420 * 00421 * @return 00422 * The new string buffer (without any initial reference) 00423 */ 00424 virtual StringBuffer *Append(const char szString[], uint32 nCount) = 0; 00425 virtual StringBuffer *Append(const wchar_t szString[], uint32 nCount) = 0; 00426 00427 /** 00428 * @brief 00429 * Insert a string at a given location 00430 * 00431 * @param[in] szString 00432 * String to insert (NEVER empty!) 00433 * @param[in] nPos 00434 * Position at which to insert the string (MUST be valid!) 00435 * @param[in] nCount 00436 * Number of characters to add (MUST be valid!) 00437 * 00438 * @return 00439 * The new string buffer (without any initial reference) 00440 * 00441 * @note 00442 * - Due to the possibility to insert the new string at every position, 00443 * the implementation is more complex as the one of "Append()", so, 00444 * whenever possible use "Append()" for better performance! 00445 */ 00446 virtual StringBuffer *Insert(const char szString[], uint32 nPos, uint32 nCount) = 0; 00447 virtual StringBuffer *Insert(const wchar_t szString[], uint32 nPos, uint32 nCount) = 0; 00448 00449 /** 00450 * @brief 00451 * Replaces all occurrences of a character by another character 00452 * 00453 * @param[in] nOld 00454 * Character to be replaced 00455 * @param[in] nNew 00456 * Character to replace with (nNew != nOld!!) 00457 * @param[out] nReplaced 00458 * Receives the number of replaced characters (0 if new = old, MUST be set!) 00459 * 00460 * @return 00461 * This string buffer if nothing was changed, else new string buffer (without any initial reference) 00462 */ 00463 virtual StringBuffer *Replace(char nOld, char nNew, uint32 &nReplaced) = 0; 00464 virtual StringBuffer *Replace(wchar_t nOld, wchar_t nNew, uint32 &nReplaced) = 0; 00465 00466 /** 00467 * @brief 00468 * Replaces all occurrences of a substring by another string 00469 * 00470 * @param[in] szOld 00471 * Substring to be replaced (NEVER empty!) 00472 * @param[in] nOldLength 00473 * Length of the old substring (MUST be valid!) 00474 * @param[in] szNew 00475 * String to replace with (szNew != szOld, can be empty!) 00476 * @param[in] nNewLength 00477 * Length of the new substring (MUST be valid but can be 0!) 00478 * @param[out] nReplaced 00479 * Receives the number of replaced characters (0 if new = old, MUST be set!) 00480 * 00481 * @return 00482 * This string buffer if nothing was changed, else new string buffer (without any initial reference) 00483 */ 00484 virtual StringBuffer *Replace(const char szOld[], uint32 nOldLength, const char szNew[], uint32 nNewLength, uint32 &nReplaced) = 0; 00485 virtual StringBuffer *Replace(const wchar_t szOld[], uint32 nOldLength, const wchar_t szNew[], uint32 nNewLength, uint32 &nReplaced) = 0; 00486 00487 /** 00488 * @brief 00489 * Sets a character at the given index 00490 * 00491 * @param[in] nIndex 00492 * Character index (MUST be valid!) 00493 * @param[in] nCharacter 00494 * Character to set at the given index 00495 * 00496 * @return 00497 * This string buffer if nothing was changed, else new string buffer (without any initial reference) 00498 */ 00499 virtual StringBuffer *SetCharacter(uint32 nIndex, char nCharacter) = 0; 00500 virtual StringBuffer *SetCharacter(uint32 nIndex, wchar_t nCharacter) = 0; 00501 00502 /** 00503 * @brief 00504 * Removes all whitespace (tabs and spaces) at the beginning of the string 00505 * 00506 * @return 00507 * This string buffer if nothing was changed, else new string buffer, (without any initial reference) 00508 * a null pointer if the string is now empty 00509 */ 00510 virtual StringBuffer *TrimLeading() = 0; 00511 00512 /** 00513 * @brief 00514 * Removes all whitespace (tabs and spaces) at the end of the string 00515 * 00516 * @return 00517 * This string buffer if nothing was changed, else new string buffer, (without any initial reference) 00518 * a null pointer if the string is now empty 00519 */ 00520 virtual StringBuffer *TrimTrailing() = 0; 00521 00522 /** 00523 * @brief 00524 * Removes line endings ("\r" or "\n") at the end of the string 00525 * 00526 * @return 00527 * This string buffer if nothing was changed, else new string buffer, (without any initial reference) 00528 * a null pointer if the string is now empty 00529 */ 00530 virtual StringBuffer *RemoveLineEndings() = 0; 00531 00532 00533 //[-------------------------------------------------------] 00534 //[ Protected data ] 00535 //[-------------------------------------------------------] 00536 protected: 00537 uint32 m_nRefCount; /**< Reference count - the "RefCount"-template isn't used because the string buffer manager requires some "special" access to this reference counter */ 00538 uint32 m_nLength; /**< Length of the string (excluding the terminating zero, NEVER 0!) */ 00539 uint32 m_nMaxLength; /**< Maximum available length of the string (excluding the terminating zero, NEVER 0!) */ 00540 uint8 m_nType; /**< String buffer type for variable inspection in debug mode */ 00541 00542 00543 }; 00544 00545 00546 //[-------------------------------------------------------] 00547 //[ Namespace ] 00548 //[-------------------------------------------------------] 00549 } 00550 00551 00552 //[-------------------------------------------------------] 00553 //[ Includes ] 00554 //[-------------------------------------------------------] 00555 // Include the string buffer implementation headers if we are in debug mode so we can inspect the string in a quite comfortable way 00556 #include "PLCore/String/StringBufferUTF8.h" 00557 #include "PLCore/String/StringBufferASCII.h" 00558 #include "PLCore/String/StringBufferUnicode.h" 00559 00560 00561 #endif // __PLCORE_STRINGBUFFER_H__
|