interface/wx/scopedarray.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/scopedarray.h
   3 // Purpose:     interface of wxScopedArray
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxScopedArray
  11
  12     This is a simple scoped smart pointer array implementation that is similar to
  13     the Boost smart pointers (see http://www.boost.org/) but rewritten to
  14     use macros instead.
  15
  16     @b Example:
  17
  18     Below is an example of using a wxWidgets scoped smart pointer and pointer array.
  19
  20     @code
  21     class MyClass { ... };
  22
  23     // declare a smart pointer to a MyClass called wxMyClassPtr
  24     wxDECLARE_SCOPED_PTR(MyClass, wxMyClassPtr)
  25     // declare a smart pointer to an array of chars
  26     wxDECLARE_SCOPED_ARRAY(char, wxCharArray)
  27
  28     ...
  29
  30     // define the first pointer class, must be complete
  31     wxDEFINE_SCOPED_PTR(MyClass, wxMyClassPtr)
  32     // define the second pointer class
  33     wxDEFINE_SCOPED_ARRAY(char, wxCharArray)
  34
  35     // create an object with a new pointer to MyClass
  36     wxMyClassPtr theObj(new MyClass());
  37     // reset the pointer (deletes the previous one)
  38     theObj.reset(new MyClass());
  39
  40     // access the pointer
  41     theObj->MyFunc();
  42
  43     // create an object with a new array of chars
  44     wxCharArray theCharObj(new char[100]);
  45
  46     // access the array
  47     theCharObj[0] = "!";
  48     @endcode
  49
  50     <b>Declaring new smart pointer types:</b>
  51     @code
  52     wxDECLAR_SCOPED_ARRAY( TYPE,        // type of the values
  53                            CLASSNAME ); // name of the class
  54     @endcode
  55
  56     A smart pointer holds a pointer to an object (which must be complete when
  57     wxDEFINE_SCOPED_ARRAY() is called).
  58
  59     The memory used by the object is deleted when the smart pointer goes out of
  60     scope. The first argument of the macro is the pointer type, the second is the
  61     name of the new smart pointer class being created. Below we will use wxScopedArray
  62     to represent the scoped pointer array class, but the user may create the class with
  63     any legal name.
  64
  65     @library{wxbase}
  66     @category{smartpointers}
  67
  68     @see wxScopedPtr
  69 */
  70 class wxScopedArray
  71 {
  72 public:
  73     /**
  74         Creates the smart pointer with the given pointer or none if @NULL.  On
  75         compilers that support it, this uses the explicit keyword.
  76     */
  77     wxScopedArray(type*  T = NULL);
  78
  79     /**
  80         This operator gets the pointer stored in the smart pointer or returns @NULL if
  81         there is none.
  82     */
  83     const T* get();
  84
  85     /**
  86         This operator acts like the standard [] indexing operator for C++ arrays.  The
  87         function does not do bounds checking.
  88     */
  89     const T& operator [](long int i);
  90
  91     /**
  92         Deletes the currently held pointer and sets it to 'p' or to @NULL if no
  93         arguments are specified. This function does check to make sure that the
  94         pointer you are assigning is not the same pointer that is already stored.
  95     */
  96     reset(T* p  = NULL);
  97
  98     /**
  99         Swap the pointer inside the smart pointer with @a ot. The pointer being swapped
 100         must be of the same type (hence the same class name).
 101     */
 102     swap(wxScopedArray& ot);
 103 };
 104
 105 /**
 106     A scoped array template class.
 107
 108     This class is similar to boost scoped_array class:
 109     http://www.boost.org/doc/libs/1_37_0/libs/smart_ptr/scoped_array.htm
 110
 111     Notice that objects of this class intentionally cannot be copied.
 112
 113     @library{wxbase}
 114     @category{smartpointers}
 115  */
 116 template <class T>
 117 class wxScopedArray
 118 {
 119 public:
 120     /// The type of the array elements.
 121     typedef T element_type;
 122
 123     /**
 124         Constructor takes ownership of the given array.
 125
 126         If @a array is @NULL, reset() must presumably be called later.
 127
 128         @param array
 129             An array allocated using @c new[] or @NULL.
 130      */
 131     explicit wxScopedArray(T * array = NULL);
 132
 133     /// Destructor destroy the array.
 134     ~wxScopedArray();
 135
 136     /**
 137         Conversion to a boolean expression (in a variant which is not
 138         convertible to anything but a boolean expression).
 139
 140         If this class contains a valid array it will return @true, if it contains
 141         a @NULL pointer it will return @false.
 142     */
 143     operator unspecified_bool_type() const;
 144
 145     /**
 146         Change the array pointer stored.
 147
 148         The previously stored array is deleted.
 149
 150         @param array
 151             An array allocated using @c new[] or @NULL.
 152      */
 153     void reset(T *array = NULL);
 154
 155     /**
 156         Return the n-th element of the array.
 157
 158         Must not be called if the array has no valid pointer.
 159      */
 160     T& operator[](size_t n) const;
 161
 162     /**
 163         Return the array pointer.
 164
 165         The returned pointer may be @NULL. It must not be deleted by the
 166         caller, call @c reset(NULL) instead.
 167      */
 168     T *get() const;
 169
 170     /// Swaps the contents of this array with another one.
 171     void swap(wxScopedArray &other);
 172 };