added wxMouseState::GetPosition(), for consistency with wxMouseEvent

[wxWidgets.git] / interface / string.h

diff --git a/interface/string.h b/interface/string.h
index 4441581d90fec3ff91b9d64f8d9bb2d6bd5bf227..c44f1a059c3507bf4682b56221dd2fc3bf032e60 100644 (file)
--- a/interface/string.h
+++ b/interface/string.h
@@ -146,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
+        Preallocate enough space for wxString to store @a nLen characters.
 
-        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
+        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);
 
     //@{
     /**
@@ -658,7 +683,7 @@ public:
         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.