[v3] basic_string::reserve() shrink-to-fit?

[Jonathan Wakely]

Any comments on these additions to the docs?

2003-12-12  Jonathan Wakely  <redi@gcc.gnu.org>

        * docs/html/21_strings/howto.html: Document shrink-to-fit reserve().
        * docs/html/faq/index.html: Reducing vector's capacity() to size().
        * docs/html/documentation.html, docs/html/faq/index.txt: Regenerate.

jon

-- 
"Until they become conscious they will never rebel,
 and until after they have rebelled they cannot become conscious."
	- 1984, George Orwell
-------------- next part --------------
Index: docs/html/21_strings/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/21_strings/howto.html,v
retrieving revision 1.18
diff -u -p -b -B -r1.18 howto.html
--- docs/html/21_strings/howto.html	18 Nov 2003 20:56:08 -0000	1.18
+++ docs/html/21_strings/howto.html	12 Dec 2003 11:28:44 -0000
@@ -38,6 +38,7 @@
    <li><a href="#3">Breaking a C++ string into tokens</a></li>
    <li><a href="#4">Simple transformations</a></li>
    <li><a href="#5">Making strings of arbitrary character types</a></li>
+   <li><a href="#6">Shrink-to-fit strings</a></li>
 </ul>
 
 <hr />
@@ -443,6 +444,25 @@
       <a href="../faq/index.html">to the FAQ</a>.
    </p>
 
+<hr />
+<h2><a name="6">Shrink-to-fit strings</a></h2>
+   <!-- referenced by faq/index.html#5_9, update link if numbering changes -->
+   <p>From GCC 3.4 calling <code>s.reserve(res)</code> on a
+      <code>string s</code> with <code>res < s.capacity()</code> will
+      reduce the string's capacity to <code>std::max(s.size(), res)</code>.
+   </p>
+   <p>This behaviour is suggested, but not required by the standard. Prior
+      to GCC 3.4 the following alternative can be used instead
+   </p>
+   <pre>
+      std::string(str.data(), str.size()).swap(str);
+   </pre>
+   <p>This is similar to the idiom for reducing a <code>vector</code>'s
+      memory usage (see <a href='../faq/index.html#5_9'>FAQ 5.9</a>) but
+      the regular copy constructor cannot be used because libstdc++'s
+      <code>string</code> is Copy-On-Write.
+   </p>
+      
 
 <!-- ####################################################### -->
 
Index: docs/html/faq/index.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/faq/index.html,v
retrieving revision 1.62
diff -u -p -b -B -r1.62 index.html
--- docs/html/faq/index.html	18 Nov 2003 20:56:12 -0000	1.62
+++ docs/html/faq/index.html	12 Dec 2003 11:28:44 -0000
@@ -118,6 +118,8 @@
          <li><a href="#5_6">Is libstdc++-v3 thread-safe?</a> </li>
          <li><a href="#5_7">How do I get a copy of the ISO C++ Standard?</a> </li>
          <li><a href="#5_8">What's an ABI and why is it so messy?</a> </li>
+         <li><a href="#5_9">How do I make std::vector<T>::capacity() 
+                            == std::vector<T>::size?</a> </li>
       </ol>
    </li>
 
@@ -1059,6 +1061,23 @@ http://clisp.cons.org/~haible/gccinclude
          the decisions, must happen before you can reasonably document a
          candidate C++ ABI that encompasses the standard library.
       </p>
+
+<hr />
+   <h2><a name="5_9">5.9 How do I make std::vector<T>::capacity()
+                     == std::vector<T>::size()?</a> </h2>
+   <!-- referenced by 21_strings/howto.html#6 -->
+   <p>The standard idiom for deallocating a <code>std::vector<T></code>'s
+      unused memory is to create a temporary copy of the vector and swap their
+      contents, e.g. for <code>std::vector<T> v</code>
+   </p>
+   <pre>
+     std::vector<T>(v).swap(v);
+   </pre>
+   <p>The copy will take O(n) time and the swap is constant time.
+   </p>
+   <p>See <a href='../21_strings/howto.html#6'>Shrink-to-fit strings</a> for
+      a similar solution for strings.
+   </p>
 
 <!-- ####################################################### -->