From 0367b928913d772d713f72d0184f4cc3968112fb Mon Sep 17 00:00:00 2001
From: Vadim Zeitlin <vadim@wxwidgets.org>
Date: Sat, 5 Apr 2008 17:50:16 +0000
Subject: [PATCH] document Alloc() vs returning bool (part of bug 1933693)

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@53030 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
---
 include/wx/string.h |  2 +-
 interface/string.h  | 49 ++++++++++++++++++++++++++++++++++-----------
 2 files changed, 38 insertions(+), 13 deletions(-)

diff --git a/include/wx/string.h b/include/wx/string.h
index f3afbd34ff..a648beb6d7 100644
--- a/include/wx/string.h
+++ b/include/wx/string.h
@@ -1729,7 +1729,7 @@ public:
   // raw access to string memory
     // ensure that string has space for at least nLen characters
     // only works if the data of this string is not shared
-  bool Alloc(size_t nLen) { reserve(nLen); /*return capacity() >= nLen;*/ return true; }
+  bool Alloc(size_t nLen) { reserve(nLen); return capacity() >= nLen; }
     // minimize the string's memory
     // only works if the data of this string is not shared
   bool Shrink();
diff --git a/interface/string.h b/interface/string.h
index 8076a9652b..c44f1a059c 100644
--- 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
-
-        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
-    */
-    void Alloc(size_t 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.
+    */
+    bool Alloc(size_t nLen);
 
     //@{
     /**
-- 
2.47.2