   
   
   
   
   
   
Chapter 20:  General Utilities 
Chapter 20 deals with utility classes and functions, such as
   the oft-debated 
auto_ptr<>.
Contents
   
#1auto_ptr is not omnipotent    
#2auto_ptr inside container classes    
#3Functors    
#4Pairs    
#5Memory allocators auto_ptr is not omnipotent 
   
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.
   
   
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 
not be used for arrays!
   
   
AP is meant to prevent nasty leaks in the presence of
      exceptions.  That's 
all.  This code is AP-friendly:
   
   
    // 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());
    }
   
   
When an exception gets thrown, the instance of MyClass that's
      been created on the heap will be 
delete'd as the stack is
      unwound past 
func().
   
   
Changing that code as follows is not AP-friendly:
   
   
        APMC  ap (new MyClass[22]);
   
   
You will get the same problems as you would without the use
      of AP:
   
   
        char*  array = new char[10];       // array new...
        ...
        delete array;                      // ...but single-object delete
   
   
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 
auto_array_ptr for that situation (in fact, this has
      been done many times; check the mailing lists, Usenet, Boost, etc).
   
   
Return #topto top of page  or
      
../faq/index.htmlto the FAQ .
   
auto_ptr inside container classes 
   
All of the ../23_containers/howto.htmlcontainers       described in the standard library require their contained types
      to have, among other things, a copy constructor like this:
   
   
    struct My_Type
    {
        My_Type (My_Type const&);
    };
   
   
Note the const keyword; the object being copied shouldn't change.
      The template class 
auto_ptr (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.
   
   
The resulting rule is simple:  Never ever use a container of
      auto_ptr objects.
  The standard says that "undefined"
      behavior is the result, but it is guaranteed to be messy.
   
   
To prevent you from doing this to yourself, the
      
../19_diagnostics/howto.html#3concept checks  built
      in to this implementation will issue an error if you try to
      compile code like this:
   
   
    #include <vector>
    #include <memory>
    
    void f()
    {
        std::vector< std::auto_ptr<int> >   vec_ap_int;
    }
   
   
Should you try this with the checks enabled, you will see an error.
   
   
Return #topto top of page  or
      
../faq/index.htmlto the FAQ .
   
Functors 
   
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
      
http://www.sgi.com/tech/stl/functors.htmltheir
      http://www.sgi.com/tech/stl/functors.html
.
   
   
Return #topto top of page  or
      
../faq/index.htmlto the FAQ .
   
Pairs 
   
The pair<T1,T2> 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
      
.first and .second.
   
   
Construction is simple.  The default ctor initializes each member
      with its respective default ctor.  The other simple ctor,
   
   
    pair (const T1& x, const T2& y);
   
   
does what you think it does, first getting x      and 
second getting y.
   
   
There is a copy constructor, but it requires that your compiler
      handle member function templates:
   
   
    template <class U, class V> pair (const pair<U,V>& p);
   
   
The compiler will convert as necessary from U to T1 and from
      V to T2 in order to perform the respective initializations.
   
   
The comparison operators are done for you.  Equality
      of two 
pair<T1,T2>s is defined as both first      members comparing equal and both 
second members comparing
      equal; this simply delegates responsibility to the respective
      
operator== functions (for types like MyClass) or builtin
      comparisons (for types like int, char, etc).
   
   
      The less-than operator is a bit odd the first time you see it.  It
      is defined as evaluating to:
      
   
   
    x.first  <  y.first  ||
        ( !(y.first  <  x.first)  &&  x.second  <  y.second )
   
   
The other operators are not defined using the rel_ops      functions above, but their semantics are the same.
   
   
Finally, there is a template function called make_pair      that takes two references-to-const objects and returns an
      instance of a pair instantiated on their respective types:
   
   
    pair<int,MyClass> p = make_pair(4,myobject);
   
   
Return #topto top of page  or
      
../faq/index.htmlto the FAQ .
   
Memory allocators 
   
The available free store ("heap") management classes are
      described 
allocator.htmlhere .
   
   
Return #topto top of page  or
      
../faq/index.htmlto the FAQ .
   
See 
../17_intro/license.htmllicense.html  for copying conditions.
Comments and suggestions are welcome, and may be sent to
mailto:libstdc  @gcc.gnu.orgthe libstdc++ mailing list .
