+ //@}
+
+
+ /**
+ @member_group_name{conv, Conversions}
+
+ This section contains both implicit and explicit conversions to C style
+ strings. Although implicit conversion is quite convenient, you are advised
+ to use wc_str() for the sake of clarity.
+ */
+ //@{
+
+ /**
+ Returns a lightweight intermediate class which is in turn implicitly
+ convertible to both @c const @c char* and to @c const @c wchar_t*.
+ Given this ambiguity it is mostly better to use wc_str(), mb_str() or
+ utf8_str() instead.
+
+ Please see the @ref overview_unicode for more information about it.
+
+ Note that the returned value is not convertible to @c char* or
+ @c wchar_t*, use char_str() or wchar_str() if you need to pass
+ string value to a function expecting non-const pointer.
+
+ @see wc_str(), utf8_str(), c_str(), mb_str(), fn_str()
+ */
+ wxCStrData c_str() const;
+
+ /**
+ Returns an object with string data that is implicitly convertible to
+ @c char* pointer. Note that any change to the returned buffer is lost and so
+ this function is only usable for passing strings to legacy libraries that
+ don't have const-correct API. Use wxStringBuffer if you want to modify
+ the string.
+
+ @see c_str()
+ */
+ wxWritableCharBuffer char_str(const wxMBConv& conv = wxConvLibc) const;
+
+ /**
+ Returns buffer of the specified type containing the string data.
+
+ This method is only useful in template code, otherwise you should
+ directly call mb_str() or wc_str() if you need to retrieve a narrow or
+ wide string from this wxString. The template parameter @a t should be
+ either @c char or @c wchar_t.
+
+ Notice that retrieving a char buffer in UTF-8 build will return the
+ internal string representation in UTF-8 while in wchar_t build the char
+ buffer will contain the conversion of the string to the encoding of the
+ current locale (and so can fail).
+
+ @param len
+ If non-@NULL, filled with the length of the returned buffer.
+
+ @return
+ buffer containing the string contents in the specified type,
+ notice that it may be @NULL if the conversion failed (e.g. Unicode
+ string couldn't be converted to the current encoding when @a T is
+ @c char).
+ */
+ template <typename T>
+ wxCharTypeBuffer<T> tchar_str(size_t *len = NULL) const;
+
+ /**
+ Returns a string representation suitable for passing to OS' functions
+ for file handling.
+ */
+ const wchar_t* fn_str() const;
+
+ /**
+ @overload
+ */
+ const char* fn_str() const;
+
+ /**
+ @overload
+ */
+ const wxCharBuffer fn_str() const;
+
+ /**
+ Returns the multibyte (C string) representation of the string
+ using @e conv's wxMBConv::cWC2MB method and returns wxCharBuffer.
+
+ @see wc_str(), utf8_str(), c_str(), wxMBConv
+ */
+ const wxCharBuffer mb_str(const wxMBConv& conv = wxConvLibc) const;
+
+ /**
+ Converts the strings contents to UTF-8 and returns it either as a
+ temporary wxCharBuffer object or as a pointer to the internal
+ string contents in UTF-8 build.
+
+ @see wc_str(), c_str(), mb_str()
+ */
+ const wxScopedCharBuffer utf8_str() const;
+
+ /**
+ Converts the strings contents to the wide character represention
+ 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).
+
+ The macro wxWX2WCbuf is defined as the correct return type (without const).
+
+ @see utf8_str(), c_str(), mb_str(), fn_str(), wchar_str()
+ */
+ const wchar_t* wc_str() const;
+
+ /**
+ @overload
+ */
+ const wxWCharBuffer wc_str() const;
+
+ /**
+ Returns an object with string data that is implicitly convertible to
+ @c char* pointer. Note that changes to the returned buffer may or may
+ not be lost (depending on the build) and so this function is only usable for
+ passing strings to legacy libraries that don't have const-correct API. Use
+ wxStringBuffer if you want to modify the string.
+
+ @see mb_str(), wc_str(), fn_str(), c_str(), char_str()
+ */
+ wxWritableWCharBuffer wchar_str() const;
+
+ /**
+ Explicit conversion to C string in the internal representation (either
+ wchar_t* or UTF-8-encoded char*, depending on the build).
+ */
+ const wxStringCharType *wx_str() const;
+
+ /**
+ Converts the string to an 8-bit string in ISO-8859-1 encoding in the
+ form of a wxCharBuffer (Unicode builds only).
+
+ This is a convenience method useful when storing binary data in
+ wxString. It should be used @em only for this purpose. It is only valid
+ to call this method on strings created using From8BitData().
+
+ @since 2.8.4
+
+ @see wxString::From8BitData()
+ */
+ const wxScopedCharBuffer To8BitData() const;
+
+ /**
+ Converts the string to an ASCII, 7-bit string in the form of
+ a wxCharBuffer (Unicode builds only) or a C string (ANSI builds).
+ Note that this conversion only works if the string contains only ASCII
+ characters. The @ref mb_str() "mb_str" method provides more
+ powerful means of converting wxString to C string.
+ */
+ const char* ToAscii() const;
+
+ /**
+ @overload
+ */
+ 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().
+ */
+ const wxScopedCharBuffer ToUTF8() const;
+
+ //@}
+
+
+ /**
+ @member_group_name{concat, Concatenation}
+
+ Almost anything may be concatenated (appended to) with a string!
+
+ Note that the various operator<<() overloads work as C++ stream insertion
+ operators. They insert the given value into the string.
+ Precision and format cannot be set using them. Use Printf() instead.
+
+ See also the insert() and append() STL-like functions.
+ */
+ //@{
+
+ /**
+ Appends the string literal @a psz.
+ */
+ wxString& Append(const char* psz);
+
+ /**
+ Appends the wide string literal @a pwz.
+ */
+ wxString& Append(const wchar_t* pwz);
+
+ /**
+ Appends the string literal @a psz with max length @a nLen.
+ */
+ wxString& Append(const char* psz, size_t nLen);
+
+ /**
+ Appends the wide string literal @a psz with max length @a nLen.
+ */
+ wxString& Append(const wchar_t* pwz, size_t nLen);
+
+ /**
+ Appends the string @a s.
+ */
+ wxString& Append(const wxString& s);
+
+ /**
+ Appends the character @a ch @a count times.
+ */
+ wxString &Append(wxUniChar ch, size_t count = 1u);
+
+ /**
+ Prepends @a str to this string, returning a reference to this string.
+ */
+ wxString& Prepend(const wxString& str);
+
+ /**
+ Concatenation: returns a new string equal to the concatenation of the operands.
+ */
+ wxString operator +(const wxString& x, const wxString& y);
+
+ /**
+ @overload
+ */
+ wxString operator +(const wxString& x, wxUniChar y);
+
+ wxString& operator<<(const wxString& s);
+ wxString& operator<<(const char* psz);
+ wxString& operator<<(const wchar_t* pwz);
+ wxString& operator<<(const wxCStrData& psz);
+ wxString& operator<<(char ch);
+ wxString& operator<<(unsigned char ch);
+ 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);
+ wxString& operator<<(unsigned long ul);
+ wxString& operator<<(wxLongLong_t ll);
+ wxString& operator<<(wxULongLong_t ul);
+ wxString& operator<<(float f);
+ wxString& operator<<(double d);
+
+ /**
+ Concatenation in place: the argument is appended to the string.
+ */
+ void operator +=(const wxString& str);
+
+ /**
+ @overload
+ */
+ void operator +=(wxUniChar c);
+
+ //@}
+
+
+ /**
+ @member_group_name{cmp, Comparison}
+
+ The default comparison function Cmp() is case-sensitive and so is the default
+ version of IsSameAs(). For case insensitive comparisons you should use CmpNoCase()
+ or give a second parameter to IsSameAs(). This last function is maybe more
+ convenient if only equality of the strings matters because it returns a boolean
+ @true value if the strings are the same and not 0 (which is usually @false
+ in C) as Cmp() does.
+
+ Matches() is a poor man's regular expression matcher: it only understands
+ '*' and '?' metacharacters in the sense of DOS command line interpreter.
+
+ StartsWith() is helpful when parsing a line of text which should start
+ with some predefined prefix and is more efficient than doing direct string
+ comparison as you would also have to precalculate the length of the prefix.
+
+ See also the compare() STL-like function.
+ */
+ //@{
+
+ /**
+ Case-sensitive comparison.
+ Returns a positive value if the string is greater than the argument,
+ zero if it is equal to it or a negative value if it is less than the
+ argument (same semantics as the standard @c strcmp() function).
+
+ @see CmpNoCase(), IsSameAs().
+ */
+ int Cmp(const wxString& s) const;
+
+ /**
+ Case-insensitive comparison.
+ Returns a positive value if the string is greater than the argument,
+ zero if it is equal to it or a negative value if it is less than the
+ argument (same semantics as the standard @c strcmp() function).
+
+ @see Cmp(), IsSameAs().
+ */
+ int CmpNoCase(const wxString& s) const;
+
+ /**
+ Test whether the string is equal to another string @a s.
+
+ The test is case-sensitive if @a caseSensitive is @true (default) or not if it is
+ @false.
+
+ @return @true if the string is equal to the other one, @false otherwise.
+
+ @see Cmp(), CmpNoCase()
+ */
+ bool IsSameAs(const wxString& s, bool caseSensitive = true) const;
+
+ /**
+ Test whether the string is equal to the single character @a ch.
+
+ The test is case-sensitive if @a caseSensitive is @true (default) or not if it is
+ @false.
+
+ @return @true if the string is equal to this character, @false otherwise.
+
+ @see Cmp(), CmpNoCase()
+ */
+ bool IsSameAs(wxUniChar ch, bool caseSensitive = true) const;
+
+ /**
+ Returns @true if the string contents matches a mask containing '*' and '?'.
+ */
+ bool Matches(const wxString& mask) const;
+
+ /**
+ This function can be used to test if the string starts with the specified
+ @a prefix.
+
+ If it does, the function will return @true and put the rest of the string
+ (i.e. after the prefix) into @a rest string if it is not @NULL.
+ Otherwise, the function returns @false and doesn't modify the @a rest.
+ */
+ bool StartsWith(const wxString& prefix, wxString *rest = NULL) const;
+
+ /**
projects / wxWidgets.git / blobdiff