1<?xml version="1.0" encoding="ISO-8859-1"?> 2<!DOCTYPE html 3 PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 4 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 5 6<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> 7<head> 8 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> 9 <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" /> 10 <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" /> 11 <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 20." /> 12 <meta name="GENERATOR" content="vi and eight fingers" /> 13 <title>libstdc++-v3 HOWTO: Chapter 20: General Utilities</title> 14<link rel="StyleSheet" href="../lib3styles.css" type="text/css" /> 15<link rel="Start" href="../documentation.html" type="text/html" 16 title="GNU C++ Standard Library" /> 17<link rel="Prev" href="../19_diagnostics/howto.html" type="text/html" 18 title="Diagnostics" /> 19<link rel="Next" href="../21_strings/howto.html" type="text/html" 20 title="Strings" /> 21<link rel="Bookmark" href="allocator.html" type="text/html" 22 title="Allocators and allocation" /> 23<link rel="Copyright" href="../17_intro/license.html" type="text/html" /> 24<link rel="Help" href="../faq/index.html" type="text/html" title="F.A.Q." /> 25</head> 26<body> 27 28<h1 class="centered"><a name="top">Chapter 20: General Utilities</a></h1> 29 30<p>Chapter 20 deals with utility classes and functions, such as 31 the oft-debated <code>auto_ptr<></code>. 32</p> 33 34 35<!-- ####################################################### --> 36<hr /> 37<h1>Contents</h1> 38<ul> 39 <li><a href="#1"><code>auto_ptr</code> is not omnipotent</a></li> 40 <li><a href="#2"><code>auto_ptr</code> inside container classes</a></li> 41 <li><a href="#3">Functors</a></li> 42 <li><a href="#4">Pairs</a></li> 43 <li><a href="#5">Memory allocators</a></li> 44</ul> 45 46<hr /> 47 48<!-- ####################################################### --> 49 50<h2><a name="1"><code>auto_ptr</code> is not omnipotent</a></h2> 51 <p>I'm not going to try and explain all of the fun and delicious 52 things that can happen with misuse of the auto_ptr class template 53 (called AP here), nor am I going to try and teach you how to use 54 AP safely in the presence of copying. The AP class is a really 55 nifty idea for a smart pointer, but it is one of the dumbest of 56 all the smart pointers -- and that's fine. 57 </p> 58 <p>AP is not meant to be a supersmart solution to all resource 59 leaks everywhere. Neither is it meant to be an effective form 60 of garbage collection (although it can help, a little bit). 61 And it can <em>not</em> be used for arrays! 62 </p> 63 <p>AP <em>is</em> meant to prevent nasty leaks in the presence of 64 exceptions. That's <em>all</em>. This code is AP-friendly: 65 </p> 66 <pre> 67 // not a recommend naming scheme, but good for web-based FAQs 68 typedef std::auto_ptr<MyClass> APMC; 69 70 extern function_taking_MyClass_pointer (MyClass*); 71 extern some_throwable_function (); 72 73 void func (int data) 74 { 75 APMC ap (new MyClass(data)); 76 77 some_throwable_function(); // this will throw an exception 78 79 function_taking_MyClass_pointer (ap.get()); 80 } 81 </pre> 82 <p>When an exception gets thrown, the instance of MyClass that's 83 been created on the heap will be <code>delete</code>'d as the stack is 84 unwound past <code>func()</code>. 85 </p> 86 <p>Changing that code as follows is <em>not</em> AP-friendly: 87 </p> 88 <pre> 89 APMC ap (new MyClass[22]); 90 </pre> 91 <p>You will get the same problems as you would without the use 92 of AP: 93 </p> 94 <pre> 95 char* array = new char[10]; // array new... 96 ... 97 delete array; // ...but single-object delete 98 </pre> 99 <p>AP cannot tell whether the pointer you've passed at creation points 100 to one or many things. If it points to many things, you are about 101 to die. AP is trivial to write, however, so you could write your 102 own <code>auto_array_ptr</code> for that situation (in fact, this has 103 been done many times; check the mailing lists, Usenet, Boost, etc). 104 </p> 105 <p>Return <a href="#top">to top of page</a> or 106 <a href="../faq/index.html">to the FAQ</a>. 107 </p> 108 109<hr /> 110<h2><a name="2"><code>auto_ptr</code> inside container classes</a></h2> 111 <p>All of the <a href="../23_containers/howto.html">containers</a> 112 described in the standard library require their contained types 113 to have, among other things, a copy constructor like this: 114 </p> 115 <pre> 116 struct My_Type 117 { 118 My_Type (My_Type const&); 119 }; 120 </pre> 121 <p>Note the const keyword; the object being copied shouldn't change. 122 The template class <code>auto_ptr</code> (called AP here) does not 123 meet this requirement. Creating a new AP by copying an existing 124 one transfers ownership of the pointed-to object, which means that 125 the AP being copied must change, which in turn means that the 126 copy ctors of AP do not take const objects. 127 </p> 128 <p>The resulting rule is simple: <em>Never ever use a container of 129 auto_ptr objects.</em> The standard says that "undefined" 130 behavior is the result, but it is guaranteed to be messy. 131 </p> 132 <p>To prevent you from doing this to yourself, the 133 <a href="../19_diagnostics/howto.html#3">concept checks</a> built 134 in to this implementation will issue an error if you try to 135 compile code like this: 136 </p> 137 <pre> 138 #include <vector> 139 #include <memory> 140 141 void f() 142 { 143 std::vector< std::auto_ptr<int> > vec_ap_int; 144 } 145 </pre> 146 <p>Should you try this with the checks enabled, you will see an error. 147 </p> 148 <p>Return <a href="#top">to top of page</a> or 149 <a href="../faq/index.html">to the FAQ</a>. 150 </p> 151 152<hr /> 153<h2><a name="3">Functors</a></h2> 154 <p>If you don't know what functors are, you're not alone. Many people 155 get slightly the wrong idea. In the interest of not reinventing 156 the wheel, we will refer you to the introduction to the functor 157 concept written by SGI as part of their STL, in 158 <a href="http://www.sgi.com/tech/stl/functors.html">their 159 http://www.sgi.com/tech/stl/functors.html</a>. 160 </p> 161 <p>Return <a href="#top">to top of page</a> or 162 <a href="../faq/index.html">to the FAQ</a>. 163 </p> 164 165<hr /> 166<h2><a name="4">Pairs</a></h2> 167 <p>The <code>pair<T1,T2></code> is a simple and handy way to 168 carry around a pair of objects. One is of type T1, and another of 169 type T2; they may be the same type, but you don't get anything 170 extra if they are. The two members can be accessed directly, as 171 <code>.first</code> and <code>.second</code>. 172 </p> 173 <p>Construction is simple. The default ctor initializes each member 174 with its respective default ctor. The other simple ctor, 175 </p> 176 <pre> 177 pair (const T1& x, const T2& y); 178 </pre> 179 <p>does what you think it does, <code>first</code> getting <code>x</code> 180 and <code>second</code> getting <code>y</code>. 181 </p> 182 <p>There is a copy constructor, but it requires that your compiler 183 handle member function templates: 184 </p> 185 <pre> 186 template <class U, class V> pair (const pair<U,V>& p); 187 </pre> 188 <p>The compiler will convert as necessary from U to T1 and from 189 V to T2 in order to perform the respective initializations. 190 </p> 191 <p>The comparison operators are done for you. Equality 192 of two <code>pair<T1,T2></code>s is defined as both <code>first</code> 193 members comparing equal and both <code>second</code> members comparing 194 equal; this simply delegates responsibility to the respective 195 <code>operator==</code> functions (for types like MyClass) or builtin 196 comparisons (for types like int, char, etc). 197 </p> 198 <p><a name="pairlt"> 199 The less-than operator is a bit odd the first time you see it. It 200 is defined as evaluating to: 201 </a> 202 </p> 203 <pre> 204 x.first < y.first || 205 ( !(y.first < x.first) && x.second < y.second ) 206 </pre> 207 <p>The other operators are not defined using the <code>rel_ops</code> 208 functions above, but their semantics are the same. 209 </p> 210 <p>Finally, there is a template function called <code>make_pair</code> 211 that takes two references-to-const objects and returns an 212 instance of a pair instantiated on their respective types: 213 </p> 214 <pre> 215 pair<int,MyClass> p = make_pair(4,myobject); 216 </pre> 217 <p>Return <a href="#top">to top of page</a> or 218 <a href="../faq/index.html">to the FAQ</a>. 219 </p> 220 221<hr /> 222<h2><a name="5">Memory allocators</a></h2> 223 <p>The available free store ("heap") management classes are 224 described <a href="allocator.html">here</a>. 225 </p> 226 <p>Return <a href="#top">to top of page</a> or 227 <a href="../faq/index.html">to the FAQ</a>. 228 </p> 229 230 231<!-- ####################################################### --> 232 233<hr /> 234<p class="fineprint"><em> 235See <a href="../17_intro/license.html">license.html</a> for copying conditions. 236Comments and suggestions are welcome, and may be sent to 237<a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>. 238</em></p> 239 240 241</body> 242</html> 243