 | 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: String.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_STRING_H__ 00024 #define __PLCORE_STRING_H__ 00025 #pragma once 00026 00027 00028 //[-------------------------------------------------------] 00029 //[ Includes ] 00030 //[-------------------------------------------------------] 00031 #include "PLCore/PLCore.h" 00032 00033 00034 //[-------------------------------------------------------] 00035 //[ Namespace ] 00036 //[-------------------------------------------------------] 00037 namespace PLCore { 00038 00039 00040 //[-------------------------------------------------------] 00041 //[ Forward declarations ] 00042 //[-------------------------------------------------------] 00043 class StringBuffer; 00044 00045 00046 //[-------------------------------------------------------] 00047 //[ Classes ] 00048 //[-------------------------------------------------------] 00049 /** 00050 * @brief 00051 * String class 00052 * 00053 * @remarks 00054 * Because strings are quite fundamental, there are several optimizations in place to make dealing 00055 * with strings as fast as possible. The string class uses a 'copy on change' technique - 00056 * therefore copying one string into another is quite performant because the internal string buffer 00057 * is shared as long as a string doesn't change. As result comparing strings 'can' also be very fast 00058 * and the internal string buffer can be ASCII OR Unicode in a quite flexible way. To 00059 * enhance the string performance, the internal string buffers are managed by a string buffer 00060 * manager to avoid to many memory allocations/deallocations. For an additional performance 00061 * improvement, memory is traded for speed, meaning that additional characters are allocated 00062 * within the internal string buffer manager for future use. This way, appending new characters 00063 * to a string is usually quite fast. 00064 * 00065 * As long as you don't save your source codes in an UTF8 format you can also use the ASCII 00066 * extension Ansi, meaning characters between 128-256. But with an UTF8 format, this may cause 00067 * serious problems and you should use Unicode instead ASCII for characters above 128 (using 00068 * codepage based ASCII is not recommended) to avoid encoding troubles! 00069 * 00070 * For best compatibility with other string techniques, this class is using pointers instead of 00071 * [] references, so a null pointer is a valid parameter. 00072 * 00073 * @verbatim 00074 * Usage example: 00075 * String sS; // Test string instance 00076 * sS = "Mini"; // Set string to 'Mini' as ASCII 00077 * sS += " Me"; // Concatenate 'Me' (ASCII) to string 00078 * const char *pS = sS.GetASCII(); // Get pointer to ASCII string content 00079 * const char *pS = sS; // Get pointer to ASCII string content (same as above) 00080 * sS = L"Mini"; // Set string to 'Mini' as Unicode 00081 * sS = L"\u65e5\u672c\u8a9e"; // Set string to 'nihon' (= Japanese) as Unicode 00082 * sS = String::FromUTF8("Mini"); // Set string to 'Mini' as UTF8 00083 * @endverbatim 00084 * 00085 * @note 00086 * - With 'length' we mean the 'number of characters' and not the 'number of bytes' 00087 * - Don't forget that wchar_t does not have the same number of bytes on every OS, so DO NOT use wchar_t for serialization, use UTF8 for that! 00088 * - PixelLight is using the compiler option "wchar_t is treated as built-in type", while other libraries like Qt are not - so you may want to 00089 * use UTF8 for string exchange between different libraries... 00090 * - If you care about best possible performance (even if nearly not measurable), use character string methods when dealing with characters - for 00091 * example, write "String sS = 'A';" instead of "String sS = "A";", this way, the string method already knows that you provided just a single 00092 * character and don't need to count characters internally 00093 * - Implementation of the bridge design pattern (with a pinch of the proxy design pattern for the copy-on-write/change), this class is the abstraction 00094 */ 00095 class String { 00096 00097 00098 //[-------------------------------------------------------] 00099 //[ Public definitions ] 00100 //[-------------------------------------------------------] 00101 public: 00102 /** 00103 * @brief 00104 * Internal string format 00105 */ 00106 enum EFormat { 00107 ASCII = 0, /**< ASCII, 1 byte per character (American Standard Code for Information Interchange, 0-128 defined, above undefined) */ 00108 Unicode = 1, /**< Unicode, (sometimes called 'multi-byte' or 'wide character') normally two bytes (UTF-16) on Microsoft Windows per character, four bytes long on UNIX systems (UTF-32) */ 00109 UTF8 = 2 /**< UTF8, only used internally */ 00110 }; 00111 00112 00113 //[-------------------------------------------------------] 00114 //[ Static functions ] 00115 //[-------------------------------------------------------] 00116 public: 00117 /** 00118 * @brief 00119 * Creates a new formatted string (like sprintf) 00120 * 00121 * @param[in] pszFormat 00122 * The format string ... -> The variable arguments (can be a null pointer) 00123 * 00124 * @return 00125 * New string 00126 * 00127 * @remarks 00128 * If possible, try to avoid to use this method because it's usually considered to be "slow" due to 00129 * it's internal complexity. Therefore, write something like 00130 * String sMyString = String("The number ") + 42 + " is fantastic!"; 00131 * instead of 00132 * String sMyString = String::Format("The number %d is fantastic!", 42); 00133 */ 00134 static PLCORE_API String Format(const char *pszFormat, ...); 00135 static PLCORE_API String Format(const wchar_t *pszFormat, ...); 00136 00137 /** 00138 * @brief 00139 * Sets the character string as UTF8 00140 * 00141 * @param[in] pszUTF8 00142 * Pointer to the character string as UTF8, can be a null pointer 00143 * @param[in] nLength 00144 * Length of the given string, (excluding the terminating zero) if negative, the length is 00145 * calculated automatically 00146 * @param[in] nNumOfBytes 00147 * Number of bytes of the string buffer (excluding the terminating zero, MUST be valid if not 0!) 00148 * 00149 * @return 00150 * New UTF8 string 00151 */ 00152 static PLCORE_API String FromUTF8(const char *pszUTF8, int nLength = -1, uint32 nNumOfBytes = 0); 00153 00154 00155 //[-------------------------------------------------------] 00156 //[ Public functions ] 00157 //[-------------------------------------------------------] 00158 public: 00159 /** 00160 * @brief 00161 * Default constructor 00162 */ 00163 inline String(); 00164 00165 /** 00166 * @brief 00167 * Character constructor 00168 * 00169 * @param[in] nValue 00170 * Single character to put into the string 00171 */ 00172 PLCORE_API String(char nValue); 00173 PLCORE_API String(wchar_t nValue); 00174 00175 /** 00176 * @brief 00177 * Constructor 00178 * 00179 * @param[in] pszString 00180 * String to save, can be a null pointer 00181 * @param[in] bCopy 00182 * Copy the given string or use this one directly? Do ONLY set bCopy to 'false' 00183 * if you are sure there can't go anything wrong - the string class will take over 00184 * control of the string buffer and also destroy it 00185 * @param[in] nLength 00186 * Length of the given string, (excluding the terminating zero) if negative, the length is 00187 * calculated automatically 00188 */ 00189 PLCORE_API String(const char *pszString, bool bCopy = true, int nLength = -1); 00190 PLCORE_API String(const wchar_t *pszString, bool bCopy = true, int nLength = -1); 00191 00192 /** 00193 * @brief 00194 * Copy constructor 00195 * 00196 * @param[in] sString 00197 * String 00198 */ 00199 PLCORE_API String(const String &sString); 00200 00201 /** 00202 * @brief 00203 * Number constructor 00204 * 00205 * @param[in] nValue 00206 * Number to put into the string 00207 */ 00208 inline String(bool bValue); 00209 PLCORE_API String(int nValue); 00210 inline String(int64 nValue); 00211 inline String(uint8 nValue); 00212 // inline String(uint16 nValue); // We can't do that because wchar_t may be defined the same way as uint16 00213 inline String(uint32 nValue); 00214 inline String(uint64 nValue); 00215 inline String(float fValue); 00216 inline String(double fValue); 00217 00218 /** 00219 * @brief 00220 * Pointer constructor 00221 * 00222 * @param[in] pValue 00223 * Pointer to put into the string 00224 */ 00225 inline String(void *pValue); 00226 00227 /** 00228 * @brief 00229 * Internal copy constructor 00230 * 00231 * @param[in] pStringBuffer 00232 * String buffer to use, can be a null pointer 00233 * 00234 * @note 00235 * - This constructor is ONLY used inside PLCore and therefore it's not exported 00236 * and usable from 'outside' 00237 */ 00238 String(StringBuffer *pStringBuffer); 00239 00240 /** 00241 * @brief 00242 * Destructor 00243 */ 00244 inline ~String(); 00245 00246 /** 00247 * @brief 00248 * Returns the length of the string 00249 * 00250 * @return 00251 * Length of the string (excluding the terminating zero) 00252 */ 00253 inline uint32 GetLength() const; 00254 00255 /** 00256 * @brief 00257 * Returns the internal string format 00258 * 00259 * @return 00260 * Internal string format 00261 */ 00262 inline EFormat GetFormat() const; 00263 00264 /** 00265 * @brief 00266 * Returns the number of bytes the string is using in a specified format (ASCII, Unicode, UTF8) 00267 * 00268 * @param[in] nFormat 00269 * The internal string format 00270 * 00271 * @return 00272 * The number of bytes the string is using in the specified format (excluding the terminating zero) 00273 */ 00274 PLCORE_API uint32 GetNumOfBytes(EFormat nFormat) const; 00275 00276 /** 00277 * @brief 00278 * Get a ASCII character of the string 00279 * 00280 * @param[in] nIndex 00281 * Position of the ASCII character to retrieve 00282 * 00283 * @return 00284 * ASCII character at the given position within the string, terminating zero (\0) on error 00285 */ 00286 inline char operator [](uint32 nIndex) const; 00287 00288 /** 00289 * @brief 00290 * Returns the character string as ASCII 00291 * 00292 * @return 00293 * Pointer to the character string as ASCII, never a null pointer 00294 * 00295 * @remarks 00296 * If the internal format of this string doesn't match the requested format, an internal temp 00297 * string of the requested format is created and backuped until this original string is manipulated. 00298 * Then, the internal backup get's dirty/invalid - so, do NEVER backup the returned pointer by self! 00299 * 00300 * @note 00301 * - Do NOT manipulate or even mess up the memory by writing outside the given buffer! 00302 */ 00303 inline const char *GetASCII() const; 00304 00305 /** 00306 * @brief 00307 * Returns the character string as ASCII 00308 * 00309 * @return 00310 * Pointer to the character string as ASCII, never a null pointer 00311 * 00312 * @see 00313 * - GetASCII() 00314 */ 00315 inline operator const char *() const; 00316 00317 /** 00318 * @brief 00319 * Returns the character string as Unicode 00320 * 00321 * @return 00322 * Pointer to the character string as Unicode, never a null pointer 00323 * 00324 * @see 00325 * - GetASCII() 00326 */ 00327 inline const wchar_t *GetUnicode() const; 00328 00329 /** 00330 * @brief 00331 * Returns the character string as Unicode 00332 * 00333 * @return 00334 * Pointer to the character string as Unicode, never a null pointer 00335 * 00336 * @see 00337 * - GetASCII() 00338 */ 00339 inline operator const wchar_t *() const; 00340 00341 /** 00342 * @brief 00343 * Copy operator 00344 * 00345 * @param[in] sString 00346 * String to copy 00347 * 00348 * @return 00349 * Reference to this string 00350 */ 00351 inline String &operator =(const String &sString); 00352 00353 /** 00354 * @brief 00355 * Copy operator 00356 * 00357 * @param[in] pszString 00358 * String to copy, can be a null pointer 00359 * 00360 * @return 00361 * Reference to this string 00362 */ 00363 PLCORE_API String &operator =(const char *pszString); 00364 PLCORE_API String &operator =(const wchar_t *pszString); 00365 00366 /** 00367 * @brief 00368 * Concatenate strings 00369 * 00370 * @param[in] sString 00371 * String to add 00372 * 00373 * @return 00374 * Reference to the new string 00375 */ 00376 PLCORE_API String operator +(const String &sString) const; 00377 00378 /** 00379 * @brief 00380 * Concatenate strings 00381 * 00382 * @param[in] pszString 00383 * String to add, can be a null pointer 00384 * 00385 * @return 00386 * Reference to the new string 00387 */ 00388 PLCORE_API String operator +(const char *pszString) const; 00389 PLCORE_API String operator +(const wchar_t *pszString) const; 00390 00391 /** 00392 * @brief 00393 * Concatenate strings 00394 * 00395 * @param[in] pszString 00396 * String to add, can be a null pointer 00397 * @param[in] sString 00398 * String to add 00399 * 00400 * @return 00401 * Reference to the new string 00402 */ 00403 PLCORE_API friend String operator +(const char *pszString, const String &sString); 00404 PLCORE_API friend String operator +(const wchar_t *pszString, const String &sString); 00405 00406 /** 00407 * @brief 00408 * Concatenate strings 00409 * 00410 * @param[in] sString 00411 * String to add 00412 * 00413 * @return 00414 * Reference to this string 00415 */ 00416 PLCORE_API String &operator +=(const String &sString); 00417 00418 /** 00419 * @brief 00420 * Concatenate strings 00421 * 00422 * @param[in] pszString 00423 * String to add, can be a null pointer 00424 * 00425 * @return 00426 * Reference to this string 00427 */ 00428 PLCORE_API String &operator +=(const char *pszString); 00429 PLCORE_API String &operator +=(const wchar_t *pszString); 00430 00431 /** 00432 * @brief 00433 * Compares this string and the given one lexicographically 00434 * 00435 * @param[in] sString 00436 * String to compare with 00437 * 00438 * @return 00439 * 'true' if this string is less than the given one 00440 */ 00441 PLCORE_API bool operator <(const String &sString) const; 00442 00443 /** 00444 * @brief 00445 * Compares this string and the given one lexicographically 00446 * 00447 * @param[in] pszString 00448 * String to compare with, can be a null pointer 00449 * 00450 * @return 00451 * 'true' if this string is less than the given one 00452 */ 00453 PLCORE_API bool operator <(const char *pszString) const; 00454 PLCORE_API bool operator <(const wchar_t *pszString) const; 00455 00456 /** 00457 * @brief 00458 * Compares this string and the given one lexicographically 00459 * 00460 * @param[in] sString 00461 * String to compare with 00462 * 00463 * @return 00464 * 'true' if this string is greater than the given one 00465 */ 00466 PLCORE_API bool operator >(const String &sString) const; 00467 00468 /** 00469 * @brief 00470 * Compares this string and the given one lexicographically 00471 * 00472 * @param[in] pszString 00473 * String to compare with, can be a null pointer 00474 * 00475 * @return 00476 * 'true' if this string is greater than the given one 00477 */ 00478 PLCORE_API bool operator >(const char *pszString) const; 00479 PLCORE_API bool operator >(const wchar_t *pszString) const; 00480 00481 /** 00482 * @brief 00483 * Compare operator (case sensitive) 00484 * 00485 * @param[in] sString 00486 * String to compare with 00487 * 00488 * @return 00489 * 'true' if the two strings are identical, else 'false' 00490 */ 00491 inline bool operator ==(const String &sString) const; 00492 00493 /** 00494 * @brief 00495 * Compare operator (case sensitive) 00496 * 00497 * @param[in] pszString 00498 * String to compare with, can be a null pointer 00499 * 00500 * @return 00501 * 'true' if the two strings are identical, else 'false' 00502 */ 00503 inline bool operator ==(const char *pszString) const; 00504 inline bool operator ==(const wchar_t *pszString) const; 00505 00506 /** 00507 * @brief 00508 * Compare operator (case sensitive) 00509 * 00510 * @param[in] sString 00511 * String to compare with 00512 * 00513 * @return 00514 * 'true' if the two strings are different, else 'false' 00515 */ 00516 inline bool operator !=(const String &sString) const; 00517 00518 /** 00519 * @brief 00520 * Compare operator (case sensitive) 00521 * 00522 * @param[in] pszString 00523 * String to compare with, can be a null pointer 00524 * 00525 * @return 00526 * 'true' if the two strings are different, else 'false' 00527 */ 00528 inline bool operator !=(const char *pszString) const; 00529 inline bool operator !=(const wchar_t *pszString) const; 00530 00531 /** 00532 * @brief 00533 * Compare function (case sensitive) 00534 * 00535 * @param[in] sString 00536 * String to compare with 00537 * @param[in] nPos 00538 * Start position within this string 00539 * @param[in] nCount 00540 * Number of characters to compare, if negative compare all characters, if 0 the result is "true" 00541 * 00542 * @return 00543 * 'true' if the two strings are identical, else 'false' 00544 */ 00545 PLCORE_API bool Compare(const String &sString, uint32 nPos = 0, int nCount = -1) const; 00546 00547 /** 00548 * @brief 00549 * Compare function (case sensitive) 00550 * 00551 * @param[in] pszString 00552 * String to compare with, can be a null pointer 00553 * @param[in] nPos 00554 * Start position within this string 00555 * @param[in] nCount 00556 * Number of characters to compare, if negative compare all characters, if 0 the result is "true" 00557 * 00558 * @return 00559 * 'true' if the two strings are identical, else 'false' 00560 */ 00561 PLCORE_API bool Compare(const char *pszString, uint32 nPos = 0, int nCount = -1) const; 00562 PLCORE_API bool Compare(const wchar_t *pszString, uint32 nPos = 0, int nCount = -1) const; 00563 00564 /** 00565 * @brief 00566 * Compare function (case insensitive) 00567 * 00568 * @param[in] sString 00569 * String to compare with 00570 * @param[in] nPos 00571 * Start position within this string 00572 * @param[in] nCount 00573 * Number of characters to compare, if negative compare all characters, if 0 the result is "true" 00574 * 00575 * @return 00576 * 'true' if the two strings are identical, else 'false' 00577 */ 00578 PLCORE_API bool CompareNoCase(const String &sString, uint32 nPos = 0, int nCount = -1) const; 00579 00580 /** 00581 * @brief 00582 * Compare function (case insensitive) 00583 * 00584 * @param[in] pszString 00585 * String to compare with, can be a null pointer 00586 * @param[in] nPos 00587 * Start position within this string 00588 * @param[in] nCount 00589 * Number of characters to compare, if negative compare all characters, if 0 the result is "true" 00590 * 00591 * @return 00592 * 'true' if the two strings are identical, else 'false' 00593 */ 00594 PLCORE_API bool CompareNoCase(const char *pszString, uint32 nPos = 0, int nCount = -1) const; 00595 PLCORE_API bool CompareNoCase(const wchar_t *pszString, uint32 nPos = 0, int nCount = -1) const; 00596 00597 /** 00598 * @brief 00599 * Determines whether the string is alphabetic or not 00600 * 00601 * @return 00602 * 'true' if the string is alphabetic, else 'false' (maybe the string is empty?) 00603 * 00604 * @note 00605 * - Examples: 'abc' is alphabetic while 'abc12' or 'ab-c' are not 00606 */ 00607 inline bool IsAlphabetic() const; 00608 00609 /** 00610 * @brief 00611 * Determines whether the string is alpha-numeric or not 00612 * 00613 * @return 00614 * 'true' if the string is alpha-numeric, else 'false' (maybe the string is empty?) 00615 * 00616 * @note 00617 * - Examples: 'abc', '12' or 'abc12' are alpha-numeric while 'abc-12' is not 00618 */ 00619 inline bool IsAlphaNumeric() const; 00620 00621 /** 00622 * @brief 00623 * Determines whether the string is numeric 00624 * 00625 * @return 00626 * 'true' if the string is numeric, else 'false' (maybe the string is empty?) 00627 * 00628 * @note 00629 * - Examples: '5' or '0' are numeric, 00630 * while '5.1', '.', 'AD', '3D', '5,5', '5.2.8' are not 00631 */ 00632 inline bool IsNumeric() const; 00633 00634 /** 00635 * @brief 00636 * Checks whether the given string is a substring of this string or not 00637 * 00638 * @param[in] sString 00639 * String to check, if empty string, 'true' will be returned 00640 * 00641 * @return 00642 * 'true', if the given string is a substring of this string, (or both are empty) else 'false' 00643 */ 00644 PLCORE_API bool IsSubstring(const String &sString) const; 00645 00646 /** 00647 * @brief 00648 * Checks whether the given string is a substring of this string or not 00649 * 00650 * @param[in] pszString 00651 * String to check, if a null pointer or empty, 'true' will be returned 00652 * 00653 * @return 00654 * 'true', if the given string is a substring of this string, (or both are empty) else 'false' else 'false' 00655 */ 00656 PLCORE_API bool IsSubstring(const char *pszString) const; 00657 PLCORE_API bool IsSubstring(const wchar_t *pszString) const; 00658 00659 /** 00660 * @brief 00661 * Returns the index of the substring if contained in this string 00662 * 00663 * @param[in] sString 00664 * String to check, if empty string, < 0 will be returned 00665 * @param[in] nPos 00666 * Start position within this string 00667 * 00668 * @return 00669 * Index of the substring if found within this string, < 0 on error 00670 * (maybe the given position is invalid) or if both strings are empty 00671 */ 00672 PLCORE_API int IndexOf(const String &sString, uint32 nPos = 0) const; 00673 00674 /** 00675 * @brief 00676 * Returns the index of the substring if contained in this string 00677 * 00678 * @param[in] pszString 00679 * String to check, if a null pointer or empty, < 0 will be returned 00680 * @param[in] nPos 00681 * Start position within this string 00682 * 00683 * @return 00684 * Index of the substring if found within this string, < 0 on error 00685 * (maybe the given position is invalid) or if both strings are empty 00686 */ 00687 PLCORE_API int IndexOf(const char *pszString, uint32 nPos = 0) const; 00688 PLCORE_API int IndexOf(const wchar_t *pszString, uint32 nPos = 0) const; 00689 00690 /** 00691 * @brief 00692 * Searches from backwards for the index of the substring within this string 00693 * 00694 * @param[in] sString 00695 * String to check, if empty string, < 0 will be returned 00696 * @param[in] nPos 00697 * Start position within this string, if < 0 start at the last character 00698 * 00699 * @return 00700 * Index of the substring if found within this string, < 0 on error 00701 * (maybe the given position is invalid) or if both strings are empty 00702 */ 00703 PLCORE_API int LastIndexOf(const String &sString, int nPos = -1) const; 00704 00705 /** 00706 * @brief 00707 * Searches from backwards for the index of the substring within this string 00708 * 00709 * @param[in] pszString 00710 * String to check, if a null pointer or empty, < 0 will be returned 00711 * @param[in] nPos 00712 * Start position within this string, if < 0 start at the last character 00713 * 00714 * @return 00715 * Index of the substring if found within this string, < 0 on error 00716 * (maybe the given position is invalid) or if both strings are empty 00717 */ 00718 PLCORE_API int LastIndexOf(const char *pszString, int nPos = -1) const; 00719 PLCORE_API int LastIndexOf(const wchar_t *pszString, int nPos = -1) const; 00720 00721 /** 00722 * @brief 00723 * Get a substring from the string 00724 * 00725 * @param[in] nPos 00726 * Start position 00727 * @param[in] nCount 00728 * Number of characters to copy, negative for everything from nPos to the end of the string 00729 * 00730 * @return 00731 * The substring 00732 */ 00733 PLCORE_API String GetSubstring(uint32 nPos, int nCount = -1) const; 00734 00735 /** 00736 * @brief 00737 * Change all characters to lower case 00738 * 00739 * @return 00740 * Reference to this string 00741 */ 00742 inline String &ToLower(); 00743 00744 /** 00745 * @brief 00746 * Change all characters to upper case 00747 * 00748 * @return 00749 * Reference to this string 00750 */ 00751 inline String &ToUpper(); 00752 00753 /** 00754 * @brief 00755 * Delete a substring 00756 * 00757 * @param[in] nPos 00758 * Start position of deletion 00759 * @param[in] nCount 00760 * Number of characters to delete, if negative delete all characters 00761 * 00762 * @return 00763 * Reference to this string 00764 */ 00765 PLCORE_API String &Delete(uint32 nPos = 0, int nCount = -1); 00766 00767 /** 00768 * @brief 00769 * Insert a character at a given location 00770 * 00771 * @param[in] nCharacter 00772 * Character to insert 00773 * @param[in] nPos 00774 * Position at which to insert the character 00775 * 00776 * @return 00777 * Reference to this string 00778 * 00779 * @note 00780 * - In case you just want to append a character, you may want to use the faster "+="-operator instead 00781 */ 00782 inline String &Insert(char nCharacter, uint32 nPos = 0); 00783 inline String &Insert(wchar_t nCharacter, uint32 nPos = 0); 00784 00785 /** 00786 * @brief 00787 * Insert a string at a given location 00788 * 00789 * @param[in] sString 00790 * String to insert 00791 * @param[in] nPos 00792 * Position at which to insert the string 00793 * @param[in] nCount 00794 * Number of characters to add, if negative insert the whole string 00795 * 00796 * @return 00797 * Reference to this string 00798 * 00799 * @note 00800 * - In case you just want to append a string, you may want to use the faster "+="-operator instead 00801 */ 00802 PLCORE_API String &Insert(const String &sString, uint32 nPos = 0, int nCount = -1); 00803 00804 /** 00805 * @brief 00806 * Insert a string at a given location 00807 * 00808 * @param[in] pszString 00809 * String to insert, can be a null pointer 00810 * @param[in] nPos 00811 * Position at which to insert the string 00812 * @param[in] nCount 00813 * Number of characters to add, if negative insert the whole string 00814 * 00815 * @return 00816 * Reference to this string 00817 * 00818 * @note 00819 * - In case you just want to append a string, you may want to use the faster "+="-operator instead 00820 */ 00821 PLCORE_API String &Insert(const char *pszString, uint32 nPos = 0, int nCount = -1); 00822 PLCORE_API String &Insert(const wchar_t *pszString, uint32 nPos = 0, int nCount = -1); 00823 00824 /** 00825 * @brief 00826 * Copies a string 00827 * 00828 * @param[in] pszString 00829 * String to copy, can be a null pointer 00830 * @param[in] nCount 00831 * Number of characters to copy, if negative copy the whole string 00832 * 00833 * @return 00834 * Reference to this string 00835 */ 00836 PLCORE_API String &Copy(const char *pszString, int nCount = -1); 00837 PLCORE_API String &Copy(const wchar_t *pszString, int nCount = -1); 00838 00839 /** 00840 * @brief 00841 * Replaces all occurrences of a character by another character 00842 * 00843 * @param[in] nOld 00844 * Character to be replaced 00845 * @param[in] nNew 00846 * Character to replace with 00847 * 00848 * @return 00849 * Number of replaced characters (0 if new = old) 00850 */ 00851 PLCORE_API uint32 Replace(char nOld, char nNew); 00852 PLCORE_API uint32 Replace(wchar_t nOld, wchar_t nNew); 00853 00854 /** 00855 * @brief 00856 * Replaces all occurrences of a substring by another string 00857 * 00858 * @param[in] sOld 00859 * Substring to be replaced 00860 * @param[in] sNew 00861 * String to replace with 00862 * 00863 * @return 00864 * Number of replaced substrings (0 if sNew = sOld or sOld is empty) 00865 */ 00866 PLCORE_API uint32 Replace(const String &sOld, const String &sNew); 00867 00868 /** 00869 * @brief 00870 * Replaces all occurrences of a substring by another string 00871 * 00872 * @param[in] pszOld 00873 * Substring to be replaced, can be a null pointer 00874 * @param[in] pszNew 00875 * String to replace with, can be a null pointer 00876 * 00877 * @return 00878 * Number of replaced substrings (0 if pszNew = pszOld or pszOld is a null pointer or empty) 00879 */ 00880 PLCORE_API uint32 Replace(const char *pszOld, const char *pszNew); 00881 PLCORE_API uint32 Replace(const wchar_t *pszOld, const wchar_t *pszNew); 00882 00883 /** 00884 * @brief 00885 * Sets a character at the given index 00886 * 00887 * @param[in] nIndex 00888 * Character index 00889 * @param[in] nCharacter 00890 * Character to set at the given index 00891 * 00892 * @return 00893 * 'true' if all went fine, else 'false' 00894 */ 00895 PLCORE_API bool SetCharacter(uint32 nIndex, char nCharacter); 00896 PLCORE_API bool SetCharacter(uint32 nIndex, wchar_t nCharacter); 00897 00898 /** 00899 * @brief 00900 * Removes all whitespace (tabs and spaces) at the beginning of the string 00901 * 00902 * @return 00903 * Reference to this string 00904 */ 00905 inline String &TrimLeading(); 00906 00907 /** 00908 * @brief 00909 * Removes all whitespace (tabs and spaces) at the end of the string 00910 * 00911 * @return 00912 * Reference to this string 00913 */ 00914 inline String &TrimTrailing(); 00915 00916 /** 00917 * @brief 00918 * Removes all whitespace (tabs and spaces) at the beginning and the end of the string 00919 * 00920 * @return 00921 * Reference to this string 00922 */ 00923 PLCORE_API String &Trim(); 00924 00925 /** 00926 * @brief 00927 * Removes line endings ("\r" or "\n") at the end of the string 00928 * 00929 * @return 00930 * Reference to this string 00931 * 00932 * @note 00933 * - Carriage return = CR = '\r' = 0x0D = 13 in decimal 00934 * - Line feed = LF = '\n' = 0x0A = 10 in decimal 00935 */ 00936 inline String &RemoveLineEndings(); 00937 00938 00939 //[-------------------------------------------------------] 00940 //[ Conversion functions ] 00941 //[-------------------------------------------------------] 00942 public: 00943 /** 00944 * @brief 00945 * Returns the character string as UTF8 00946 * 00947 * @return 00948 * Pointer to the character string as UTF8, never a null pointer - do NOT destroy the returned memory, it's owned by this string instance! 00949 * 00950 * @see 00951 * - GetASCII() 00952 */ 00953 inline const char *GetUTF8() const; 00954 00955 // Is valid tests 00956 PLCORE_API bool IsValidInteger() const; 00957 PLCORE_API bool IsValidFloat() const; 00958 00959 // Convert from string 00960 PLCORE_API bool GetBool() const; 00961 PLCORE_API char GetChar() const; 00962 PLCORE_API wchar_t GetWideChar() const; 00963 PLCORE_API int GetInt() const; 00964 PLCORE_API int64 GetInt64() const; 00965 PLCORE_API uint8 GetUInt8() const; 00966 PLCORE_API uint16 GetUInt16() const; 00967 PLCORE_API uint32 GetUInt32() const; 00968 PLCORE_API uint64 GetUInt64() const; 00969 inline uint_ptr GetUIntPtr() const; 00970 PLCORE_API float GetFloat() const; 00971 PLCORE_API double GetDouble() const; 00972 00973 // Convert to string 00974 inline String &operator =(bool bValue); 00975 PLCORE_API String &operator =(char nValue); 00976 PLCORE_API String &operator =(wchar_t nValue); 00977 PLCORE_API String &operator =(int nValue); 00978 PLCORE_API String &operator =(int64 nValue); 00979 PLCORE_API String &operator =(uint8 nValue); 00980 // PLCORE_API String &operator =(uint16 nValue); // We can't do that because wchar_t may be defined the same way as uint16 00981 PLCORE_API String &operator =(uint32 nValue); 00982 PLCORE_API String &operator =(uint64 nValue); 00983 PLCORE_API String &operator =(float fValue); 00984 PLCORE_API String &operator =(double dValue); 00985 00986 // Concatenation 00987 PLCORE_API String operator +(bool bValue) const; 00988 PLCORE_API String operator +(char nValue) const; 00989 PLCORE_API String operator +(wchar_t nValue) const; 00990 PLCORE_API String operator +(int nValue) const; 00991 inline String operator +(int64 nValue) const; 00992 inline String operator +(uint8 nValue) const; 00993 // inline String operator +(uint16 nValue) const; // We can't do that because wchar_t may be defined the same way as uint16 00994 inline String operator +(uint32 nValue) const; 00995 inline String operator +(uint64 nValue) const; 00996 inline String operator +(float fValue) const; 00997 inline String operator +(double dValue) const; 00998 PLCORE_API friend String operator +(bool bValue, const String &sString); 00999 PLCORE_API friend String operator +(char nValue, const String &sString); 01000 PLCORE_API friend String operator +(wchar_t nValue, const String &sString); 01001 inline friend String operator +(int nValue, const String &sString); 01002 inline friend String operator +(int64 nValue, const String &sString); 01003 inline friend String operator +(uint8 nValue, const String &sString); 01004 // inline friend String operator +(uint16 nValue, const String &sString); // We can't do that because wchar_t may be defined the same way as uint16 01005 inline friend String operator +(uint32 nValue, const String &sString); 01006 inline friend String operator +(uint64 nValue, const String &sString); 01007 inline friend String operator +(float fValue, const String &sString); 01008 inline friend String operator +(double dValue, const String &sString); 01009 PLCORE_API String &operator +=(bool bValue); 01010 PLCORE_API String &operator +=(char nValue); 01011 PLCORE_API String &operator +=(wchar_t nValue); 01012 inline String &operator +=(int nValue); 01013 inline String &operator +=(int64 nValue); 01014 inline String &operator +=(uint8 nValue); 01015 // inline String &operator +=(uint16 nValue); // We can't do that because wchar_t may be defined the same way as uint16 01016 inline String &operator +=(uint32 nValue); 01017 inline String &operator +=(uint64 nValue); 01018 inline String &operator +=(float fValue); 01019 inline String &operator +=(double dValue); 01020 01021 01022 //[-------------------------------------------------------] 01023 //[ Private functions ] 01024 //[-------------------------------------------------------] 01025 private: 01026 /** 01027 * @brief 01028 * Use a new string buffer 01029 * 01030 * @param[in] pStringBuffer 01031 * New string buffer to use, can be a null pointer 01032 */ 01033 PLCORE_API void SetStringBuffer(StringBuffer *pStringBuffer); 01034 01035 /** 01036 * @brief 01037 * Release string buffer 01038 */ 01039 void ReleaseStringBuffer(); 01040 01041 01042 //[-------------------------------------------------------] 01043 //[ Private data ] 01044 //[-------------------------------------------------------] 01045 private: 01046 StringBuffer *m_pStringBuffer; /**< Pointer to the string buffer, if a null pointer, string is empty */ 01047 01048 01049 }; 01050 01051 01052 //[-------------------------------------------------------] 01053 //[ Namespace ] 01054 //[-------------------------------------------------------] 01055 } // PLCore 01056 01057 01058 //[-------------------------------------------------------] 01059 //[ Implementation ] 01060 //[-------------------------------------------------------] 01061 #include "PLCore/String/String.inl" 01062 01063 01064 #endif // __PLCORE_STRING_H__
|