X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/b1db61e1fd85b9d28702fb613dba5f375108ff5d..3f16e52c1396f7d58b29b2eea22d7715f0f4596b:/interface/ptr_scpd.h diff --git a/interface/ptr_scpd.h b/interface/ptr_scpd.h index 340242a0da..11180b1a55 100644 --- a/interface/ptr_scpd.h +++ b/interface/ptr_scpd.h @@ -11,20 +11,82 @@ @wxheader{ptr_scpd.h} This is a simple scoped smart pointer implementation that is similar to - the Boost smart pointers but rewritten to - use macros instead. + the Boost smart pointers (see http://www.boost.org) but rewritten + to use macros instead. Since wxWidgets 2.9.0 there is also a templated version of this class - with the same name. See wxScopedPtrT(). + with the same name. See wxScopedPtr. A smart pointer holds a pointer to an object. The memory used by the object is deleted when the smart pointer goes out of scope. This class is different from - the @c std::auto_ptr in so far as it doesn't provide copy constructor + the @c std::auto_ptr<> in so far as it doesn't provide copy constructor nor assignment operator. This limits what you can do with it but is much less - surprizing than the "destructive copy'' behaviour of the standard class. + surprizing than the "destructive copy" behaviour of the standard class. + + @b Example: + + Below is an example of using a wxWidgets scoped smart pointer and pointer array. + + @code + class MyClass{ ... }; + + // declare a smart pointer to a MyClass called wxMyClassPtr + wxDECLARE_SCOPED_PTR(MyClass, wxMyClassPtr) + // declare a smart pointer to an array of chars + wxDECLARE_SCOPED_ARRAY(char, wxCharArray) + + ... + + // define the first pointer class, must be complete + wxDEFINE_SCOPED_PTR(MyClass, wxMyClassPtr) + // define the second pointer class + wxDEFINE_SCOPED_ARRAY(char, wxCharArray) + + // create an object with a new pointer to MyClass + wxMyClassPtr theObj(new MyClass()); + // reset the pointer (deletes the previous one) + theObj.reset(new MyClass()); + + // access the pointer + theObj->MyFunc(); + + // create an object with a new array of chars + wxCharArray theCharObj(new char[100]); + + // access the array + theCharObj[0] = "!"; + @endcode + + @section wxscopedptr_newpointers Declaring new smart pointer types + + To declare the smart pointer class @c CLASSNAME containing pointes to + a (possibly incomplete) type @c TYPE you should use + @code + wxDECLARE_SCOPED_PTR( TYPE, // type of the values + CLASSNAME ); // name of the class + @endcode + And later, when @c TYPE is fully defined, you must also use + @code + wxDEFINE_SCOPED_PTR( TYPE, CLASSNAME ); + @endcode + to implement the scoped pointer class. + + The first argument of these macro is the pointer type, the second is the name + of the new smart pointer class being created. Below we will use wxScopedPtr + to represent the scoped pointer class, but the user may create the class with + any legal name. + + Alternatively, if you don't have to separate the point of declaration and + definition of this class and if you accept the standard naming convention, + that is that the scoped pointer for the class @c Foo is called @c FooPtr, + you can use a single macro which replaces two macros above: + @code + wxDEFINE_SCOPED_PTR_TYPE( TYPE ); + @endcode + Once again, in this cass @c CLASSNAME will be @c TYPEPtr. @library{wxbase} - @category{FIXME} + @category{smartpointers} @see wxScopedArray */ @@ -32,10 +94,11 @@ class wxScopedPtr { public: /** - Creates the smart pointer with the given pointer or none if @NULL. On - compilers that support it, this uses the explicit keyword. + Creates the smart pointer with the given pointer or none if @NULL. + + On compilers that support it, this uses the explicit keyword. */ - explicit wxScopedPtr(type T = NULL); + explicit wxScopedPtr(type* T = NULL); /** Destructor frees the pointer help by this object if it is not @NULL. @@ -43,43 +106,51 @@ public: ~wxScopedPtr(); /** - This operator gets the pointer stored in the smart pointer or returns @NULL if - there is none. + This operator gets the pointer stored in the smart pointer or returns + @NULL if there is none. */ const T* get(); /** This operator works like the standard C++ pointer operator to return the object - being pointed to by the pointer. If the pointer is @NULL or invalid this will - crash. + being pointed to by the pointer. + + @note + If the pointer is @NULL or invalid this will crash. */ - const T operator *(); + const T& operator *(); /** This operator works like the standard C++ pointer operator to return the pointer in the smart pointer or @NULL if it is empty. */ - const T* operator -(); + const T* operator ->(); /** Returns the currently hold pointer and resets the smart pointer object to - @NULL. After a call to this function the caller is responsible for - deleting the pointer. + @NULL. + + @remarks + After a call to this function the caller is responsible for deleting the + pointer. */ T* release(); /** Deletes the currently held pointer and sets it to @a p or to @NULL if no - arguments are specified. This function does check to make sure that the - pointer you are assigning is not the same pointer that is already stored. + arguments are specified. + + @note + This function does check to make sure that the pointer you are assigning + is not the same pointer that is already stored. */ - reset(T p = NULL); + reset(T* p = NULL); /** - Swap the pointer inside the smart pointer with @e other. The pointer being + Swap the pointer inside the smart pointer with @a other. The pointer being swapped must be of the same type (hence the same class name). */ - swap(wxScopedPtr amp; other); + swap(wxScopedPtr& other); }; @@ -89,11 +160,60 @@ public: @wxheader{ptr_scpd.h} This is a simple scoped smart pointer array implementation that is similar to - the Boost smart pointers but rewritten to + the Boost smart pointers (see http://www.boost.org/) but rewritten to use macros instead. + @b Example: + + Below is an example of using a wxWidgets scoped smart pointer and pointer array. + + @code + class MyClass { ... }; + + // declare a smart pointer to a MyClass called wxMyClassPtr + wxDECLARE_SCOPED_PTR(MyClass, wxMyClassPtr) + // declare a smart pointer to an array of chars + wxDECLARE_SCOPED_ARRAY(char, wxCharArray) + + ... + + // define the first pointer class, must be complete + wxDEFINE_SCOPED_PTR(MyClass, wxMyClassPtr) + // define the second pointer class + wxDEFINE_SCOPED_ARRAY(char, wxCharArray) + + // create an object with a new pointer to MyClass + wxMyClassPtr theObj(new MyClass()); + // reset the pointer (deletes the previous one) + theObj.reset(new MyClass()); + + // access the pointer + theObj->MyFunc(); + + // create an object with a new array of chars + wxCharArray theCharObj(new char[100]); + + // access the array + theCharObj[0] = "!"; + @endcode + + Declaring new smart pointer types: + @code + wxDECLAR_SCOPED_ARRAY( TYPE, // type of the values + CLASSNAME ); // name of the class + @endcode + + A smart pointer holds a pointer to an object (which must be complete when + wxDEFINE_SCOPED_ARRAY() is called). + + The memory used by the object is deleted when the smart pointer goes out of + scope. The first argument of the macro is the pointer type, the second is the + name of the new smart pointer class being created. Below we will use wxScopedArray + to represent the scoped pointer array class, but the user may create the class with + any legal name. + @library{wxbase} - @category{FIXME} + @category{smartpointers} @see wxScopedPtr */ @@ -104,7 +224,7 @@ public: Creates the smart pointer with the given pointer or none if @NULL. On compilers that support it, this uses the explicit keyword. */ - wxScopedArray(type T = NULL); + wxScopedArray(type* T = NULL); /** This operator gets the pointer stored in the smart pointer or returns @NULL if @@ -116,20 +236,20 @@ public: This operator acts like the standard [] indexing operator for C++ arrays. The function does not do bounds checking. */ - const T operator [](long int i); + const T& operator [](long int i); /** Deletes the currently held pointer and sets it to 'p' or to @NULL if no arguments are specified. This function does check to make sure that the pointer you are assigning is not the same pointer that is already stored. */ - reset(T p = NULL); + reset(T* p = NULL); /** - Swap the pointer inside the smart pointer with 'ot'. The pointer being swapped + Swap the pointer inside the smart pointer with @a ot. The pointer being swapped must be of the same type (hence the same class name). */ - swap(wxScopedPtr amp; ot); + swap(wxScopedPtr& ot); }; @@ -138,24 +258,22 @@ public: @class wxScopedTiedPtr @wxheader{ptr_scpd.h} - This is a variation on the topic of wxScopedPtr. This - class is also a smart pointer but in addition it "ties'' the pointer value to - another variable. In other words, during the life time of this class the value - of that variable is set to be the same as the value of the pointer itself and - it is reset to its old value when the object is destroyed. This class is - especially useful when converting the existing code (which may already store - the pointers value in some variable) to the smart pointers. + This is a variation on the topic of wxScopedPtr. This class is also a smart pointer + but in addition it "ties" the pointer value to another variable. In other words, + during the life time of this class the value of that variable is set to be the same + as the value of the pointer itself and it is reset to its old value when the object + is destroyed. This class is especially useful when converting the existing code + (which may already store the pointers value in some variable) to the smart pointers. @library{wxbase} - @category{FIXME} + @category{smartpointers} */ -class wxScopedTiedPtr +class wxScopedTiedPtr : public wxScopedPtr { public: /** Constructor creates a smart pointer initialized with @a ptr and stores - @a ptr in the location specified by @a ppTie which must not be - @NULL. + @a ptr in the location specified by @a ppTie which must not be @NULL. */ wxScopedTiedPtr(T** ppTie, T* ptr); @@ -163,9 +281,10 @@ public: Destructor frees the pointer help by this object and restores the value stored at the tied location (as specified in the @ref ctor() constructor) to the old value. - Warning: this location may now contain an uninitialized value if it hadn't been - initialized previously, in particular don't count on it magically being - @NULL! + + @warning + This location may now contain an uninitialized value if it hadn't been + initialized previously, in particular don't count on it magically being @NULL! */ ~wxScopedTiedPtr(); }; @@ -176,25 +295,26 @@ public: @wxheader{ptr_scpd.h} A scoped pointer template class. It is the template version of - the old-style @ref overview_wxscopedptr "scoped pointer macros". + the old-style @ref classwx_scoped_ptr "scoped pointer macros". @library{wxbase} - @category{FIXME} + @category{smartpointers} - @see wxSharedPtr, wxWeakRef + @see wxSharedPtr, wxWeakRef */ +template class wxScopedPtr { public: /** Constructor. */ - wxScopedPtrT(T* ptr = NULL); + wxScopedPtr(T* ptr = NULL); /** Destructor. */ - ~wxScopedPtrT(); + ~wxScopedPtr(); /** Returns pointer to object or @NULL. @@ -203,15 +323,19 @@ public: /** Conversion to a boolean expression (in a variant which is not - convertable to anything but a boolean expression). If this class - contains a valid pointer it will return @e @true, if it contains - a @NULL pointer it will return @e @false. + convertable to anything but a boolean expression). + + If this class contains a valid pointer it will return @true, if it contains + a @NULL pointer it will return @false. */ operator unspecified_bool_type() const; /** - Returns a reference to the object. If the internal pointer is @NULL - this method will cause an assert in debug mode. + Returns a reference to the object. + + @note + If the internal pointer is @NULL this method will cause an assert + in debug mode. */ T operator*() const; @@ -219,18 +343,20 @@ public: Returns pointer to object. If the pointer is @NULL this method will cause an assert in debug mode. */ - T* operator-() const; + T* operator->() const; /** Releases the current pointer and returns it. + + @remarks Afterwards the caller is responsible for deleting the data contained in the scoped pointer before. */ T* release(); /** - Reset pointer to the value of @e ptr. The - previous pointer will be deleted. + Reset pointer to the value of @a ptr. + The previous pointer will be deleted. */ void reset(T* ptr = NULL);