X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/328f5751e8a06727b137189fe04891a9f43bfc8b..14bdedbc67c490c8b168455bc726f092a950faea:/interface/string.h diff --git a/interface/string.h b/interface/string.h index fc57852172..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 */ @@ -147,18 +146,43 @@ public: 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); //@{ /** @@ -187,11 +211,11 @@ public: 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*" */ @@ -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 */ @@ -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() */ @@ -408,7 +432,7 @@ public: /** 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); @@ -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); @@ -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 */ @@ -632,9 +657,9 @@ public: /** 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. @@ -704,7 +729,7 @@ public: These functions replace the standard @e strchr() and @e strstr() functions. Find() - + Replace() */ @@ -733,13 +758,13 @@ public: These functions return the string length and check whether the string is empty or empty it. Len() - + IsEmpty() - + @ref operatornot() operator! - + Empty() - + Clear() */ @@ -765,23 +790,23 @@ public: 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,8 +816,9 @@ 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; @@ -816,7 +842,7 @@ 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) const; @@ -834,7 +860,7 @@ 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) const; @@ -845,7 +871,7 @@ 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) const; @@ -861,7 +887,7 @@ 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) const; @@ -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,7 +974,7 @@ 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 @@ -961,7 +987,7 @@ 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 @@ -975,7 +1001,7 @@ 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; @@ -990,7 +1016,7 @@ 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 */ @@ -1101,7 +1127,7 @@ 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 */ @@ -1115,7 +1141,7 @@ 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 @@ -1126,40 +1152,54 @@ public: 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); -//@} -