X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/69d31e313035d5e22d9400ec946f6007f710910c..15fa4de377053c3c38f62593b2df941c217ea34b:/interface/wx/string.h diff --git a/interface/wx/string.h b/interface/wx/string.h index 4952ca259a..93ff1cbee8 100644 --- a/interface/wx/string.h +++ b/interface/wx/string.h @@ -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 a 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.