X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4cc4bfafe5a31cb96f35b3ec9b19fa2b0b3a4eef..f9d6e4e454ac06b3303c71081b289152c8867ec1:/interface/string.h diff --git a/interface/string.h b/interface/string.h index 11639efeca..c44f1a059c 100644 --- a/interface/string.h +++ b/interface/string.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: string.h -// Purpose: documentation for wxStringBuffer class +// Purpose: interface of wxStringBuffer // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -67,6 +67,7 @@ public: }; + /** @class wxString @wxheader{string.h} @@ -94,11 +95,9 @@ public: @category{data} @stdobjects - Objects: - wxEmptyString + ::Objects:, ::wxEmptyString, - @seealso - @ref overview_wxstringoverview "wxString overview", @ref overview_unicode + @see @ref overview_wxstringoverview "wxString overview", @ref overview_unicode "Unicode overview" */ class wxString @@ -112,7 +111,7 @@ public: wxMBConv::MB2WC method is called to convert @a psz to wide string (the default converter uses current locale's charset). It is ignored in ANSI build. - + @see @ref overview_mbconvclasses "wxMBConv classes", @ref mbstr() mb_str, @ref wcstr() wc_str */ @@ -138,27 +137,52 @@ public: Gets all the characters after the first occurrence of @e ch. Returns the empty string if @a ch is not found. */ - wxString AfterFirst(wxChar ch); + wxString AfterFirst(wxChar ch) const; /** Gets all the characters after the last occurrence of @e ch. Returns the whole string if @a ch is not found. */ - wxString AfterLast(wxChar ch); + wxString AfterLast(wxChar ch) const; /** - Preallocate enough space for wxString to store @a nLen characters. This function - may be used to increase speed when the string is constructed by repeated - concatenation as in - - because it will avoid the need to reallocate string memory many times (in case - of long strings). Note that it does not set the maximal length of a string - it - will still expand if more than @a nLen characters are stored in it. Also, it - does not truncate the existing string (use - Truncate() for this) even if its current length is - greater than @e nLen + Preallocate enough space for wxString to store @a nLen characters. + + Please note that this method does the same thing as the standard + reserve() one and shouldn't be used in new code. + + This function may be used to increase speed when the string is + constructed by repeated concatenation as in + + @code + // delete all vowels from the string + wxString DeleteAllVowels(const wxString& original) + { + wxString result; + + size_t len = original.length(); + + result.Alloc(len); + + for ( size_t n = 0; n < len; n++ ) + { + if ( strchr("aeuio", tolower(original[n])) == NULL ) + result += original[n]; + } + + return result; + } + @endcode + + because it will avoid the need to reallocate string memory many times + (in case of long strings). Note that it does not set the maximal length + of a string -- it will still expand if more than @a nLen characters are + stored in it. Also, it does not truncate the existing string (use + Truncate() for this) even if its current length is greater than @a nLen. + + @return @true if memory was successfully allocated, @false otherwise. */ - void Alloc(size_t nLen); + bool Alloc(size_t nLen); //@{ /** @@ -174,24 +198,24 @@ public: Gets all characters before the first occurrence of @e ch. Returns the whole string if @a ch is not found. */ - wxString BeforeFirst(wxChar ch); + wxString BeforeFirst(wxChar ch) const; /** Gets all characters before the last occurrence of @e ch. Returns the empty string if @a ch is not found. */ - wxString BeforeLast(wxChar ch); + wxString BeforeLast(wxChar ch) const; /** The MakeXXX() variants modify the string in place, while the other functions return a new string which contains the original text converted to the upper or lower case and leave the original string unchanged. MakeUpper() - + Upper() - + MakeLower() - + Lower() */ @@ -207,26 +231,26 @@ public: This section also contains both implicit and explicit conversions to C style strings. Although implicit conversion is quite convenient, it is advised to use explicit @ref cstr() c_str method for the sake of clarity. Also - see overview for the cases where it is necessary to + see overview() for the cases where it is necessary to use it. GetChar() - + GetWritableChar() - + SetChar() - + Last() - + @ref operatorbracket() "operator []" - + @ref cstr() c_str - + @ref mbstr() mb_str - + @ref wcstr() wc_str - + @ref fnstr() fn_str - + @ref operatorconstcharpt() "operator const char*" */ @@ -246,8 +270,8 @@ public: as the standard @e strcmp() function). See also CmpNoCase(), IsSameAs(). */ - int Cmp(const wxString& s); - int Cmp(const wxChar* psz); + int Cmp(const wxString& s) const; + const int Cmp(const wxChar* psz) const; //@} //@{ @@ -259,15 +283,15 @@ public: as the standard @e strcmp() function). See also Cmp(), IsSameAs(). */ - int CmpNoCase(const wxString& s); - int CmpNoCase(const wxChar* psz); + int CmpNoCase(const wxString& s) const; + const int CmpNoCase(const wxChar* psz) const; //@} /** Case-sensitive comparison. Returns 0 if equal, 1 if greater or -1 if less. This is a wxWidgets 1.xx compatibility function; use Cmp() instead. */ - int CompareTo(const wxChar* psz, caseCompare cmp = exact); + int CompareTo(const wxChar* psz, caseCompare cmp = exact) const; /** The default comparison function Cmp() is case-sensitive and @@ -286,22 +310,22 @@ public: doing direct string comparison as you would also have to precalculate the length of the prefix then. Cmp() - + CmpNoCase() - + IsSameAs() - + Matches() - + StartsWith() - + EndsWith() */ //@{ /** - + */ bool operator ==(const wxString& x, const wxString& y); bool operator ==(const wxString& x, const wxChar* t); @@ -322,13 +346,13 @@ public: append something to a C string (including literal constants), so to do this it should be converted to a wxString first. @ref operatorout() "operator " - + @ref plusequal() "operator +=" - + @ref operatorplus() "operator +" - + Append() - + Prepend() */ @@ -339,9 +363,9 @@ public: default which creates an empty string) there is also a corresponding assignment operator. @ref construct() wxString - + @ref operatorassign() "operator =" - + @ref destruct() ~wxString */ @@ -351,7 +375,7 @@ public: This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ - bool Contains(const wxString& str); + bool Contains(const wxString& str) const; /** The string provides functions for conversion to signed and unsigned integer and @@ -359,13 +383,13 @@ public: put the numeric value in and return @true if the @b entire string could be converted to a number. ToLong() - + ToLongLong() - + ToULong() - + ToULongLong() - + ToDouble() */ @@ -383,15 +407,15 @@ public: @NULL. Otherwise, the function returns @false and doesn't modify the @e rest. */ - bool EndsWith(const wxString& suffix, wxString rest = NULL); + bool EndsWith(const wxString& suffix, wxString rest = NULL) const; //@{ /** Searches for the given string. Returns the starting index, or @c wxNOT_FOUND if not found. */ - int Find(wxUniChar ch, bool fromEnd = false); - int Find(const wxString& sub); + int Find(wxUniChar ch, bool fromEnd = false) const; + const int Find(const wxString& sub) const; //@} //@{ @@ -400,15 +424,15 @@ public: This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ - int First(wxChar c); - int First(const wxChar* psz); - int First(const wxString& str); + int First(wxChar c) const; + int First(const wxChar* psz) const; + const int First(const wxString& str) const; //@} /** This static function returns the string containing the result of calling Printf() with the passed parameters on it. - + @see FormatV(), Printf() */ static wxString Format(const wxChar format, ...); @@ -416,7 +440,7 @@ public: /** This static function returns the string containing the result of calling PrintfV() with the passed parameters on it. - + @see Format(), PrintfV() */ static wxString FormatV(const wxChar format, va_list argptr); @@ -426,7 +450,7 @@ public: This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ - int Freq(wxChar ch); + int Freq(wxChar ch) const; //@{ /** @@ -434,8 +458,9 @@ public: build, the string is interpreted as being in ISO-8859-1 encoding. The version without @a len parameter takes NUL-terminated data. This is a convenience method useful when storing binary data in wxString. - This function is new since wxWidgets version 2.8.4 - + + @wxsince{2.8.4} + @see wxString::To8BitData */ static wxString From8BitData(const char* buf, size_t len); @@ -471,13 +496,13 @@ public: /** Returns the character at position @a n (read-only). */ - wxChar GetChar(size_t n); + wxChar GetChar(size_t n) const; /** wxWidgets compatibility conversion. Returns a constant pointer to the data in the string. */ - const wxChar* GetData(); + const wxChar* GetData() const; /** Returns a reference to the character at position @e n. @@ -502,8 +527,8 @@ public: This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ - size_t Index(wxChar ch); - size_t Index(const wxChar* sz); + size_t Index(wxChar ch) const; + const size_t Index(const wxChar* sz) const; //@} /** @@ -511,26 +536,26 @@ public: This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ - bool IsAscii(); + bool IsAscii() const; /** Returns @true if the string is empty. */ - bool IsEmpty(); + bool IsEmpty() const; /** Returns @true if the string is empty (same as wxString::IsEmpty). This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ - bool IsNull(); + bool IsNull() const; /** Returns @true if the string is an integer (with possible sign). This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ - bool IsNumber(); + bool IsNumber() const; //@{ /** @@ -540,8 +565,8 @@ public: Returns @true if the string is equal to the character, @false otherwise. See also Cmp(), CmpNoCase() */ - bool IsSameAs(const wxChar* psz, bool caseSensitive = true); - bool IsSameAs(wxChar c, bool caseSensitive = true); + bool IsSameAs(const wxChar* psz, bool caseSensitive = true) const; + const bool IsSameAs(wxChar c, bool caseSensitive = true) const; //@} /** @@ -549,7 +574,7 @@ public: This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ - bool IsWord(); + bool IsWord() const; //@{ /** @@ -558,30 +583,30 @@ public: code. */ wxChar Last(); - wxChar Last(); + const wxChar Last(); //@} /** Returns the first @a count characters of the string. */ - wxString Left(size_t count); + wxString Left(size_t count) const; /** Returns the length of the string. */ - size_t Len(); + size_t Len() const; /** Returns the length of the string (same as Len). This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ - size_t Length(); + size_t Length() const; /** Returns this string converted to the lower case. */ - wxString Lower(); + wxString Lower() const; /** Same as MakeLower. @@ -603,7 +628,7 @@ public: /** Returns @true if the string contents matches a mask containing '*' and '?'. */ - bool Matches(const wxString& mask); + bool Matches(const wxString& mask) const; /** These are "advanced" functions and they will be needed quite rarely. @@ -614,11 +639,11 @@ public: useful when working with some external API which requires the caller to provide a writable buffer. Alloc() - + Shrink() - + wxStringBuffer - + wxStringBufferLength */ @@ -627,14 +652,14 @@ public: Returns a substring starting at @e first, with length @e count, or the rest of the string if @a count is the default value. */ - wxString Mid(size_t first, size_t count = wxSTRING_MAXLEN); + wxString Mid(size_t first, size_t count = wxSTRING_MAXLEN) const; /** Other string functions. Trim() - + Truncate() - + Pad() */ @@ -657,8 +682,8 @@ public: characters written, or an integer less than zero on error. Note that if @c wxUSE_PRINTF_POS_PARAMS is set to 1, then this function supports Unix98-style positional parameters: - - @b NB: This function will use a safe version of @e vsprintf() (usually called + + @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 dangerous @e vsprintf() will be used then which may lead to buffer overflows. @@ -698,13 +723,13 @@ public: /** Returns the last @a count characters. */ - wxString Right(size_t count); + wxString Right(size_t count) const; /** These functions replace the standard @e strchr() and @e strstr() functions. Find() - + Replace() */ @@ -727,19 +752,19 @@ public: @NULL. Otherwise, the function returns @false and doesn't modify the @e rest. */ - bool StartsWith(const wxString& prefix, wxString rest = NULL); + bool StartsWith(const wxString& prefix, wxString rest = NULL) const; /** These functions return the string length and check whether the string is empty or empty it. Len() - + IsEmpty() - + @ref operatornot() operator! - + Empty() - + Clear() */ @@ -750,7 +775,7 @@ public: This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ - wxString Strip(stripType s = trailing); + wxString Strip(stripType s = trailing) const; /** Returns the part of the string between the indices @a from and @e to @@ -758,30 +783,30 @@ public: This is a wxWidgets 1.xx compatibility function, use Mid() instead (but note that parameters have different meaning). */ - wxString SubString(size_t from, size_t to); + wxString SubString(size_t from, size_t to) const; /** These functions allow to extract substring from this string. All of them don't modify the original string and return a new string containing the extracted substring. Mid() - + @ref operatorparenth() operator - + Left() - + Right() - + BeforeFirst() - + BeforeLast() - + AfterFirst() - + AfterLast() - + StartsWith() - + EndsWith() */ @@ -791,12 +816,13 @@ public: 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. - This function is new since wxWidgets version 2.8.4 - + + @wxsince{2.8.4} + @see wxString::From8BitData */ - const char* To8BitData(); - const wxCharBuffer To8BitData(); + const char* To8BitData() const; + const const wxCharBuffer To8BitData() const; //@} //@{ @@ -807,8 +833,8 @@ public: characters. The @ref mbstr() mb_str method provides more powerful means of converting wxString to C string. */ - const char* ToAscii(); - const wxCharBuffer ToAscii(); + const char* ToAscii() const; + const const wxCharBuffer ToAscii() const; //@} /** @@ -816,10 +842,10 @@ public: success (the number is stored in the location pointed to by @e val) or @false if the string does not represent such number (the value of @a val is not modified in this case). - + @see ToLong(), ToULong() */ - bool ToDouble(double val); + bool ToDouble(double val) const; /** Attempts to convert the string to a signed integer in base @e base. Returns @@ -834,10 +860,10 @@ public: that you may not want to specify the base 0 if you are parsing the numbers which may have leading zeroes as they can yield unexpected (to the user not familiar with C) results. - + @see ToDouble(), ToULong() */ - bool ToLong(long val, int base = 10); + bool ToLong(long val, int base = 10) const; /** This is exactly the same as ToLong() but works with 64 @@ -845,10 +871,10 @@ public: Notice that currently it doesn't work (always returns @false) if parsing of 64 bit numbers is not supported by the underlying C run-time library. Compilers with C99 support and Microsoft Visual C++ version 7 and higher do support this. - + @see ToLong(), ToULongLong() */ - bool ToLongLong(wxLongLong_t val, int base = 10); + bool ToLongLong(wxLongLong_t val, int base = 10) const; /** Attempts to convert the string to an unsigned integer in base @e base. @@ -861,24 +887,24 @@ public: (e.g. -1 is returned as @c ULONG_MAX). See ToLong() for the more detailed description of the @a base parameter. - + @see ToDouble(), ToLong() */ - bool ToULong(unsigned long val, int base = 10); + bool ToULong(unsigned long val, int base = 10) const; /** This is exactly the same as ToULong() but works with 64 bit integer numbers. Please see ToLongLong() for additional remarks. */ - bool ToULongLong(wxULongLong_t val, int base = 10); + bool ToULongLong(wxULongLong_t val, int base = 10) const; //@{ /** Same as @ref wxString::utf8str utf8_str. */ - const char* ToUTF8(); - const wxCharBuffer ToUF8(); + const char* ToUTF8() const; + const const wxCharBuffer ToUF8() const; //@} /** @@ -914,7 +940,7 @@ public: /** Returns this string converted to upper case. */ - wxString Upper(); + wxString Upper() const; /** The same as MakeUpper. @@ -928,15 +954,15 @@ public: insertion operators exist (for basic types only). Additionally, the Format() function allows to use simply append formatted value to a string: - + Format() - + FormatV() - + Printf() - + PrintfV() - + @ref operatorout() "operator " */ @@ -948,12 +974,12 @@ public: @c wchar_t*, use @ref charstr() char_str or @ref wcharstr() wchar_string if you need to pass string value to a function expecting non-const pointer. - + @see @ref mbstr() mb_str, @ref wcstr() wc_str, @ref fnstr() fn_str, @ref charstr() char_str, @ref wcharstr() wchar_string */ - const wxChar* c_str(); + const wxChar* c_str() const; /** Returns an object with string data that is implicitly convertible to @@ -961,12 +987,12 @@ public: 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 @ref mbstr() mb_str, @ref wcstr() wc_str, @ref fnstr() fn_str, @ref cstr() c_str, @ref wcharstr() wchar_str */ - wxWritableCharBuffer char_str(const wxMBConv& conv = wxConvLibc); + wxWritableCharBuffer char_str(const wxMBConv& conv = wxConvLibc) const; //@{ /** @@ -975,12 +1001,12 @@ public: In Unicode build, returned value can be either wide character string or C string in charset matching the @c wxConvFileName object, depending on the OS. - + @see wxMBConv, @ref wcstr() wc_str, @ref wcstr() mb_str */ - const wchar_t* fn_str(); - const char* fn_str(); - const wxCharBuffer fn_str(); + const wchar_t* fn_str() const; + const const char* fn_str() const; + const const wxCharBuffer fn_str() const; //@} //@{ @@ -990,12 +1016,12 @@ public: method and returns wxCharBuffer. In ANSI build, this function is same as @ref cstr() c_str. The macro wxWX2MBbuf is defined as the correct return type (without const). - + @see wxMBConv, @ref cstr() c_str, @ref wcstr() wc_str, @ref fnstr() fn_str, @ref charstr() char_str */ - const char* mb_str(const wxMBConv& conv = wxConvLibc); - const wxCharBuffer mb_str(const wxMBConv& conv = wxConvLibc); + const char* mb_str(const wxMBConv& conv = wxConvLibc) const; + const const wxCharBuffer mb_str(const wxMBConv& conv = wxConvLibc) const; //@} /** @@ -1057,16 +1083,16 @@ public: /** Element extraction. */ - wxChar operator [](size_t i); - wxChar operator [](size_t i); - wxChar operator [](int i); - wxChar operator [](int i); + wxChar operator [](size_t i) const; + wxChar operator [](size_t i) const; + const wxChar operator [](int i) const; + wxChar operator [](int i) const; //@} /** Implicit conversion to a C string. */ - operator const wxChar*(); + operator const wxChar*() const; /** Empty string is @false, so !string will only return @true if the string is @@ -1076,7 +1102,7 @@ public: to wxString. See also IsEmpty(). */ - bool operator!(); + bool operator!() const; /** The supported functions are only listed here, please see any STL reference for @@ -1090,8 +1116,8 @@ public: wxCharBuffer object or as a pointer to the internal string contents in UTF-8 build. */ - const char* utf8_str(); - const wxCharBuffer utf8_str(); + const char* utf8_str() const; + const const wxCharBuffer utf8_str() const; //@} //@{ @@ -1101,12 +1127,12 @@ public: method and returns wxWCharBuffer. In Unicode build, this function is same as @ref cstr() c_str. The macro wxWX2WCbuf is defined as the correct return type (without const). - + @see wxMBConv, @ref cstr() c_str, @ref wcstr() mb_str, @ref fnstr() fn_str, @ref wcharstr() wchar_str */ - const wchar_t* wc_str(const wxMBConv& conv); - const wxWCharBuffer wc_str(const wxMBConv& conv); + const wchar_t* wc_str(const wxMBConv& conv) const; + const const wxWCharBuffer wc_str(const wxMBConv& conv) const; //@} /** @@ -1115,51 +1141,65 @@ public: 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 @ref mbstr() mb_str, @ref wcstr() wc_str, @ref fnstr() fn_str, @ref cstr() c_str, @ref charstr() char_str */ - wxWritableWCharBuffer wchar_str(); + wxWritableWCharBuffer wchar_str() const; /** These functions are deprecated, please consider using new wxWidgets 2.0 functions instead of them (or, even better, std::string compatible variants). CompareTo() - + Contains() - + First() - + Freq() - + Index() - + IsAscii() - + IsNull() - + IsNumber() - + IsWord() - + Last() - + Length() - + LowerCase() - + Remove() - + Strip() - + SubString() - + UpperCase() */ }; +/** + FIXME +*/ +wxString Objects: +; + +/** + FIXME +*/ +wxString wxEmptyString; + + + + /** @class wxStringBufferLength @wxheader{string.h} @@ -1233,26 +1273,3 @@ public: wxChar* operator wxChar *(); }; - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -//@{ -/** - Converts its argument to string. - See also: wxFromString. -*/ -wxString wxToString(const wxColour& col); -wxString wxToString(const wxFont& col); -//@} - -//@{ -/** - Converts string to the type of the second argument. Returns @true on success. - See also: wxToString. -*/ -bool wxFromString(const wxString& str, wxColour* col); -bool wxFromString(const wxString& str, wxFont* col); -//@} -