]> git.saurik.com Git - wxWidgets.git/blobdiff - include/wx/string.h
add a comment about wxNativeFontInfo::SetFaceName return value
[wxWidgets.git] / include / wx / string.h
index 22e0ec6f5ed19560e82abd04b1a09edd7c0c6e65..ec66dce85c61d59510dd176e800b1d5a3434ec04 100644 (file)
@@ -262,9 +262,11 @@ public:
     wxUniChar operator[](unsigned int n) const { return operator[](size_t(n)); }
 #endif // size_t != unsigned int
 
-    // these operators are needed to emulate the pointer semantics of c_str():
+    // These operators are needed to emulate the pointer semantics of c_str():
     // expressions like "wxChar *p = str.c_str() + 1;" should continue to work
-    // (we need both versions to resolve ambiguities):
+    // (we need both versions to resolve ambiguities). Note that this means
+    // the 'n' value is interpreted as addition to char*/wchar_t* pointer, it
+    // is *not* number of Unicode characters in wxString.
     wxCStrData operator+(int n) const
         { return wxCStrData(m_str, m_offset + n, m_owned); }
     wxCStrData operator+(long n) const
@@ -287,8 +289,16 @@ public:
     inline wxUniChar operator*() const;
 
 private:
+    // the wxString this object was returned for
     const wxString *m_str;
+    // Offset into c_str() return value. Note that this is *not* offset in
+    // m_str in Unicode characters. Instead, it is index into the
+    // char*/wchar_t* buffer returned by c_str(). It's interpretation depends
+    // on how is the wxCStrData instance used: if it is eventually cast to
+    // const char*, m_offset will be in bytes form string's start; if it is
+    // cast to const wchar_t*, it will be in wchar_t values.
     size_t m_offset;
+    // should m_str be deleted, i.e. is it owned by us?
     bool m_owned;
 
     friend class WXDLLIMPEXP_FWD_BASE wxString;
@@ -350,7 +360,7 @@ public:
     // these are duplicated wxString methods, they're also declared below
     // if !wxNEEDS_WXSTRING_PRINTF_MIXIN:
 
-    // static wxString Format(const wString& format, ...) ATTRIBUTE_PRINTF_1;
+    // static wxString Format(const wString& format, ...) WX_ATTRIBUTE_PRINTF_1;
     WX_DEFINE_VARARG_FUNC_SANS_N0(static typename StringReturnType<T1>::type,
                                   Format, 1, (const wxFormatString&),
                                   DoFormatWchar, DoFormatUtf8)
@@ -372,7 +382,7 @@ public:
     // int Printf(const wxString& format, ...);
     WX_DEFINE_VARARG_FUNC(int, Printf, 1, (const wxFormatString&),
                           DoPrintfWchar, DoPrintfUtf8)
-    // int sprintf(const wxString& format, ...) ATTRIBUTE_PRINTF_2;
+    // int sprintf(const wxString& format, ...) WX_ATTRIBUTE_PRINTF_2;
     WX_DEFINE_VARARG_FUNC(int, sprintf, 1, (const wxFormatString&),
                           DoPrintfWchar, DoPrintfUtf8)
 
@@ -426,7 +436,7 @@ private:
 
     // the node belongs to a particular iterator instance, it's not copied
     // when a copy of the iterator is made
-    DECLARE_NO_COPY_CLASS(wxStringIteratorNode)
+    wxDECLARE_NO_COPY_CLASS(wxStringIteratorNode);
 };
 #endif // wxUSE_UNICODE_UTF8
 
@@ -2202,25 +2212,34 @@ public:
     // check if the string contents matches a mask containing '*' and '?'
   bool Matches(const wxString& mask) const;
 
-    // conversion to numbers: all functions return true only if the whole
-    // string is a number and put the value of this number into the pointer
-    // provided, the base is the numeric base in which the conversion should be
-    // done and must be comprised between 2 and 36 or be 0 in which case the
-    // standard C rules apply (leading '0' => octal, "0x" => hex)
-        // convert to a signed integer
-    bool ToLong(long *val, int base = 10) const;
-        // convert to an unsigned integer
-    bool ToULong(unsigned long *val, int base = 10) const;
-        // convert to wxLongLong
+  // conversion to numbers: all functions return true only if the whole
+  // string is a number and put the value of this number into the pointer
+  // provided, the base is the numeric base in which the conversion should be
+  // done and must be comprised between 2 and 36 or be 0 in which case the
+  // standard C rules apply (leading '0' => octal, "0x" => hex)
+      // convert to a signed integer
+  bool ToLong(long *val, int base = 10) const;
+      // convert to an unsigned integer
+  bool ToULong(unsigned long *val, int base = 10) const;
+      // convert to wxLongLong
 #if defined(wxLongLong_t)
-    bool ToLongLong(wxLongLong_t *val, int base = 10) const;
-        // convert to wxULongLong
-    bool ToULongLong(wxULongLong_t *val, int base = 10) const;
+  bool ToLongLong(wxLongLong_t *val, int base = 10) const;
+      // convert to wxULongLong
+  bool ToULongLong(wxULongLong_t *val, int base = 10) const;
 #endif // wxLongLong_t
-        // convert to a double
-    bool ToDouble(double *val) const;
-
-
+      // convert to a double
+  bool ToDouble(double *val) const;
+
+#if wxUSE_XLOCALE
+  // conversions to numbers using C locale
+      // convert to a signed integer
+  bool ToCLong(long *val, int base = 10) const;
+      // convert to an unsigned integer
+  bool ToCULong(unsigned long *val, int base = 10) const;
+      // convert to a double
+  bool ToCDouble(double *val) const;
+#endif
+  
 #ifndef wxNEEDS_WXSTRING_PRINTF_MIXIN
   // formatted input/output
     // as sprintf(), returns the number of characters written or < 0 on error
@@ -2245,7 +2264,7 @@ public:
 
 #ifndef wxNEEDS_WXSTRING_PRINTF_MIXIN
     // returns the string containing the result of Printf() to it
-  // static wxString Format(const wxString& format, ...) ATTRIBUTE_PRINTF_1;
+  // static wxString Format(const wxString& format, ...) WX_ATTRIBUTE_PRINTF_1;
   WX_DEFINE_VARARG_FUNC(static wxString, Format, 1, (const wxFormatString&),
                         DoFormatWchar, DoFormatUtf8)
 #ifdef __WATCOMC__
@@ -2294,7 +2313,7 @@ public:
 #ifndef wxNEEDS_WXSTRING_PRINTF_MIXIN
   // use Printf()
   // (take 'this' into account in attribute parameter count)
-  // int sprintf(const wxString& format, ...) ATTRIBUTE_PRINTF_2;
+  // int sprintf(const wxString& format, ...) WX_ATTRIBUTE_PRINTF_2;
   WX_DEFINE_VARARG_FUNC(int, sprintf, 1, (const wxFormatString&),
                         DoPrintfWchar, DoPrintfUtf8)
 #ifdef __WATCOMC__
@@ -3428,7 +3447,7 @@ private:
 
       // copying is disallowed as it would result in more than one pointer into
       // the same linked list
-      DECLARE_NO_COPY_CLASS(wxStringIteratorNodeHead)
+      wxDECLARE_NO_COPY_CLASS(wxStringIteratorNodeHead);
   };
 
   wxStringIteratorNodeHead m_iterators;
@@ -3571,7 +3590,7 @@ private:
     wxString&         m_str;
     wxStringCharType *m_buf;
 
-    DECLARE_NO_COPY_CLASS(wxStringInternalBuffer)
+    wxDECLARE_NO_COPY_CLASS(wxStringInternalBuffer);
 };
 
 class wxStringInternalBufferLength
@@ -3601,7 +3620,7 @@ private:
     size_t            m_len;
     bool              m_lenSet;
 
-    DECLARE_NO_COPY_CLASS(wxStringInternalBufferLength)
+    wxDECLARE_NO_COPY_CLASS(wxStringInternalBufferLength);
 };
 
 #endif // !wxUSE_STL_BASED_WXSTRING
@@ -3681,7 +3700,7 @@ public:
         this->m_str.assign(this->m_buf.data());
     }
 
-    DECLARE_NO_COPY_CLASS(wxStringTypeBuffer)
+    wxDECLARE_NO_COPY_CLASS(wxStringTypeBuffer);
 };
 
 template<typename T>
@@ -3697,7 +3716,7 @@ public:
         this->m_str.assign(this->m_buf.data(), this->m_len);
     }
 
-    DECLARE_NO_COPY_CLASS(wxStringTypeBufferLength)
+    wxDECLARE_NO_COPY_CLASS(wxStringTypeBufferLength);
 };
 
 #if wxUSE_STL_BASED_WXSTRING
@@ -3712,7 +3731,7 @@ public:
     ~wxStringInternalBuffer()
         { m_str.m_impl.assign(m_buf.data()); }
 
-    DECLARE_NO_COPY_CLASS(wxStringInternalBuffer)
+    wxDECLARE_NO_COPY_CLASS(wxStringInternalBuffer);
 };
 
 WXDLLIMPEXP_TEMPLATE_INSTANCE_BASE(
@@ -3730,7 +3749,7 @@ public:
         m_str.m_impl.assign(m_buf.data(), m_len);
     }
 
-    DECLARE_NO_COPY_CLASS(wxStringInternalBufferLength)
+    wxDECLARE_NO_COPY_CLASS(wxStringInternalBufferLength);
 };
 
 #endif // wxUSE_STL_BASED_WXSTRING
@@ -3780,7 +3799,7 @@ public:
         conv.ToWChar(wbuf, wlen, m_buf);
     }
 
-    DECLARE_NO_COPY_CLASS(wxUTF8StringBuffer)
+    wxDECLARE_NO_COPY_CLASS(wxUTF8StringBuffer);
 };
 
 WXDLLIMPEXP_TEMPLATE_INSTANCE_BASE( wxStringTypeBufferLengthBase<char> )
@@ -3803,7 +3822,7 @@ public:
         wbuf.SetLength(wlen);
     }
 
-    DECLARE_NO_COPY_CLASS(wxUTF8StringBufferLength)
+    wxDECLARE_NO_COPY_CLASS(wxUTF8StringBufferLength);
 };
 #endif // wxUSE_UNICODE_UTF8/wxUSE_UNICODE_WCHAR