howto.html: Document shrink-to-fit reserve().

2003-12-16  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.

From-SVN: r74695

libstdc++-v3/ChangeLog

+2003-12-16  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.
+
 2003-12-16  Paolo Carlini  <pcarlini@suse.de>
 
 	* testsuite/performance/narrow_widen_char.cc: Tweak the

libstdc++-v3/docs/html/21_strings/howto.html

@@ -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 &lt; 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>
+      
 
 <!-- ####################################################### -->
 

libstdc++-v3/docs/html/documentation.html

@@ -156,6 +156,7 @@
      <li><a href="21_strings/howto.html#3">Breaking a C++ string into tokens</a></li>
      <li><a href="21_strings/howto.html#4">Simple transformations</a></li>
      <li><a href="21_strings/howto.html#5">Making strings of arbitrary character types</a></li>
+     <li><a href="21_strings/howto.html#6">Shrink-to-fit strings</a></li>
    </ul>
    </li>
 

libstdc++-v3/docs/html/faq/index.html

@@ -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&lt;T&gt;::capacity() 
+                            == std::vector&lt;T&gt;::size?</a> </li>
       </ol>
    </li>
 
@@ -1060,6 +1062,23 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
          candidate C++ ABI that encompasses the standard library.
       </p>
 
+<hr />
+   <h2><a name="5_9">5.9 How do I make std::vector&lt;T&gt;::capacity()
+                     == std::vector&lt;T&gt;::size()?</a> </h2>
+   <!-- referenced by 21_strings/howto.html#6 -->
+   <p>The standard idiom for deallocating a <code>std::vector&lt;T&gt;</code>'s
+      unused memory is to create a temporary copy of the vector and swap their
+      contents, e.g. for <code>std::vector&lt;T&gt; v</code>
+   </p>
+   <pre>
+     std::vector&lt;T&gt;(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>
+
 <!-- ####################################################### -->
 
 <hr />