interface/wx/scopedarray.h

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