]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/string.h
Correct names of parameters in wxAffineMatrix2D documentation.
[wxWidgets.git] / interface / wx / string.h
index 4952ca259a4f693eb3bd1a16f924a85422c1a364..93ff1cbee89fe22ca29491665960a80b3f59c8d5 100644 (file)
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxStringBuffer, wxString
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 
@@ -112,6 +112,26 @@ public:
     */
     wxString(const wxString& stringSrc);
 
+    /**
+       Construct a string consisting of @a nRepeat copies of ch.
+    */
+    wxString(wxUniChar ch, size_t nRepeat = 1);
+
+    /**
+       Construct a string consisting of @a nRepeat copies of ch.
+    */
+    wxString(wxUniCharRef ch, size_t nRepeat = 1);
+
+    /**
+       Construct a string consisting of @a nRepeat copies of ch
+       converted to Unicode using the current locale encoding.
+    */
+    wxString(char ch, size_t nRepeat = 1);
+
+    /**
+       Construct a string consisting of @a nRepeat copies of ch.
+    */
+    wxString(wchar_t ch, size_t nRepeat = 1);
 
     /**
        Constructs a string from the string literal @a psz using
@@ -161,11 +181,15 @@ public:
     /**
        Constructs a string from @a str using the using the current locale encoding
        to convert it to Unicode (wxConvLibc).
+
+       @see ToStdString()
     */
     wxString(const std::string& str);
 
     /**
        Constructs a string from @a str.
+
+       @see ToStdWstring()
     */
     wxString(const std::wstring& str);
 
@@ -300,7 +324,7 @@ public:
     void SetChar(size_t n, wxUniChar ch);
 
     /**
-        Returns the last character.
+        Returns the last character.
 
         This is a wxWidgets 1.xx compatibility function;
         you should not use it in new code.
@@ -423,7 +447,7 @@ public:
     const wxScopedCharBuffer utf8_str() const;
 
     /**
-        Converts the strings contents to the wide character represention
+        Converts the strings contents to the wide character representation
         and returns it as a temporary wxWCharBuffer object (Unix and OS X)
         or returns a pointer to the internal string contents in wide character
         mode (Windows).
@@ -468,12 +492,7 @@ public:
 
         @see wxString::From8BitData()
     */
-    const char* To8BitData() const;
-
-    /**
-        @overload
-    */
-    const wxCharBuffer To8BitData() const;
+    const wxScopedCharBuffer To8BitData() const;
 
     /**
         Converts the string to an ASCII, 7-bit string in the form of
@@ -489,6 +508,36 @@ public:
     */
     const wxCharBuffer ToAscii() const;
 
+    /**
+        Return the string as an std::string in current locale encoding.
+
+        Note that if the conversion of (Unicode) string contents to the current
+        locale fails, the return string will be empty. Be sure to check for
+        this to avoid silent data loss.
+
+        Instead of using this function it's also possible to write
+        @code
+        std::string s;
+        wxString wxs;
+        ...
+        s = std::string(wxs);
+        @endcode
+        but using ToStdString() may make the code more clear.
+
+        @since 2.9.1
+    */
+    std::string ToStdString() const;
+
+    /**
+        Return the string as an std::wstring.
+
+        Unlike ToStdString(), there is no danger of data loss when using this
+        function.
+
+        @since 2.9.1
+    */
+    std::wstring ToStdWstring() const;
+
     /**
         Same as utf8_str().
     */
@@ -564,6 +613,7 @@ public:
     wxString& operator<<(wchar_t ch);
     wxString& operator<<(const wxCharBuffer& s);
     wxString& operator<<(const wxWCharBuffer& s);
+    wxString& operator<<(wxUniChar ch);
     wxString& operator<<(wxUniCharRef ch);
     wxString& operator<<(unsigned int ui);
     wxString& operator<<(long l);
@@ -733,14 +783,32 @@ public:
     /**
         Gets all characters before the first occurrence of @e ch.
         Returns the whole string if @a ch is not found.
+
+        @param ch The character to look for.
+        @param rest Filled with the part of the string following the first
+            occurrence of @a ch or cleared if it was not found. The same string
+            is returned by AfterFirst() but it is more efficient to use this
+            output parameter if both the "before" and "after" parts are needed
+            than calling both functions one after the other. This parameter is
+            available in wxWidgets version 2.9.2 and later only.
+        @return Part of the string before the first occurrence of @a ch.
     */
-    wxString BeforeFirst(wxUniChar ch) const;
+    wxString BeforeFirst(wxUniChar ch, wxString *rest = NULL) const;
 
     /**
         Gets all characters before the last occurrence of @e ch.
         Returns the empty string if @a ch is not found.
+
+        @param ch The character to look for.
+        @param rest Filled with the part of the string following the last
+            occurrence of @a ch or the copy of this string if it was not found.
+            The same string is returned by AfterLast() but it is more efficient
+            to use this output parameter if both the "before" and "after" parts
+            are needed than calling both functions one after the other. This
+            parameter is available in wxWidgets version 2.9.2 and later only.
+        @return Part of the string before the last occurrence of @a ch.
     */
-    wxString BeforeLast(wxUniChar ch) const;
+    wxString BeforeLast(wxUniChar ch, wxString *rest = NULL) const;
 
     //@}
 
@@ -907,8 +975,13 @@ public:
         you are sure that this string contains a floating point number formatted with
         the rules of the locale currently in use (see wxLocale).
 
-        Refer to the docs of the standard function @c strtod() for more details about
-        the supported syntax.
+        Also notice that even this function is locale-specific it does not
+        support strings with thousands separators in them, even if the current
+        locale uses digits grouping. You may use wxNumberFormatter::FromString()
+        to parse such strings.
+
+        Please refer to the documentation of the standard function @c strtod()
+        for more details about the supported syntax.
 
         @see ToCDouble(), ToLong(), ToULong()
     */
@@ -947,8 +1020,12 @@ public:
         that this string contains an integer number formatted with
         the rules of the locale currently in use (see wxLocale).
 
-        Refer to the docs of the standard function @c strtol() for more details about
-        the supported syntax.
+        As with ToDouble(), this function does not support strings containing
+        thousands separators even if the current locale uses digits grouping.
+        You may use wxNumberFormatter::FromString() to parse such strings.
+
+        Please refer to the documentation of the standard function @c strtol()
+        for more details about the supported syntax.
 
         @see ToCDouble(), ToDouble(), ToULong()
     */
@@ -1033,6 +1110,16 @@ public:
         Note that if @c wxUSE_PRINTF_POS_PARAMS is set to 1, then this function supports
         Unix98-style positional parameters:
 
+        @code
+        wxString str;
+
+        str.Printf(wxT("%d %d %d"), 1, 2, 3);
+        // str now contains "1 2 3"
+
+        str.Printf(wxT("%2$d %3$d %1$d"), 1, 2, 3);
+        // str now contains "2 3 1"
+        @endcode
+
         @note This function will use a safe version of @e vsprintf() (usually called
         @e vsnprintf()) whenever available to always allocate the buffer of correct
         size. Unfortunately, this function is not available on all platforms and the
@@ -1239,7 +1326,7 @@ public:
     /**
         @member_group_name{iter, Iterator interface}
 
-        These methods return iterators to the beginnnig or end of the string.
+        These methods return iterators to the beginning or end of the string.
 
         Please see any STL reference (e.g. http://www.cppreference.com/wiki/string/start)
         for their documentation.
@@ -1386,7 +1473,7 @@ public:
 
 
     // STATIC FUNCTIONS
-    // Keep these functions separed from the other groups or Doxygen gets confused
+    // Keep these functions separated from the other groups or Doxygen gets confused
     // -----------------------------------------------------------------------------
 
     /**
@@ -1442,6 +1529,44 @@ public:
     static wxString FromAscii(char c);
     //@}
 
+    /**
+        Returns a string with the textual representation of the number in C
+        locale.
+
+        Unlike FromDouble() the string returned by this function always uses
+        the period character as decimal separator, independently of the current
+        locale. Otherwise its behaviour is identical to the other function.
+
+        @since 2.9.1
+
+        @see ToCDouble()
+     */
+    static wxString FromCDouble(double val, int precision = -1);
+
+    /**
+        Returns a string with the textual representation of the number.
+
+        For the default value of @a precision, this function behaves as a
+        simple wrapper for @code wxString::Format("%g", val) @endcode. If @a
+        precision is positive (or zero), the @c %.Nf format is used with the
+        given precision value.
+
+        Notice that the string returned by this function uses the decimal
+        separator appropriate for the current locale, e.g. @c "," and not a
+        period in French locale. Use FromCDouble() if this is unwanted.
+
+        @param val
+            The value to format.
+        @param precision
+            The number of fractional digits to use in or -1 to use the most
+            appropriate format. This parameter is new in wxWidgets 2.9.2.
+
+        @since 2.9.1
+
+        @see ToDouble()
+     */
+    static wxString FromDouble(double val, int precision = -1);
+
     //@{
     /**
         Converts C string encoded in UTF-8 to wxString.