Public API Reference

csutil/csstring.h

Go to the documentation of this file.

/*
    Crystal Space utility library: string class
    Copyright (C) 1999,2000 by Andrew Zabolotny <[email protected]>

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Library General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Library General Public License for more details.

    You should have received a copy of the GNU Library General Public
    License along with this library; if not, write to the Free
    Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*/
#ifndef __CS_CSSTRING_H__
#define __CS_CSSTRING_H__

#include "csextern.h"
#include "csutil/snprintf.h"
#include "csutil/util.h"

class CS_CRYSTALSPACE_EXPORT csStringBase
{
protected:
  enum { DEFAULT_GROW_BY = 64 };

  char* Data;
  size_t Size;
  size_t MaxSize;
  size_t GrowBy;

  void ExpandIfNeeded (size_t NewSize);

  virtual void SetCapacityInternal (size_t NewSize, bool soft);

  size_t ComputeNewSize (size_t NewSize);

  virtual char* GetDataMutable ()
  { return Data; }

public:
  void SetCapacity (size_t NewSize);

  virtual size_t GetCapacity() const
  { return MaxSize > 0 ? MaxSize - 1 : 0; }

  csStringBase& Append (const char* Str, size_t Count = (size_t)-1);

  csStringBase& Append (const wchar_t* Str, size_t Count = (size_t)-1);

  csStringBase& Append (const csStringBase& Str, size_t Count = (size_t)-1);

  csStringBase& Append (char c);

  /*csStringBase& Append (unsigned char c)
  { return Append(char(c)); }*/

  csStringBase& Append (bool b) { return Append (b ? "1" : "0"); }

  csStringBase& AppendFmt (const char* format, ...) CS_GNUC_PRINTF (2, 3);
  csStringBase& AppendFmtV (const char* format, va_list args);

  csStringBase& Append (short v) { return AppendFmt ("%hd", v); }
  csStringBase& Append (unsigned short v) { return AppendFmt ("%hu", v); }
  csStringBase& Append (int v) { return AppendFmt ("%d", v); }
  csStringBase& Append (unsigned int v) { return AppendFmt ("%u", v); }
  csStringBase& Append (long v) { return AppendFmt ("%ld", v); }
  csStringBase& Append (unsigned long v) { return AppendFmt ("%lu", v); }
  csStringBase& Append (float v) { return AppendFmt ("%g", v); }
  csStringBase& Append (double v) { return AppendFmt ("%g", v); }
#ifndef __STRICT_ANSI__
  csStringBase& Append (longlong v) { return AppendFmt ("%lld", v); }
  csStringBase& Append (ulonglong v) { return AppendFmt ("%llu", v); }
#endif

  csStringBase () : Data (0), Size (0), MaxSize (0), GrowBy (DEFAULT_GROW_BY)
  {}

  csStringBase (size_t Length) : Data (0), Size (0), MaxSize (0),
    GrowBy (DEFAULT_GROW_BY)
  { SetCapacity (Length); }

  csStringBase (const csStringBase& copy) : Data (0), Size (0), MaxSize (0),
    GrowBy (DEFAULT_GROW_BY)
  { Append (copy); }

  csStringBase (const char* src) : Data (0), Size (0), MaxSize (0),
    GrowBy (DEFAULT_GROW_BY)
  { Append (src); }

  csStringBase (const wchar_t* src) : Data (0), Size (0), MaxSize (0),
    GrowBy (DEFAULT_GROW_BY)
  { Append (src); }

  csStringBase (const char* src, size_t _length) : Data (0), Size (0),
        MaxSize (0), GrowBy (DEFAULT_GROW_BY)
  { Append (src, _length); }

  csStringBase (const wchar_t* src, size_t _length) : Data (0), Size (0),
        MaxSize (0), GrowBy (DEFAULT_GROW_BY)
  { Append (src, _length); }

  csStringBase (char c) : Data (0), Size (0), MaxSize (0),
    GrowBy (DEFAULT_GROW_BY)
  { Append (c); }

  csStringBase (unsigned char c) : Data(0), Size (0), MaxSize (0),
    GrowBy (DEFAULT_GROW_BY)
  { Append ((char) c); }

  virtual ~csStringBase ();

  void SetGrowsBy(size_t);

  size_t GetGrowsBy() const
  { return GrowBy; }

  CS_DEPRECATED_METHOD_MSG("Use SetGrowsBy(0) instead.") 
  void SetGrowsExponentially(bool b)
  { SetGrowsBy(b ? 0 : DEFAULT_GROW_BY); }

  CS_DEPRECATED_METHOD_MSG("Use GetGrowsBy() instead.") 
  bool GetGrowsExponentially() const
  { return GetGrowsBy() == 0; }

  virtual void Free ();

  csStringBase& Truncate (size_t Len);

  csStringBase& Empty() { return Truncate (0); }

  virtual void ShrinkBestFit ();

  csStringBase& Reclaim () { ShrinkBestFit(); return *this; }

  csStringBase& Clear () { return Empty(); }

  CS_VISIBILITY_DEFAULT // <- @@@ FIXME: needed for gcc 4.1.0
  virtual char const* GetData () const
  { return Data; }

   char const* GetDataSafe() const
   { char const* p = GetData(); return p != 0 ? p : ""; }

  size_t Length () const
  { return Size; }

  bool IsEmpty () const
  { return (Size == 0); }

  char& operator [] (size_t n)
  {
    CS_ASSERT (n < Size);
    return GetDataMutable()[n];
  }

  char operator [] (size_t n) const
  {
    CS_ASSERT (n < Size);
    return GetData()[n];
  }

  void SetAt (size_t n, const char c)
  {
    CS_ASSERT (n < Size);
    GetDataMutable() [n] = c;
  }

  char GetAt (size_t n) const
  {
    CS_ASSERT (n < Size);
    return GetData() [n];
  }

  csStringBase& DeleteAt (size_t Pos, size_t Count = 1);

  csStringBase& Insert (size_t Pos, const csStringBase& Str);

  csStringBase& Insert (size_t Pos, const char* Str);

  csStringBase& Insert (size_t Pos, char C);

  csStringBase& Overwrite (size_t Pos, const csStringBase& Str);

  csStringBase Slice (size_t start, size_t len = (size_t)-1) const;

  void SubString (csStringBase& sub, size_t start, 
    size_t len = (size_t)-1) const;

  size_t FindFirst (char c, size_t pos = 0) const;

  size_t FindFirst (const char *c, size_t pos = 0) const;

  size_t FindLast (char c, size_t pos = (size_t)-1) const;
  
  size_t FindLast (const char *c, size_t pos = (size_t)-1) const;

  size_t Find (const char* search, size_t pos = 0) const;

  /* CS_DEPRECATED_METHOD_MSG("Use Find() instead.") */
  size_t FindStr (const char* search, size_t pos = 0) const
  { return Find(search, pos); }

  void ReplaceAll (const char* search, const char* replacement);

  /* CS_DEPRECATED_METHOD_MSG("Use ReplaceAll() instead.") */
  void FindReplace (const char* search, const char* replacement)
  { ReplaceAll(search, replacement); }

  csStringBase& Format (const char* format, ...) CS_GNUC_PRINTF (2, 3);

  csStringBase& FormatV (const char* format, va_list args);

  csStringBase& Replace (const csStringBase& Str, size_t Count = (size_t)-1);

  csStringBase& Replace (const char* Str, size_t Count = (size_t)-1);

  template<typename T>
  csStringBase& Replace (T const& val) { Truncate (0); return Append (val); }

  bool Compare (const csStringBase& iStr) const
  {
    if (&iStr == this)
      return true;
    size_t const n = iStr.Length();
    if (Size != n)
      return false;
    if (Size == 0 && n == 0)
      return true;
    return (memcmp (GetDataSafe(), iStr.GetDataSafe (), Size) == 0);
  }

  bool Compare (const char* iStr) const
  { return (strcmp (GetDataSafe(), iStr) == 0); }

  bool CompareNoCase (const csStringBase& iStr) const
  {
    if (&iStr == this)
      return true;
    size_t const n = iStr.Length();
    if (Size != n)
      return false;
    if (Size == 0 && n == 0)
      return true;
    return (csStrNCaseCmp (GetDataSafe(), iStr.GetDataSafe(), Size) == 0);
  }

  bool CompareNoCase (const char* iStr) const
  { return (csStrCaseCmp (GetDataSafe(), iStr) == 0); }

  bool StartsWith (const csStringBase& iStr, bool ignore_case = false) const
  {
    char const* p = GetDataSafe();
    if (&iStr == this)
      return true;
    size_t const n = iStr.Length();
    if (n == 0)
      return true;
    if (n > Size)
      return false;
    CS_ASSERT(p != 0);
    if (ignore_case)
      return (csStrNCaseCmp (p, iStr.GetDataSafe (), n) == 0);
    else
      return (strncmp (p, iStr.GetDataSafe (), n) == 0);
  }

  bool StartsWith (const char* iStr, bool ignore_case = false) const
  {
    char const* p = GetDataSafe();
    if (iStr == 0)
      return false;
    size_t const n = strlen (iStr);
    if (n == 0)
      return true;
    if (n > Size)
      return false;
    CS_ASSERT(p != 0);
    if (ignore_case)
      return (csStrNCaseCmp (p, iStr, n) == 0);
    else
      return (strncmp (p, iStr, n) == 0);
  }

  csStringBase Clone () const
  { return csStringBase (*this); }

  csStringBase& LTrim();

  csStringBase& RTrim();

  csStringBase& Trim();

  csStringBase& Collapse();

  csStringBase& PadLeft (size_t NewSize, char PadChar = ' ');

  csStringBase& PadRight (size_t NewSize, char PadChar = ' ');

  csStringBase& PadCenter (size_t NewSize, char PadChar = ' ');

  template<typename T>
  const csStringBase& operator = (T const& s) { return Replace (s); }

  const csStringBase& operator = (const csStringBase& copy)
  { Replace(copy); return *this; }

  template<typename T>
  csStringBase &operator += (T const& s) { return Append (s); }

  // Specialization which prevents gcc from barfing on strings allocated via
  // CS_ALLOC_STACK_ARRAY().
  csStringBase &operator += (char const* s)
  { return Append(s); }

  csStringBase operator + (const csStringBase &iStr) const
  { return Clone ().Append (iStr); }

  operator const char* () const
  { return GetData(); }

  bool operator == (const csStringBase& Str) const
  { return Compare (Str); }
  bool operator == (const char* Str) const
  { return Compare (Str); }
  bool operator < (const csStringBase& Str) const
  {
    return strcmp (GetDataSafe (), Str.GetDataSafe ()) < 0;
  }
  bool operator < (const char* Str) const
  {
    return strcmp (GetDataSafe (), Str) < 0;
  }
  bool operator > (const csStringBase& Str) const
  {
    return strcmp (GetDataSafe (), Str.GetDataSafe ()) > 0;
  }
  bool operator > (const char* Str) const
  {
    return strcmp (GetDataSafe (), Str) > 0;
  }
  bool operator != (const csStringBase& Str) const
  { return !Compare (Str); }
  bool operator != (const char* Str) const
  { return !Compare (Str); }

  template <typename T>
  csStringBase &operator << (T const& v)
  { return Append (v); }

  // Specialization which prevents gcc from barfing on strings allocated via
  // CS_ALLOC_STACK_ARRAY().
  csStringBase &operator << (char const* v)
  { return Append(v); }

  csStringBase& Downcase();
  csStringBase& Upcase();

  virtual char* Detach ()
  { char* d = Data; Data = 0; Size = 0; MaxSize = 0; return d; }
  uint GetHash() const;
};

inline csStringBase operator + (const char* iStr1, const csStringBase &iStr2)
{
  return csStringBase (iStr1).Append (iStr2);
}

inline csStringBase operator + (const csStringBase& iStr1, const char* iStr2)
{
  return iStr1.Clone ().Append (iStr2);
}

template<int LEN = 36>
class csStringFast : public csStringBase
{
protected:
  char minibuff[LEN];
  size_t miniused;

  virtual void SetCapacityInternal (size_t NewSize, bool soft)
  {
    if (Data != 0) // If dynamic buffer already allocated, just re-use it.
      csStringBase::SetCapacityInternal(NewSize, soft);
    else
    {
      NewSize++; // Plus one for implicit null byte.
      if (NewSize <= LEN)
        miniused = NewSize;
      else
      {
        CS_ASSERT(MaxSize == 0);
        if (soft)
          NewSize = ComputeNewSize (NewSize);
        Data = new char[NewSize];
        MaxSize = NewSize;
        if (Size == 0)
          Data[0] = '\0';
        else
          memcpy(Data, minibuff, Size + 1);
      }
    }
  }

  virtual char* GetDataMutable ()
  { return (miniused == 0 && Data == 0 ? 0 : (Data != 0 ? Data : minibuff)); }

public:
  csStringFast () : csStringBase(), miniused(0) { }
  csStringFast (size_t Length) : csStringBase(), miniused(0)
  { SetCapacity (Length); }
  csStringFast (const csStringBase& copy) : csStringBase (), miniused(0) 
  { Append (copy); }
  csStringFast (const csStringFast& copy) : csStringBase (), miniused(0)
  { Append (copy); }
  csStringFast (const char* src) : csStringBase(), miniused(0)
  { Append (src); }
  csStringFast (const char* src, size_t _length) : csStringBase(), miniused(0)
  { Append (src, _length); }

  
  csStringFast (char c) : csStringBase(), miniused(0)
  { Append (c); }
  csStringFast (unsigned char c) : csStringBase(), miniused(0)
  { Append ((char)c); }
  virtual ~csStringFast () { }

  const csStringFast& operator = (const csStringBase& copy)
  { Replace(copy); return *this; }

  template<typename T>
  const csStringFast& operator = (T const& s) { Replace (s); return *this; }

  virtual char const* GetData () const
  { return (miniused == 0 && Data == 0 ? 0 : (Data != 0 ? Data : minibuff)); }

  virtual size_t GetCapacity() const
  { return Data != 0 ? csStringBase::GetCapacity() : miniused - 1; }

  virtual void ShrinkBestFit ()
  {
    if (Size == 0)
    {
      csStringBase::ShrinkBestFit();
      miniused = 0;
    }
    else
    {
      size_t needed = Size + 1;
      if (needed > LEN)
        csStringBase::ShrinkBestFit();
      else
      {
        miniused = needed;
        if (Data != 0)
        {
          memcpy(minibuff, Data, needed); // Includes implicit null byte.
          csStringBase::Free();
        }
      }
    }
  }

  virtual void Free () { miniused = 0; csStringBase::Free(); }

  virtual char* Detach ()
  { 
    if (Data != 0)
      return csStringBase::Detach();
    else if (miniused == 0)
      return 0; // Emulate NULL return of csStringBase in this case.
    else
    {
      CS_ASSERT(MaxSize == 0);
      char* d = csStrNew (minibuff);
      Size = 0; miniused = 0;
      return d;
    }
  }
};

template<>
class csStringFast<0> : public csStringBase
{
public:
  csStringFast () : csStringBase() { }
  csStringFast (size_t Length) : csStringBase(Length) { }
  csStringFast (const csStringBase& copy) : csStringBase (copy) { }
  csStringFast (const char* src) : csStringBase(src) { }
  csStringFast (const char* src, size_t _length) : csStringBase(src, _length)
  { }
  csStringFast (char c) : csStringBase(c) { }
  csStringFast (unsigned char c) : csStringBase(c) { }
  const csStringFast& operator = (const csStringBase& copy)
  { Replace(copy); return *this; }
  const csStringFast& operator = (const char* copy)
  { Replace(copy); return *this; }
  const csStringFast& operator = (char x)
  { Replace(x); return *this; }
  const csStringFast& operator = (unsigned char x)
  { Replace(x); return *this; }
  const csStringFast& operator = (bool x)
  { Replace(x); return *this; }
  const csStringFast& operator = (short x)
  { Replace(x); return *this; }
  const csStringFast& operator = (unsigned short x)
  { Replace(x); return *this; }
  const csStringFast& operator = (int x)
  { Replace(x); return *this; }
  const csStringFast& operator = (unsigned int x)
  { Replace(x); return *this; }
  const csStringFast& operator = (long x)
  { Replace(x); return *this; }
  const csStringFast& operator = (unsigned long x)
  { Replace(x); return *this; }
  const csStringFast& operator = (float x)
  { Replace(x); return *this; }
  const csStringFast& operator = (double x)
  { Replace(x); return *this; }
#ifndef __STRICT_ANSI__
  const csStringFast& operator = (longlong x)
  { Replace(x); return *this; }
  const csStringFast& operator = (ulonglong x)
  { Replace(x); return *this; }
#endif
};

#ifndef SWIG

typedef csStringFast<> csStringFastDefault;
#else
#define csStringFastDefault csStringFast<36>
%template(csStringParent) csStringFast<36>;
#endif

class csString : public csStringFastDefault
{
public:
  csString () : csStringFast<> () { }
  csString (size_t Length) : csStringFast<> (Length) { }

  csString (const csString& copy) :
    csStringFast<> ((const csStringBase&)copy) { }
  csString (const csStringBase& copy) : csStringFast<> (copy) { }

  csString (const char* src) : csStringFast<> (src) { }
  csString (const char* src, size_t _length) : csStringFast<> (src, _length) { }
  csString (char c) : csStringFast<> (c) { }
  csString (unsigned char c) : csStringFast<> (c) { }


  const csString& operator = (const csString& copy)
  { Replace(copy); return *this; }
  const csString& operator = (const csStringBase& copy)
  { Replace(copy); return *this; }
  const csString& operator = (const char* copy)
  { Replace(copy); return *this; }
  const csString& operator = (char x)
  { Replace(x); return *this; }
  const csString& operator = (unsigned char x)
  { Replace(x); return *this; }
  const csString& operator = (bool x)
  { Replace(x); return *this; }
  const csString& operator = (short x)
  { Replace(x); return *this; }
  const csString& operator = (unsigned short x)
  { Replace(x); return *this; }
  const csString& operator = (int x)
  { Replace(x); return *this; }
  const csString& operator = (unsigned int x)
  { Replace(x); return *this; }
  const csString& operator = (long x)
  { Replace(x); return *this; }
  const csString& operator = (unsigned long x)
  { Replace(x); return *this; }
  const csString& operator = (float x)
  { Replace(x); return *this; }
  const csString& operator = (double x)
  { Replace(x); return *this; }
#ifndef __STRICT_ANSI__
  const csString& operator = (longlong x)
  { Replace(x); return *this; }
  const csString& operator = (ulonglong x)
  { Replace(x); return *this; }
#endif

};

#endif // __CS_CSSTRING_H__

---