CrystalSpace

Public API Reference

Main Page | Modules | Class Hierarchy | Alphabetical List | Class List | File List | Class Members | File Members | Related Pages

csstring.h

Go to the documentation of this file.
00001 /*
00002     Crystal Space utility library: string class
00003     Copyright (C) 1999,2000 by Andrew Zabolotny <bit@eltech.ru>
00004 
00005     This library is free software; you can redistribute it and/or
00006     modify it under the terms of the GNU Library General Public
00007     License as published by the Free Software Foundation; either
00008     version 2 of the License, or (at your option) any later version.
00009 
00010     This library is distributed in the hope that it will be useful,
00011     but WITHOUT ANY WARRANTY; without even the implied warranty of
00012     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00013     Library General Public License for more details.
00014 
00015     You should have received a copy of the GNU Library General Public
00016     License along with this library; if not, write to the Free
00017     Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00018 */
00019 #ifndef __CS_CSSTRING_H__
00020 #define __CS_CSSTRING_H__
00021 
00026 #include <stdarg.h>
00027 #include <ctype.h>
00028 #include "csextern.h"
00029 #include "snprintf.h"
00030 #include "util.h"
00031 
00055 class CS_CSUTIL_EXPORT csString
00056 {
00057 protected:
00058   // Default number of bytes by which allocation should grow.
00059   // *** IMPORTANT *** This must be a power of two (i.e. 8, 16, 32, 64, etc.).
00060   enum { DEFAULT_GROW_BY = 64 };
00061 
00062   // String buffer.
00063   char* Data;
00064   // Length of string; not including null terminator.
00065   size_t Size;
00066   // Size in bytes of allocated string buffer.
00067   size_t MaxSize;
00068   // Size in bytes by which allocated buffer is increased when needed.
00069   size_t GrowBy;
00070   // Controls if allocated buffer grows exponentially (overrides GrowBy).
00071   bool GrowExponentially;
00072 
00073   // If necessary, increase the buffer capacity enough to hold NewSize bytes.
00074   // Buffer capacity is increased in GrowBy increments or exponentially
00075   // depending upon configuration.
00076   void ExpandIfNeeded(size_t NewSize);
00077 
00079   void Mug (csString& other);
00080 public:
00089   void SetCapacity (size_t NewSize);
00090 
00092   size_t GetCapacity() const
00093   { return MaxSize; }
00094 
00102   void SetGrowsBy(size_t);
00103 
00105   size_t GetGrowsBy() const
00106   { return GrowBy; }
00107 
00112   void SetGrowsExponentially(bool b)
00113   { GrowExponentially = b; }
00114 
00116   bool GetGrowsExponentially() const
00117   { return GrowExponentially; }
00118 
00125   void Free ();
00126 
00143   csString& Truncate (size_t Len);
00144 
00154   csString& Reclaim ();
00155 
00162   csString& Clear ()
00163   { return Truncate (0); }
00164 
00174   /*CS_DEPRECATED_METHOD*/ 
00175     // @@@ GCC and VC always seem to prefer this GetData() and barf "deprecated".
00176   char* GetData ()
00177   { return Data; }
00178 
00186   char const* GetData () const
00187   { return Data; }
00188 
00198    char const* GetDataSafe() const
00199    { return Data != 0 ? Data : ""; }
00200 
00206   size_t Length () const
00207   { return Size; }
00208 
00214   bool IsEmpty () const
00215   { return (Size == 0); }
00216 
00218   char& operator [] (size_t n)
00219   {
00220     CS_ASSERT (n < Size);
00221     return Data [n];
00222   }
00223 
00225   char operator [] (size_t n) const
00226   {
00227     CS_ASSERT (n < Size);
00228     return Data[n];
00229   }
00230 
00237   void SetAt (size_t n, const char c)
00238   {
00239     CS_ASSERT (n < Size);
00240     Data [n] = c;
00241   }
00242 
00244   char GetAt (size_t n) const
00245   {
00246     CS_ASSERT (n < Size);
00247     return Data [n];
00248   }
00249 
00256   csString& DeleteAt (size_t Pos, size_t Count = 1);
00257 
00264   csString& Insert (size_t Pos, const csString& Str);
00265 
00272   csString& Insert (size_t Pos, const char* Str);
00273 
00280   csString& Insert (size_t Pos, char C);
00281 
00290   csString& Overwrite (size_t Pos, const csString& Str);
00291 
00299   csString& Append (const char* Str, size_t Count = (size_t)-1);
00300 
00308   csString& Append (const csString& Str, size_t Count = (size_t)-1);
00309 
00314   csString& Append (char c)
00315   { char s[2]; s[0] = c; s[1] = '\0'; return Append(s); }
00316 
00321   csString& Append (unsigned char c)
00322   { return Append(char(c)); }
00323 
00330   csString Slice (size_t start, size_t len) const;
00331 
00342   void SubString (csString& sub, size_t start, size_t len) const;
00343 
00350   size_t FindFirst (char c, size_t pos = 0) const;
00351 
00358   size_t FindFirst (const char *c, size_t pos = 0) const;
00359 
00367   size_t FindLast (char c, size_t pos = (size_t)-1) const;
00368   
00375   size_t FindStr (const char* str, size_t pos = 0) const;
00376 
00381   void FindReplace (const char* str, const char* replaceWith);
00382 
00383 #define STR_APPEND(TYPE,FMT,SZ) csString& Append(TYPE n) \
00384   { char s[SZ]; cs_snprintf(s, SZ, FMT, n); return Append(s); }
00385 
00389   STR_APPEND(short, "%hd", 32)
00390   STR_APPEND(unsigned short, "%hu", 32)
00391   STR_APPEND(int, "%d", 32)
00392   STR_APPEND(unsigned int, "%u", 32)
00393   STR_APPEND(long, "%ld", 32)
00394   STR_APPEND(unsigned long, "%lu", 32)
00395   STR_APPEND(float, "%g", 64)
00396   STR_APPEND(double, "%g", 64)
00397 #undef STR_APPEND
00400 
00401   csString& Append (bool b) { return Append (b ? "1" : "0"); }
00402 
00412   csString& Replace (const csString& Str, size_t Count = (size_t)-1);
00413 
00423   csString& Replace (const char* Str, size_t Count = (size_t)-1);
00424 
00425 #define STR_REPLACE(TYPE) \
00426 csString& Replace (TYPE s) { Size = 0; return Append(s); }
00427 
00432   STR_REPLACE(char)
00433   STR_REPLACE(unsigned char)
00434   STR_REPLACE(short)
00435   STR_REPLACE(unsigned short)
00436   STR_REPLACE(int)
00437   STR_REPLACE(unsigned int)
00438   STR_REPLACE(long)
00439   STR_REPLACE(unsigned long)
00440   STR_REPLACE(float)
00441   STR_REPLACE(double)
00442   STR_REPLACE(bool)
00443 #undef STR_REPLACE
00452   bool Compare (const csString& iStr) const
00453   {
00454     if (&iStr == this)
00455       return true;
00456     size_t const n = iStr.Length();
00457     if (Size != n)
00458       return false;
00459     if (Size == 0 && n == 0)
00460       return true;
00461     return (memcmp (Data, iStr.GetData (), Size) == 0);
00462   }
00463 
00470   bool Compare (const char* iStr) const
00471   { return (strcmp (Data ? Data : "", iStr) == 0); }
00472 
00479   bool CompareNoCase (const csString& iStr) const
00480   {
00481     if (&iStr == this)
00482       return true;
00483     size_t const n = iStr.Length();
00484     if (Size != n)
00485       return false;
00486     if (Size == 0 && n == 0)
00487       return true;
00488     return (csStrNCaseCmp (Data, iStr.GetData (), Size) == 0);
00489   }
00490 
00497   bool CompareNoCase (const char* iStr) const
00498   { return (csStrNCaseCmp (Data ? Data : "", iStr, Size) == 0); }
00499 
00506   bool StartsWith (const csString& iStr, bool ignore_case = false) const
00507   {
00508     if (&iStr == this)
00509       return true;
00510     size_t const n = iStr.Length();
00511     if (n == 0)
00512       return true;
00513     if (n > Size)
00514       return false;
00515     CS_ASSERT(Data != 0);
00516     if (ignore_case)
00517       return (csStrNCaseCmp (Data, iStr.GetData (), n) == 0);
00518     else
00519       return (strncmp (Data, iStr.GetData (), n) == 0);
00520   }
00521 
00528   bool StartsWith (const char* iStr, bool ignore_case = false) const
00529   {
00530     if (iStr == 0)
00531       return false;
00532     size_t const n = strlen (iStr);
00533     if (n == 0)
00534       return true;
00535     if (n > Size)
00536       return false;
00537     CS_ASSERT(Data != 0);
00538     if (ignore_case)
00539       return (csStrNCaseCmp (Data, iStr, n) == 0);
00540     else
00541       return (strncmp (Data, iStr, n) == 0);
00542   }
00543 
00548   csString () : Data (0), Size (0), MaxSize (0), GrowBy (DEFAULT_GROW_BY),
00549     GrowExponentially (false) {}
00550 
00556   csString (size_t Length) : Data (0), Size (0), MaxSize (0),
00557     GrowBy (DEFAULT_GROW_BY), GrowExponentially(false)
00558   { SetCapacity (Length); }
00559 
00565   csString (const csString& copy) : Data (0), Size (0), MaxSize (0),
00566     GrowBy (DEFAULT_GROW_BY), GrowExponentially(false)
00567   { Append (copy); }
00568 
00574   csString (const char* src) : Data (0), Size (0), MaxSize (0),
00575     GrowBy (DEFAULT_GROW_BY), GrowExponentially(false)
00576   { Append (src); }
00577 
00579   csString (char c) : Data (0), Size (0), MaxSize (0),
00580     GrowBy (DEFAULT_GROW_BY), GrowExponentially(false)
00581   { Append (c); }
00582 
00584   csString (unsigned char c) : Data(0), Size (0), MaxSize (0),
00585     GrowBy (DEFAULT_GROW_BY), GrowExponentially(false)
00586   { Append ((char) c); }
00587 
00589   virtual ~csString ();
00590 
00596   csString Clone () const
00597   { return csString (*this); }
00598 
00606   csString& LTrim();
00607 
00615   csString& RTrim();
00616 
00622   csString& Trim();
00623 
00629   csString& Collapse();
00630 
00637   csString& Format(const char* format, ...) CS_GNUC_PRINTF (2, 3);
00638 
00645   csString& FormatV(const char* format, va_list args);
00646 
00647 #define STR_FORMAT(TYPE) \
00648   static csString Format (TYPE v);
00653   STR_FORMAT(short)
00654   STR_FORMAT(unsigned short)
00655   STR_FORMAT(int)
00656   STR_FORMAT(unsigned int)
00657   STR_FORMAT(long)
00658   STR_FORMAT(unsigned long)
00659   STR_FORMAT(float)
00660   STR_FORMAT(double)
00661 #undef STR_FORMAT
00662 
00663 #define STR_FORMAT_INT(TYPE) \
00664   static csString Format (TYPE v, int width, int prec=0);
00665   STR_FORMAT_INT(short)
00666   STR_FORMAT_INT(unsigned short)
00667   STR_FORMAT_INT(int)
00668   STR_FORMAT_INT(unsigned int)
00669   STR_FORMAT_INT(long)
00670   STR_FORMAT_INT(unsigned long)
00671 #undef STR_FORMAT_INT
00672 
00673 #define STR_FORMAT_FLOAT(TYPE) \
00674   static csString Format (TYPE v, int width, int prec=6);
00675   STR_FORMAT_FLOAT(float)
00676   STR_FORMAT_FLOAT(double)
00677 #undef STR_FORMAT_FLOAT
00688   csString& PadLeft (size_t NewSize, char PadChar = ' ');
00689 
00691   csString AsPadLeft (size_t NewSize, char PadChar = ' ') const;
00692 
00693 #define STR_PADLEFT(TYPE) \
00694   static csString PadLeft (TYPE v, size_t iNewSize, char iChar=' ');
00699   STR_PADLEFT(const csString&)
00700   STR_PADLEFT(const char*)
00701   STR_PADLEFT(char)
00702   STR_PADLEFT(unsigned char)
00703   STR_PADLEFT(short)
00704   STR_PADLEFT(unsigned short)
00705   STR_PADLEFT(int)
00706   STR_PADLEFT(unsigned int)
00707   STR_PADLEFT(long)
00708   STR_PADLEFT(unsigned long)
00709   STR_PADLEFT(float)
00710   STR_PADLEFT(double)
00711   STR_PADLEFT(bool)
00712 #undef STR_PADLEFT
00723   csString& PadRight (size_t NewSize, char PadChar = ' ');
00724 
00726   csString AsPadRight (size_t NewSize, char PadChar = ' ') const;
00727 
00728 #define STR_PADRIGHT(TYPE) \
00729   static csString PadRight (TYPE v, size_t iNewSize, char iChar=' ');
00734   STR_PADRIGHT(const csString&)
00735   STR_PADRIGHT(const char*)
00736   STR_PADRIGHT(char)
00737   STR_PADRIGHT(unsigned char)
00738   STR_PADRIGHT(short)
00739   STR_PADRIGHT(unsigned short)
00740   STR_PADRIGHT(int)
00741   STR_PADRIGHT(unsigned int)
00742   STR_PADRIGHT(long)
00743   STR_PADRIGHT(unsigned long)
00744   STR_PADRIGHT(float)
00745   STR_PADRIGHT(double)
00746   STR_PADRIGHT(bool)
00747 #undef STR_PADRIGHT
00761   csString& PadCenter (size_t NewSize, char PadChar = ' ');
00762 
00764   csString AsPadCenter (size_t NewSize, char PadChar = ' ') const;
00765 
00766 #define STR_PADCENTER(TYPE) \
00767   static csString PadCenter (TYPE v, size_t iNewSize, char iChar=' ');
00772   STR_PADCENTER(const csString&)
00773   STR_PADCENTER(const char*)
00774   STR_PADCENTER(char)
00775   STR_PADCENTER(unsigned char)
00776   STR_PADCENTER(short)
00777   STR_PADCENTER(unsigned short)
00778   STR_PADCENTER(int)
00779   STR_PADCENTER(unsigned int)
00780   STR_PADCENTER(long)
00781   STR_PADCENTER(unsigned long)
00782   STR_PADCENTER(float)
00783   STR_PADCENTER(double)
00784   STR_PADCENTER(bool)
00785 #undef STR_PADCENTER
00788 #define STR_ASSIGN(TYPE) \
00789 const csString& operator = (TYPE s) { return Replace (s); }
00794   STR_ASSIGN(const csString&)
00795   STR_ASSIGN(const char*)
00796   STR_ASSIGN(char)
00797   STR_ASSIGN(unsigned char)
00798   STR_ASSIGN(short)
00799   STR_ASSIGN(unsigned short)
00800   STR_ASSIGN(int)
00801   STR_ASSIGN(unsigned int)
00802   STR_ASSIGN(long)
00803   STR_ASSIGN(unsigned long)
00804   STR_ASSIGN(float)
00805   STR_ASSIGN(double)
00806   STR_ASSIGN(bool)
00807 #undef STR_ASSIGN
00810 #define STR_OP_APPEND(TYPE) \
00811   csString &operator += (TYPE s) { return Append (s); }
00816   STR_OP_APPEND(const csString&)
00817   STR_OP_APPEND(const char*)
00818   STR_OP_APPEND(char)
00819   STR_OP_APPEND(unsigned char)
00820   STR_OP_APPEND(short)
00821   STR_OP_APPEND(unsigned short)
00822   STR_OP_APPEND(int)
00823   STR_OP_APPEND(unsigned int)
00824   STR_OP_APPEND(long)
00825   STR_OP_APPEND(unsigned long)
00826   STR_OP_APPEND(float)
00827   STR_OP_APPEND(double)
00828   STR_OP_APPEND(bool)
00829 #undef STR_OP_APPEND
00832 
00833   csString operator + (const csString &iStr) const
00834   { return Clone ().Append (iStr); }
00835 
00843   operator const char* () const
00844   { return Data; }
00845 
00852   bool operator == (const csString& Str) const
00853   { return Compare (Str); }
00860   bool operator == (const char* Str) const
00861   { return Compare (Str); }
00868   bool operator < (const csString& Str) const
00869   {
00870     return strcmp (GetDataSafe (), Str.GetDataSafe ()) < 0;
00871   }
00878   bool operator < (const char* Str) const
00879   {
00880     return strcmp (GetDataSafe (), Str) < 0;
00881   }
00888   bool operator > (const csString& Str) const
00889   {
00890     return strcmp (GetDataSafe (), Str.GetDataSafe ()) > 0;
00891   }
00898   bool operator > (const char* Str) const
00899   {
00900     return strcmp (GetDataSafe (), Str) > 0;
00901   }
00908   bool operator != (const csString& Str) const
00909   { return !Compare (Str); }
00916   bool operator != (const char* Str) const
00917   { return !Compare (Str); }
00918 
00923   csString& Downcase();
00928   csString& Upcase();
00929 
00940   char* Detach ()
00941   { char* d = Data; Data = 0; Size = 0; MaxSize = 0; return d; }
00942 };
00943 
00945 inline csString operator + (const char* iStr1, const csString &iStr2)
00946 {
00947   return csString (iStr1).Append (iStr2);
00948 }
00949 
00951 inline csString operator + (const csString& iStr1, const char* iStr2)
00952 {
00953   return iStr1.Clone ().Append (iStr2);
00954 }
00955 
00956 #define STR_SHIFT(TYPE) \
00957   inline csString &operator << (csString &s, TYPE v) { return s.Append (v); }
00958 
00966 STR_SHIFT(const csString&)
00967 STR_SHIFT(const char*)
00968 STR_SHIFT(char)
00969 STR_SHIFT(unsigned char)
00970 STR_SHIFT(short)
00971 STR_SHIFT(unsigned short)
00972 STR_SHIFT(int)
00973 STR_SHIFT(unsigned int)
00974 STR_SHIFT(long)
00975 STR_SHIFT(unsigned long)
00976 STR_SHIFT(float)
00977 STR_SHIFT(double)
00978 STR_SHIFT(bool)
00979 #undef STR_SHIFT
00982 #endif // __CS_CSSTRING_H__

Generated for Crystal Space by doxygen 1.3.9.1