]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/scopedarray.h
put both versions of wxGetMousePosition in one place so they can use one implementation
[wxWidgets.git] / 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 licence
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 };