Fix missing documentation for several GDI functions.

[wxWidgets.git] / include / wx / string.h

diff --git a/include/wx/string.h b/include/wx/string.h
index 95d440a362a8cee9299a4a5c4b3b5412ad1eb585..53ae8907d8b0185320b00251412fc71c9ecb392e 100644 (file)
--- a/include/wx/string.h
+++ b/include/wx/string.h
@@ -24,7 +24,6 @@
 
 #include "wx/defs.h"        // everybody should include this
 
 
 #include "wx/defs.h"        // everybody should include this
 

-#ifndef __WXPALMOS5__

 #if defined(__WXMAC__) || defined(__VISAGECPP__)
     #include <ctype.h>
 #endif
 #if defined(__WXMAC__) || defined(__VISAGECPP__)
     #include <ctype.h>
 #endif


@@ -47,7 +46,6 @@
 #ifdef HAVE_STRCASECMP_IN_STRINGS_H
     #include <strings.h>    // for strcasecmp()
 #endif // HAVE_STRCASECMP_IN_STRINGS_H
 #ifdef HAVE_STRCASECMP_IN_STRINGS_H
     #include <strings.h>    // for strcasecmp()
 #endif // HAVE_STRCASECMP_IN_STRINGS_H

-#endif // ! __WXPALMOS5__

 
 #include "wx/wxcrtbase.h"   // for wxChar, wxStrlen() etc.
 #include "wx/strvararg.h"
 
 #include "wx/wxcrtbase.h"   // for wxChar, wxStrlen() etc.
 #include "wx/strvararg.h"


@@ -71,7 +69,7 @@
 // it would have to be re-tested and probably corrected
 // CS: under OSX release builds the string destructor/cache cleanup sometimes
 // crashes, disable until we find the true reason or a better workaround
 // it would have to be re-tested and probably corrected
 // CS: under OSX release builds the string destructor/cache cleanup sometimes
 // crashes, disable until we find the true reason or a better workaround

-#if wxUSE_UNICODE_UTF8 && !defined(__WXMSW__) && !defined(__WXOSX__)
+#if wxUSE_UNICODE_UTF8 && !defined(__WINDOWS__) && !defined(__WXOSX__)

     #define wxUSE_STRING_POS_CACHE 1
 #else
     #define wxUSE_STRING_POS_CACHE 0
     #define wxUSE_STRING_POS_CACHE 1
 #else
     #define wxUSE_STRING_POS_CACHE 0


@@ -156,7 +154,7 @@ inline int Stricmp(const char *psz1, const char *psz2)
   } while ( c1 && (c1 == c2) );
 
   return c1 - c2;
   } while ( c1 && (c1 == c2) );
 
   return c1 - c2;

-#elif defined(__VISUALC__) || ( defined(__MWERKS__) && defined(__INTEL__) )
+#elif defined(__VISUALC__)

   return _stricmp(psz1, psz2);
 #elif defined(__SC__)
   return _stricmp(psz1, psz2);
   return _stricmp(psz1, psz2);
 #elif defined(__SC__)
   return _stricmp(psz1, psz2);


@@ -170,19 +168,10 @@ inline int Stricmp(const char *psz1, const char *psz2)
   return stricmp(psz1, psz2);
 #elif defined(__WXPM__)
   return stricmp(psz1, psz2);
   return stricmp(psz1, psz2);
 #elif defined(__WXPM__)
   return stricmp(psz1, psz2);

-#elif defined(__WXPALMOS__) || \
-      defined(HAVE_STRCASECMP_IN_STRING_H) || \
+#elif defined(HAVE_STRCASECMP_IN_STRING_H) || \

       defined(HAVE_STRCASECMP_IN_STRINGS_H) || \
       defined(__GNUWIN32__)
   return strcasecmp(psz1, psz2);
       defined(HAVE_STRCASECMP_IN_STRINGS_H) || \
       defined(__GNUWIN32__)
   return strcasecmp(psz1, psz2);

-#elif defined(__MWERKS__) && !defined(__INTEL__)
-  register char c1, c2;
-  do {
-    c1 = tolower(*psz1++);
-    c2 = tolower(*psz2++);
-  } while ( c1 && (c1 == c2) );
-
-  return c1 - c2;

 #else
   // almost all compilers/libraries provide this function (unfortunately under
   // different names), that's why we don't implement our own which will surely
 #else
   // almost all compilers/libraries provide this function (unfortunately under
   // different names), that's why we don't implement our own which will surely


@@ -1153,6 +1142,25 @@ public:
   #undef WX_STR_ITERATOR_TAG
   #undef WX_STR_ITERATOR_IMPL
 
   #undef WX_STR_ITERATOR_TAG
   #undef WX_STR_ITERATOR_IMPL
 

+  // This method is mostly used by wxWidgets itself and return the offset of
+  // the given iterator in bytes relative to the start of the buffer
+  // representing the current string contents in the current locale encoding.
+  //
+  // It is inefficient as it involves converting part of the string to this
+  // encoding (and also unsafe as it simply returns 0 if the conversion fails)
+  // and so should be avoided if possible, wx itself only uses it to implement
+  // backwards-compatible API.
+  ptrdiff_t IterOffsetInMBStr(const const_iterator& i) const
+  {
+      const wxString str(begin(), i);
+
+      // This is logically equivalent to strlen(str.mb_str()) but avoids
+      // actually converting the string to multibyte and just computes the
+      // length that it would have after conversion.
+      size_t ofs = wxConvLibc.FromWChar(NULL, 0, str.wc_str(), str.length());
+      return ofs == wxCONV_FAILED ? 0 : static_cast<ptrdiff_t>(ofs);
+  }
+

   friend class iterator;
   friend class const_iterator;
 
   friend class iterator;
   friend class const_iterator;
 


@@ -1345,12 +1353,13 @@ public:
   }
 #endif // wxUSE_STRING_POS_CACHE
 
   }
 #endif // wxUSE_STRING_POS_CACHE
 

-  // even if we're not built with wxUSE_STL == 1 it is very convenient to allow
-  // implicit conversions from std::string to wxString and vice verse as this
-  // allows to use the same strings in non-GUI and GUI code, however we don't
-  // want to unconditionally add this ctor as it would make wx lib dependent on
-  // libstdc++ on some Linux versions which is bad, so instead we ask the
-  // client code to define this wxUSE_STD_STRING symbol if they need it
+  // even if we're not built with wxUSE_STD_STRING_CONV_IN_WXSTRING == 1 it is
+  // very convenient to allow implicit conversions from std::string to wxString
+  // and vice verse as this allows to use the same strings in non-GUI and GUI
+  // code, however we don't want to unconditionally add this ctor as it would
+  // make wx lib dependent on libstdc++ on some Linux versions which is bad, so
+  // instead we ask the client code to define this wxUSE_STD_STRING symbol if
+  // they need it

 #if wxUSE_STD_STRING
   #if wxUSE_UNICODE_WCHAR
     wxString(const wxStdWideString& str) : m_impl(str) {}
 #if wxUSE_STD_STRING
   #if wxUSE_UNICODE_WCHAR
     wxString(const wxStdWideString& str) : m_impl(str) {}


@@ -1368,10 +1377,8 @@ public:
   #endif
 #endif // wxUSE_STD_STRING
 
   #endif
 #endif // wxUSE_STD_STRING
 

-  // Unlike ctor from std::string, we provide conversion to std::string only
-  // if wxUSE_STL and not merely wxUSE_STD_STRING (which is on by default),
-  // because it conflicts with operator const char/wchar_t* but we still
-  // provide explicit conversions to std::[w]string for convenience in any case
+  // Also always provide explicit conversions to std::[w]string in any case,
+  // see below for the implicit ones.

 #if wxUSE_STD_STRING
   // We can avoid a copy if we already use this string type internally,
   // otherwise we create a copy on the fly:
 #if wxUSE_STD_STRING
   // We can avoid a copy if we already use this string type internally,
   // otherwise we create a copy on the fly:


@@ -1408,13 +1415,14 @@ public:
     }
   #endif
 
     }
   #endif
 

-#if wxUSE_STL
-  // In wxUSE_STL case we also provide implicit conversions as there is no
-  // ambiguity with the const char/wchar_t* ones as they are disabled in this
-  // build (for consistency with std::basic_string<>)
+#if wxUSE_STD_STRING_CONV_IN_WXSTRING
+    // Implicit conversions to std::[w]string are not provided by default as
+    // they conflict with the implicit conversions to "const char/wchar_t *"
+    // which we use for backwards compatibility but do provide them if
+    // explicitly requested.

   operator wxStringToStdStringRetType() const { return ToStdString(); }
   operator wxStringToStdWstringRetType() const { return ToStdWstring(); }
   operator wxStringToStdStringRetType() const { return ToStdString(); }
   operator wxStringToStdWstringRetType() const { return ToStdWstring(); }

-#endif // wxUSE_STL
+#endif // wxUSE_STD_STRING_CONV_IN_WXSTRING

 
 #undef wxStringToStdStringRetType
 #undef wxStringToStdWstringRetType
 
 #undef wxStringToStdStringRetType
 #undef wxStringToStdWstringRetType


@@ -1654,11 +1662,12 @@ public:
     operator wxCStrData() const { return c_str(); }
 
     // the first two operators conflict with operators for conversion to
     operator wxCStrData() const { return c_str(); }
 
     // the first two operators conflict with operators for conversion to

-    // std::string and they must be disabled in STL build; the next one only
-    // makes sense if conversions to char* are also defined and not defining it
-    // in STL build also helps us to get more clear error messages for the code
-    // which relies on implicit conversion to char* in STL build
-#if !wxUSE_STL
+    // std::string and they must be disabled if those conversions are enabled;
+    // the next one only makes sense if conversions to char* are also defined
+    // and not defining it in STL build also helps us to get more clear error
+    // messages for the code which relies on implicit conversion to char* in
+    // STL build
+#if !wxUSE_STD_STRING_CONV_IN_WXSTRING

     operator const char*() const { return c_str(); }
     operator const wchar_t*() const { return c_str(); }
 
     operator const char*() const { return c_str(); }
     operator const wchar_t*() const { return c_str(); }
 


@@ -1666,7 +1675,7 @@ public:
     // wxWidgets versions: this is the same as conversion to const char * so it
     // may fail!
     operator const void*() const { return c_str(); }
     // wxWidgets versions: this is the same as conversion to const char * so it
     // may fail!
     operator const void*() const { return c_str(); }

-#endif // wxUSE_STL
+#endif // !wxUSE_STD_STRING_CONV_IN_WXSTRING

 
     // identical to c_str(), for MFC compatibility
     const wxCStrData GetData() const { return c_str(); }
 
     // identical to c_str(), for MFC compatibility
     const wxCStrData GetData() const { return c_str(); }


@@ -2121,7 +2130,7 @@ public:
       // insert an unsigned long into string
   wxString& operator<<(unsigned long ul)
     { return (*this) << Format(wxT("%lu"), ul); }
       // insert an unsigned long into string
   wxString& operator<<(unsigned long ul)
     { return (*this) << Format(wxT("%lu"), ul); }

-#if defined wxLongLong_t && !defined wxLongLongIsLong
+#ifdef wxHAS_LONG_LONG_T_DIFFERENT_FROM_LONG

       // insert a long long if they exist and aren't longs
   wxString& operator<<(wxLongLong_t ll)
     {
       // insert a long long if they exist and aren't longs
   wxString& operator<<(wxLongLong_t ll)
     {


@@ -2132,7 +2141,7 @@ public:
     {
       return (*this) << Format("%" wxLongLongFmtSpec "u" , ull);
     }
     {
       return (*this) << Format("%" wxLongLongFmtSpec "u" , ull);
     }

-#endif // wxLongLong_t && !wxLongLongIsLong
+#endif // wxHAS_LONG_LONG_T_DIFFERENT_FROM_LONG

       // insert a float into string
   wxString& operator<<(float f)
     { return (*this) << Format(wxT("%f"), f); }
       // insert a float into string
   wxString& operator<<(float f)
     { return (*this) << Format(wxT("%f"), f); }


@@ -2326,12 +2335,12 @@ public:
       // convert to a double
   bool ToCDouble(double *val) const;
 
       // convert to a double
   bool ToCDouble(double *val) const;
 

-  // create a string representing the given floating point number
+  // create a string representing the given floating point number with the
+  // default (like %g) or fixed (if precision >=0) precision

     // in the current locale
     // in the current locale

-  static wxString FromDouble(double val)
-    { return wxString::Format(wxS("%g"), val); }
+  static wxString FromDouble(double val, int precision = -1);

     // in C locale
     // in C locale

-  static wxString FromCDouble(double val);
+  static wxString FromCDouble(double val, int precision = -1);

 
 #ifndef wxNEEDS_WXSTRING_PRINTF_MIXIN
   // formatted input/output
 
 #ifndef wxNEEDS_WXSTRING_PRINTF_MIXIN
   // formatted input/output


@@ -2615,9 +2624,21 @@ public:
       return *this;
   }
 
       return *this;
   }
 

+    // This is a non-standard-compliant overload taking the first "len"
+    // characters of the source string.

   wxString& assign(const wxString& str, size_t len)
   {
   wxString& assign(const wxString& str, size_t len)
   {

+#if wxUSE_STRING_POS_CACHE
+      // It is legal to pass len > str.length() to wxStringImpl::assign() but
+      // by restricting it here we save some work for that function so it's not
+      // really less efficient and, at the same time, ensure that we don't
+      // cache invalid length.
+      const size_t lenSrc = str.length();
+      if ( len > lenSrc )
+          len = lenSrc;
+

       wxSTRING_SET_CACHED_LENGTH(len);
       wxSTRING_SET_CACHED_LENGTH(len);

+#endif // wxUSE_STRING_POS_CACHE

 
       m_impl.assign(str.m_impl, 0, str.LenToImpl(len));
 
 
       m_impl.assign(str.m_impl, 0, str.LenToImpl(len));
 


@@ -2659,7 +2680,7 @@ public:
 
   wxString& assign(const char *sz, size_t n)
   {
 
   wxString& assign(const char *sz, size_t n)
   {

-      wxSTRING_SET_CACHED_LENGTH(n);
+      wxSTRING_INVALIDATE_CACHE();

 
       SubstrBufFromMB str(ImplStr(sz, n));
       m_impl.assign(str.data, str.len);
 
       SubstrBufFromMB str(ImplStr(sz, n));
       m_impl.assign(str.data, str.len);


@@ -3475,7 +3496,7 @@ private:
 
   void DoUngetWriteBuf(size_t nLen)
   {
 
   void DoUngetWriteBuf(size_t nLen)
   {

-      wxSTRING_SET_CACHED_LENGTH(nLen);
+      wxSTRING_INVALIDATE_CACHE();

 
       m_impl.DoUngetWriteBuf(nLen);
   }
 
       m_impl.DoUngetWriteBuf(nLen);
   }