diff options
Diffstat (limited to 'libstdc++-v3/doc/html/20_util/howto.html')
| -rw-r--r-- | libstdc++-v3/doc/html/20_util/howto.html | 234 |
1 files changed, 234 insertions, 0 deletions
diff --git a/libstdc++-v3/doc/html/20_util/howto.html b/libstdc++-v3/doc/html/20_util/howto.html new file mode 100644 index 00000000000..fb02aa169fb --- /dev/null +++ b/libstdc++-v3/doc/html/20_util/howto.html @@ -0,0 +1,234 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!DOCTYPE html + PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> + <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)" /> + <meta name="KEYWORDS" content="HOWTO, libstdc++, GCC, g++, libg++, STL" /> + <meta name="DESCRIPTION" content="HOWTO for the libstdc++ chapter 20." /> + <meta name="GENERATOR" content="vi and eight fingers" /> + <title>libstdc++ HOWTO: Chapter 20: General Utilities</title> +<link rel="StyleSheet" href="../lib3styles.css" type="text/css" /> +<link rel="Start" href="../documentation.html" type="text/html" + title="GNU C++ Standard Library" /> +<link rel="Prev" href="../19_diagnostics/howto.html" type="text/html" + title="Diagnostics" /> +<link rel="Next" href="../21_strings/howto.html" type="text/html" + title="Strings" /> +<link rel="Bookmark" href="allocator.html" type="text/html" + title="Allocators and allocation" /> +<link rel="Copyright" href="../17_intro/license.html" type="text/html" /> +<link rel="Help" href="../faq/index.html" type="text/html" title="F.A.Q." /> +</head> +<body> + +<h1 class="centered"><a name="top">Chapter 20: General Utilities</a></h1> + +<p>Chapter 20 deals with utility classes and functions, such as + the oft-debated <code>auto_ptr<></code>. +</p> + + +<!-- ####################################################### --> +<hr /> +<h1>Contents</h1> +<ul> + <li><a href="#1"><code>auto_ptr</code> is not omnipotent</a></li> + <li><a href="#2"><code>auto_ptr</code> inside container classes</a></li> + <li><a href="#3">Functors</a></li> + <li><a href="#4">Pairs</a></li> + <li><a href="#5">Memory allocators</a></li> +</ul> + +<hr /> + +<!-- ####################################################### --> + +<h2><a name="1"><code>auto_ptr</code> is not omnipotent</a></h2> + <p>I'm not going to try and explain all of the fun and delicious + things that can happen with misuse of the auto_ptr class template + (called AP here), nor am I going to try and teach you how to use + AP safely in the presence of copying. The AP class is a really + nifty idea for a smart pointer, but it is one of the dumbest of + all the smart pointers -- and that's fine. + </p> + <p>AP is not meant to be a supersmart solution to all resource + leaks everywhere. Neither is it meant to be an effective form + of garbage collection (although it can help, a little bit). + And it can <em>not</em> be used for arrays! + </p> + <p>AP <em>is</em> meant to prevent nasty leaks in the presence of + exceptions. That's <em>all</em>. This code is AP-friendly: + </p> + <pre> + // not a recommend naming scheme, but good for web-based FAQs + typedef std::auto_ptr<MyClass> APMC; + + extern function_taking_MyClass_pointer (MyClass*); + extern some_throwable_function (); + + void func (int data) + { + APMC ap (new MyClass(data)); + + some_throwable_function(); // this will throw an exception + + function_taking_MyClass_pointer (ap.get()); + } + </pre> + <p>When an exception gets thrown, the instance of MyClass that's + been created on the heap will be <code>delete</code>'d as the stack is + unwound past <code>func()</code>. + </p> + <p>Changing that code as follows is <em>not</em> AP-friendly: + </p> + <pre> + APMC ap (new MyClass[22]); + </pre> + <p>You will get the same problems as you would without the use + of AP: + </p> + <pre> + char* array = new char[10]; // array new... + ... + delete array; // ...but single-object delete + </pre> + <p>AP cannot tell whether the pointer you've passed at creation points + to one or many things. If it points to many things, you are about + to die. AP is trivial to write, however, so you could write your + own <code>auto_array_ptr</code> for that situation (in fact, this has + been done many times; check the mailing lists, Usenet, Boost, etc). + </p> + <p>Return <a href="#top">to top of page</a> or + <a href="../faq/index.html">to the FAQ</a>. + </p> + +<hr /> +<h2><a name="2"><code>auto_ptr</code> inside container classes</a></h2> + <p>All of the <a href="../23_containers/howto.html">containers</a> + described in the standard library require their contained types + to have, among other things, a copy constructor like this: + </p> + <pre> + struct My_Type + { + My_Type (My_Type const&); + }; + </pre> + <p>Note the const keyword; the object being copied shouldn't change. + The template class <code>auto_ptr</code> (called AP here) does not + meet this requirement. Creating a new AP by copying an existing + one transfers ownership of the pointed-to object, which means that + the AP being copied must change, which in turn means that the + copy ctors of AP do not take const objects. + </p> + <p>The resulting rule is simple: <em>Never ever use a container of + auto_ptr objects.</em> The standard says that "undefined" + behavior is the result, but it is guaranteed to be messy. + </p> + <p>To prevent you from doing this to yourself, the + <a href="../19_diagnostics/howto.html#3">concept checks</a> built + in to this implementation will issue an error if you try to + compile code like this: + </p> + <pre> + #include <vector> + #include <memory> + + void f() + { + std::vector< std::auto_ptr<int> > vec_ap_int; + } + </pre> + <p>Should you try this with the checks enabled, you will see an error. + </p> + <p>Return <a href="#top">to top of page</a> or + <a href="../faq/index.html">to the FAQ</a>. + </p> + +<hr /> +<h2><a name="3">Functors</a></h2> + <p>If you don't know what functors are, you're not alone. Many people + get slightly the wrong idea. In the interest of not reinventing + the wheel, we will refer you to the introduction to the functor + concept written by SGI as part of their STL, in + <a href="http://www.sgi.com/tech/stl/functors.html">their + http://www.sgi.com/tech/stl/functors.html</a>. + </p> + <p>Return <a href="#top">to top of page</a> or + <a href="../faq/index.html">to the FAQ</a>. + </p> + +<hr /> +<h2><a name="4">Pairs</a></h2> + <p>The <code>pair<T1,T2></code> is a simple and handy way to + carry around a pair of objects. One is of type T1, and another of + type T2; they may be the same type, but you don't get anything + extra if they are. The two members can be accessed directly, as + <code>.first</code> and <code>.second</code>. + </p> + <p>Construction is simple. The default ctor initializes each member + with its respective default ctor. The other simple ctor, + </p> + <pre> + pair (const T1& x, const T2& y); + </pre> + <p>does what you think it does, <code>first</code> getting <code>x</code> + and <code>second</code> getting <code>y</code>. + </p> + <p>There is a copy constructor, but it requires that your compiler + handle member function templates: + </p> + <pre> + template <class U, class V> pair (const pair<U,V>& p); + </pre> + <p>The compiler will convert as necessary from U to T1 and from + V to T2 in order to perform the respective initializations. + </p> + <p>The comparison operators are done for you. Equality + of two <code>pair<T1,T2></code>s is defined as both <code>first</code> + members comparing equal and both <code>second</code> members comparing + equal; this simply delegates responsibility to the respective + <code>operator==</code> functions (for types like MyClass) or builtin + comparisons (for types like int, char, etc). + </p> + <p><a name="pairlt"> + The less-than operator is a bit odd the first time you see it. It + is defined as evaluating to: + </a> + </p> + <pre> + x.first < y.first || + ( !(y.first < x.first) && x.second < y.second ) + </pre> + <p>The other operators are not defined using the <code>rel_ops</code> + functions above, but their semantics are the same. + </p> + <p>Finally, there is a template function called <code>make_pair</code> + that takes two references-to-const objects and returns an + instance of a pair instantiated on their respective types: + </p> + <pre> + pair<int,MyClass> p = make_pair(4,myobject); + </pre> + + <p>Return <a href="#top">to top of page</a> or + <a href="../faq/index.html">to the FAQ</a>. + </p> + + +<!-- ####################################################### --> + +<hr /> +<p class="fineprint"><em> +See <a href="../17_intro/license.html">license.html</a> for copying conditions. +Comments and suggestions are welcome, and may be sent to +<a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>. +</em></p> + + +</body> +</html> |
