add a comment about wxNativeFontInfo::SetFaceName return value

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

diff --git a/include/wx/string.h b/include/wx/string.h
index bdba1d23cf181b289c79e4752c501a8d198a9a7b..ec66dce85c61d59510dd176e800b1d5a3434ec04 100644 (file)
--- a/include/wx/string.h
+++ b/include/wx/string.h
@@ -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;
@@ -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