]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/string.h
projects / wxWidgets.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
Minor clarification
[wxWidgets.git] / interface / string.h
diff --git a/interface/string.h b/interface/string.h
index fc578521721a68c28ad6bbda72ad20a9a9d1a4f9..c44f1a059c3507bf4682b56221dd2fc3bf032e60 100644 (file)
--- a/interface/string.h
+++ b/interface/string.h
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        string.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        string.h
-// Purpose:     documentation for wxStringBuffer class
+// Purpose:     interface of wxStringBuffer
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
@@ -67,6 +67,7 @@ public:
 };
 
 
 };
 
 
+
 /**
     @class wxString
     @wxheader{string.h}
 /**
     @class wxString
     @wxheader{string.h}
@@ -94,11 +95,9 @@ public:
     @category{data}
 
     @stdobjects
     @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
     "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.
         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
     */
         @see @ref overview_mbconvclasses "wxMBConv classes", @ref mbstr()
              mb_str, @ref wcstr() wc_str
     */
@@ -147,18 +146,43 @@ public:
     wxString AfterLast(wxChar ch) const;
 
     /**
     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()
         return a new string which contains the original text converted to the upper or
         lower case and leave the original string unchanged.
         MakeUpper()
-        
+
         Upper()
         Upper()
-        
+
         MakeLower()
         MakeLower()
-        
+
         Lower()
     */
 
         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
         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()
         use it.
         GetChar()
-        
+
         GetWritableChar()
         GetWritableChar()
-        
+
         SetChar()
         SetChar()
-        
+
         Last()
         Last()
-        
+
         @ref operatorbracket() "operator []"
         @ref operatorbracket() "operator []"
-        
+
         @ref cstr() c_str
         @ref cstr() c_str
-        
+
         @ref mbstr() mb_str
         @ref mbstr() mb_str
-        
+
         @ref wcstr() wc_str
         @ref wcstr() wc_str
-        
+
         @ref fnstr() fn_str
         @ref fnstr() fn_str
-        
+
         @ref operatorconstcharpt() "operator const char*"
     */
 
         @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()
         doing direct string comparison as you would also have to precalculate the
         length of the prefix then.
         Cmp()
-        
+
         CmpNoCase()
         CmpNoCase()
-        
+
         IsSameAs()
         IsSameAs()
-        
+
         Matches()
         Matches()
-        
+
         StartsWith()
         StartsWith()
-        
+
         EndsWith()
     */
 
 
     //@{
     /**
         EndsWith()
     */
 
 
     //@{
     /**
-        
+
     */
     bool operator ==(const wxString& x, const wxString& y);
     bool operator ==(const wxString& x, const wxChar* t);
     */
     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 "
         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 plusequal() "operator +="
-        
+
         @ref operatorplus() "operator +"
         @ref operatorplus() "operator +"
-        
+
         Append()
         Append()
-        
+
         Prepend()
     */
 
         Prepend()
     */
 
@@ -339,9 +363,9 @@ public:
         default which creates an empty string) there is also a corresponding assignment
         operator.
         @ref construct() wxString
         default which creates an empty string) there is also a corresponding assignment
         operator.
         @ref construct() wxString
-        
+
         @ref operatorassign() "operator ="
         @ref operatorassign() "operator ="
-        
+
         @ref destruct() ~wxString
     */
 
         @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()
         put the numeric value in and return @true if the @b entire string could be
         converted to a number.
         ToLong()
-        
+
         ToLongLong()
         ToLongLong()
-        
+
         ToULong()
         ToULong()
-        
+
         ToULongLong()
         ToULongLong()
-        
+
         ToDouble()
     */
 
         ToDouble()
     */
 
@@ -408,7 +432,7 @@ public:
     /**
         This static function returns the string containing the result of calling
         Printf() with the passed parameters on it.
     /**
         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, ...);
         @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.
     /**
         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);
         @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.
         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);
         @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()
         useful when working with some external API which requires the caller to provide
         a writable buffer.
         Alloc()
-        
+
         Shrink()
         Shrink()
-        
+
         wxStringBuffer
         wxStringBuffer
-        
+
         wxStringBufferLength
     */
 
         wxStringBufferLength
     */
 
@@ -632,9 +657,9 @@ public:
     /**
         Other string functions.
         Trim()
     /**
         Other string functions.
         Trim()
-        
+
         Truncate()
         Truncate()
-        
+
         Pad()
     */
 
         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:
         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.
         @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()
         These functions replace the standard @e strchr() and @e strstr()
         functions.
         Find()
-        
+
         Replace()
     */
 
         Replace()
     */
 
@@ -733,13 +758,13 @@ public:
         These functions return the string length and check whether the string is empty
         or empty it.
         Len()
         These functions return the string length and check whether the string is empty
         or empty it.
         Len()
-        
+
         IsEmpty()
         IsEmpty()
-        
+
         @ref operatornot() operator!
         @ref operatornot() operator!
-        
+
         Empty()
         Empty()
-        
+
         Clear()
     */
 
         Clear()
     */
 
@@ -765,23 +790,23 @@ public:
         modify the original string and return a new string containing the extracted
         substring.
         Mid()
         modify the original string and return a new string containing the extracted
         substring.
         Mid()
-        
+
         @ref operatorparenth() operator
         @ref operatorparenth() operator
-        
+
         Left()
         Left()
-        
+
         Right()
         Right()
-        
+
         BeforeFirst()
         BeforeFirst()
-        
+
         BeforeLast()
         BeforeLast()
-        
+
         AfterFirst()
         AfterFirst()
-        
+
         AfterLast()
         AfterLast()
-        
+
         StartsWith()
         StartsWith()
-        
+
         EndsWith()
     */
 
         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.
         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;
         @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).
         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;
         @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.
         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;
         @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.
         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;
         @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.
         (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;
         @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:
         insertion operators exist (for basic types only). Additionally, the
         Format() function allows to use simply append
         formatted value to a string:
-        
+
         Format()
         Format()
-        
+
         FormatV()
         FormatV()
-        
+
         Printf()
         Printf()
-        
+
         PrintfV()
         PrintfV()
-        
+
         @ref operatorout() "operator "
     */
 
         @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.
         @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
         @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.
         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
         @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.
         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;
         @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).
         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
     */
         @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).
         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
     */
         @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.
         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
         @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()
         These functions are deprecated, please consider using new wxWidgets 2.0
         functions instead of them (or, even better, std::string compatible variants).
         CompareTo()
-        
+
         Contains()
         Contains()
-        
+
         First()
         First()
-        
+
         Freq()
         Freq()
-        
+
         Index()
         Index()
-        
+
         IsAscii()
         IsAscii()
-        
+
         IsNull()
         IsNull()
-        
+
         IsNumber()
         IsNumber()
-        
+
         IsWord()
         IsWord()
-        
+
         Last()
         Last()
-        
+
         Length()
         Length()
-        
+
         LowerCase()
         LowerCase()
-        
+
         Remove()
         Remove()
-        
+
         Strip()
         Strip()
-        
+
         SubString()
         SubString()
-        
+
         UpperCase()
     */
 };
 
 
         UpperCase()
     */
 };
 
 
+/**
+    FIXME
+*/
+wxString Objects:
+;
+
+/**
+    FIXME
+*/
+wxString wxEmptyString;
+
+
+
+
 /**
     @class wxStringBufferLength
     @wxheader{string.h}
 /**
     @class wxStringBufferLength
     @wxheader{string.h}
@@ -1233,26 +1273,3 @@ public:
     wxChar* operator wxChar *();
 };
 
     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);
-//@}
-
wxWidgets (Impactor)