memory

00001 // <memory> -*- C++ -*-
00002 
00003 // Copyright (C) 2001, 2002 Free Software Foundation, Inc.
00004 //
00005 // This file is part of the GNU ISO C++ Library.  This library is free
00006 // software; you can redistribute it and/or modify it under the
00007 // terms of the GNU General Public License as published by the
00008 // Free Software Foundation; either version 2, or (at your option)
00009 // any later version.
00010 
00011 // This library is distributed in the hope that it will be useful,
00012 // but WITHOUT ANY WARRANTY; without even the implied warranty of
00013 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00014 // GNU General Public License for more details.
00015 
00016 // You should have received a copy of the GNU General Public License along
00017 // with this library; see the file COPYING.  If not, write to the Free
00018 // Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307,
00019 // USA.
00020 
00021 // As a special exception, you may use this file as part of a free software
00022 // library without restriction.  Specifically, if other files instantiate
00023 // templates or use macros or inline functions from this file, or you compile
00024 // this file and link it with other files to produce an executable, this
00025 // file does not by itself cause the resulting executable to be covered by
00026 // the GNU General Public License.  This exception does not however
00027 // invalidate any other reasons why the executable file might be covered by
00028 // the GNU General Public License.
00029 
00030 /*
00031  * Copyright (c) 1997-1999
00032  * Silicon Graphics Computer Systems, Inc.
00033  *
00034  * Permission to use, copy, modify, distribute and sell this software
00035  * and its documentation for any purpose is hereby granted without fee,
00036  * provided that the above copyright notice appear in all copies and
00037  * that both that copyright notice and this permission notice appear
00038  * in supporting documentation.  Silicon Graphics makes no
00039  * representations about the suitability of this software for any
00040  * purpose.  It is provided "as is" without express or implied warranty.
00041  *
00042  */
00043 
00044 /** @file memory
00045  *  This is a Standard C++ Library header.  You should @c #include this header
00046  *  in your programs, rather than any of the "st[dl]_*.h" implementation files.
00047  */
00048 
00049 #ifndef _CPP_MEMORY
00050 #define _CPP_MEMORY 1
00051 
00052 #pragma GCC system_header
00053 
00054 #include <bits/stl_algobase.h>
00055 #include <bits/stl_alloc.h>
00056 #include <bits/stl_construct.h>
00057 #include <bits/stl_iterator_base_types.h> //for iterator_traits
00058 #include <bits/stl_uninitialized.h>
00059 #include <bits/stl_raw_storage_iter.h>
00060 
00061 namespace std
00062 {
00063   /**
00064    *  @if maint
00065    *  This is a helper function.  The unused second parameter exists to
00066    *  permit the real get_temporary_buffer to use template parameter deduction.
00067    *
00068    *  XXX This should perhaps use the pool.
00069    *  @endif
00070    */
00071   template<typename _Tp>
00072     pair<_Tp*, ptrdiff_t>
00073     __get_temporary_buffer(ptrdiff_t __len, _Tp*)
00074     {
00075       if (__len > ptrdiff_t(INT_MAX / sizeof(_Tp)))
00076     __len = INT_MAX / sizeof(_Tp);
00077       
00078       while (__len > 0) 
00079     {
00080       _Tp* __tmp = (_Tp*) std::malloc((std::size_t)__len * sizeof(_Tp));
00081       if (__tmp != 0)
00082         return pair<_Tp*, ptrdiff_t>(__tmp, __len);
00083       __len /= 2;
00084     }
00085       return pair<_Tp*, ptrdiff_t>((_Tp*)0, 0);
00086     }
00087 
00088   /**
00089    *  @brief This is a mostly-useless wrapper around malloc().
00090    *  @param  len  The number of objects of type Tp.
00091    *  @return   See full description.
00092    *
00093    *  Reinventing the wheel, but this time with prettier spokes!
00094    *
00095    *  This function tries to obtain storage for @c len adjacent Tp objects.
00096    *  The objects themselves are not constructed, of course.  A pair<> is
00097    *  returned containing "the buffer s address and capacity (in the units of
00098    *  sizeof(Tp)), or a pair of 0 values if no storage can be obtained."
00099    *  Note that the capacity obtained may be less than that requested if the
00100    *  memory is unavailable; you should compare len with the .second return
00101    *  value.
00102    */
00103   template<typename _Tp>
00104     inline pair<_Tp*,ptrdiff_t>
00105     get_temporary_buffer(ptrdiff_t __len)
00106     { return __get_temporary_buffer(__len, (_Tp*) 0); }
00107 
00108   /**
00109    *  @brief The companion to get_temporary_buffer().
00110    *  @param  p  A buffer previously allocated by get_temporary_buffer.
00111    *  @return   None.
00112    *
00113    *  Frees the memory pointed to by p.
00114    */
00115   template<typename _Tp>
00116     void
00117     return_temporary_buffer(_Tp* __p)
00118     { std::free(__p); }
00119 
00120   /**
00121    *  A wrapper class to provide auto_ptr with reference semantics.  For
00122    *  example, an auto_ptr can be assigned (or constructed from) the result of
00123    *  a function which returns an auto_ptr by value.
00124    *
00125    *  All the auto_ptr_ref stuff should happen behind the scenes.
00126    */
00127   template<typename _Tp1>
00128     struct auto_ptr_ref
00129     {
00130       _Tp1* _M_ptr;
00131       
00132       explicit
00133       auto_ptr_ref(_Tp1* __p): _M_ptr(__p) { }
00134     };
00135 
00136 
00137   /**
00138    *  @brief  A simple smart pointer providing strict ownership semantics.
00139    *
00140    *  The Standard says:
00141    *  <pre>
00142    *  An @c auto_ptr owns the object it holds a pointer to.  Copying an
00143    *  @c auto_ptr copies the pointer and transfers ownership to the destination.
00144    *  If more than one @c auto_ptr owns the same object at the same time the
00145    *  behavior of the program is undefined.
00146    *
00147    *  The uses of @c auto_ptr include providing temporary exception-safety for
00148    *  dynamically allocated memory, passing ownership of dynamically allocated
00149    *  memory to a function, and returning dynamically allocated memory from a
00150    *  function.  @c auto_ptr does not meet the CopyConstructible and Assignable
00151    *  requirements for Standard Library <a href="tables.html#65">container</a>
00152    *  elements and thus instantiating a Standard Library container with an
00153    *  @c auto_ptr results in undefined behavior.
00154    *  </pre>
00155    *  Quoted from [20.4.5]/3.
00156    *
00157    *  Good examples of what can and cannot be done with auto_ptr can be found
00158    *  in the libstdc++ testsuite.
00159    *
00160    *  @if maint
00161    *  _GLIBCPP_RESOLVE_LIB_DEFECTS
00162    *  127.  auto_ptr<> conversion issues
00163    *  These resolutions have all been incorporated.
00164    *  @endif
00165    */
00166   template<typename _Tp>
00167     class auto_ptr
00168     {
00169     private:
00170       _Tp* _M_ptr;
00171       
00172     public:
00173       /// The pointed-to type.
00174       typedef _Tp element_type;
00175       
00176       /**
00177        *  @brief  An %auto_ptr is usually constructed from a raw pointer.
00178        *  @param  p  A pointer (defaults to NULL).
00179        *
00180        *  This object now @e owns the object pointed to by @a p.
00181        */
00182       explicit
00183       auto_ptr(element_type* __p = 0) throw() : _M_ptr(__p) { }
00184 
00185       /**
00186        *  @brief  An %auto_ptr can be constructed from another %auto_ptr.
00187        *  @param  a  Another %auto_ptr of the same type.
00188        *
00189        *  This object now @e owns the object previously owned by @a a,
00190        *  which has given up ownsership.
00191        */
00192       auto_ptr(auto_ptr& __a) throw() : _M_ptr(__a.release()) { }
00193 
00194       /**
00195        *  @brief  An %auto_ptr can be constructed from another %auto_ptr.
00196        *  @param  a  Another %auto_ptr of a different but related type.
00197        *
00198        *  A pointer-to-Tp1 must be convertible to a pointer-to-Tp/element_type.
00199        *
00200        *  This object now @e owns the object previously owned by @a a,
00201        *  which has given up ownsership.
00202        */
00203       template<typename _Tp1>
00204         auto_ptr(auto_ptr<_Tp1>& __a) throw() : _M_ptr(__a.release()) { }
00205 
00206       /**
00207        *  @brief  %auto_ptr assignment operator.
00208        *  @param  a  Another %auto_ptr of the same type.
00209        *
00210        *  This object now @e owns the object previously owned by @a a,
00211        *  which has given up ownsership.  The object that this one @e
00212        *  used to own and track has been deleted.
00213        */
00214       auto_ptr&
00215       operator=(auto_ptr& __a) throw()
00216       {
00217     reset(__a.release());
00218     return *this;
00219       }
00220 
00221       /**
00222        *  @brief  %auto_ptr assignment operator.
00223        *  @param  a  Another %auto_ptr of a different but related type.
00224        *
00225        *  A pointer-to-Tp1 must be convertible to a pointer-to-Tp/element_type.
00226        *
00227        *  This object now @e owns the object previously owned by @a a,
00228        *  which has given up ownsership.  The object that this one @e
00229        *  used to own and track has been deleted.
00230        */
00231       template<typename _Tp1>
00232         auto_ptr&
00233         operator=(auto_ptr<_Tp1>& __a) throw()
00234         {
00235       reset(__a.release());
00236       return *this;
00237     }
00238 
00239       /**
00240        *  When the %auto_ptr goes out of scope, the object it owns is deleted.
00241        *  If it no longer owns anything (i.e., @c get() is @c NULL), then this
00242        *  has no effect.
00243        *
00244        *  @if maint
00245        *  The C++ standard says there is supposed to be an empty throw
00246        *  specification here, but omitting it is standard conforming.  Its
00247        *  presence can be detected only if _Tp::~_Tp() throws, but this is
00248        *  prohibited.  [17.4.3.6]/2
00249        *  @end maint
00250        */
00251       ~auto_ptr() { delete _M_ptr; }
00252       
00253       /**
00254        *  @brief  Smart pointer dereferencing.
00255        *
00256        *  If this %auto_ptr no longer owns anything, then this
00257        *  operation will crash.  (For a smart pointer, "no longer owns
00258        *  anything" is the same as being a null pointer, and you know
00259        *  what happens when you dereference one of those...)
00260        */
00261       element_type&
00262       operator*() const throw() { return *_M_ptr; }
00263       
00264       /**
00265        *  @brief  Smart pointer dereferencing.
00266        *
00267        *  This returns the pointer itself, which the language then will
00268        *  automatically cause to be dereferenced.
00269        */
00270       element_type*
00271       operator->() const throw() { return _M_ptr; }
00272       
00273       /**
00274        *  @brief  Bypassing the smart pointer.
00275        *  @return  The raw pointer being managed.
00276        *
00277        *  You can get a copy of the pointer that this object owns, for
00278        *  situations such as passing to a function which only accepts a raw
00279        *  pointer.
00280        *
00281        *  @note  This %auto_ptr still owns the memory.
00282        */
00283       element_type*
00284       get() const throw() { return _M_ptr; }
00285       
00286       /**
00287        *  @brief  Bypassing the smart pointer.
00288        *  @return  The raw pointer being managed.
00289        *
00290        *  You can get a copy of the pointer that this object owns, for
00291        *  situations such as passing to a function which only accepts a raw
00292        *  pointer.
00293        *
00294        *  @note  This %auto_ptr no longer owns the memory.  When this object
00295        *  goes out of scope, nothing will happen.
00296        */
00297       element_type*
00298       release() throw()
00299       {
00300     element_type* __tmp = _M_ptr;
00301     _M_ptr = 0;
00302     return __tmp;
00303       }
00304       
00305       /**
00306        *  @brief  Forcibly deletes the managed object.
00307        *  @param  p  A pointer (defaults to NULL).
00308        *
00309        *  This object now @e owns the object pointed to by @a p.  The previous
00310        *  object has been deleted.
00311        */
00312       void
00313       reset(element_type* __p = 0) throw()
00314       {
00315     if (__p != _M_ptr)
00316       {
00317         delete _M_ptr;
00318         _M_ptr = __p;
00319       }
00320       }
00321       
00322       /** @{
00323        *  @brief  Automatic conversions
00324        *
00325        *  These operations convert an %auto_ptr into and from an auto_ptr_ref
00326        *  automatically as needed.  This allows constructs such as
00327        *  @code
00328        *    auto_ptr<Derived>  func_returning_auto_ptr(.....);
00329        *    ...
00330        *    auto_ptr<Base> ptr = func_returning_auto_ptr(.....);
00331        *  @endcode
00332        */
00333       auto_ptr(auto_ptr_ref<element_type> __ref) throw()
00334       : _M_ptr(__ref._M_ptr) { }
00335       
00336       auto_ptr&
00337       operator=(auto_ptr_ref<element_type> __ref) throw()
00338       {
00339     if (__ref._M_ptr != this->get())
00340       {
00341         delete _M_ptr;
00342         _M_ptr = __ref._M_ptr;
00343       }
00344     return *this;
00345       }
00346       
00347       template<typename _Tp1>
00348         operator auto_ptr_ref<_Tp1>() throw()
00349         { return auto_ptr_ref<_Tp1>(this->release()); }
00350 
00351       template<typename _Tp1>
00352         operator auto_ptr<_Tp1>() throw()
00353         { return auto_ptr<_Tp1>(this->release()); }
00354       /** @}  */
00355   };
00356 } // namespace std
00357 
00358 #endif 

Generated on Thu Feb 10 23:22:56 2005 for libstdc++-v3 Source by  doxygen 1.4.0