/////////////////////////////////////////////////////////////////////////////
// Name: ptr_scpd.h
-// Purpose: documentation for wxScopedPtr class
+// Purpose: interface of wxScopedPtr
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
@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<T>.
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}
- @seealso
- wxScopedArray
+ @see wxScopedArray
*/
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.
~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();
+ T* release();
/**
- Deletes the currently held pointer and sets it to @e 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.
+ Deletes the currently held pointer and sets it to @a p or to @NULL if no
+ 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);
};
+
/**
@class wxScopedArray
@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
+
+ <b>Declaring new smart pointer types:</b>
+ @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}
- @seealso
- wxScopedPtr
+ @see wxScopedPtr
*/
class wxScopedArray
{
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
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);
};
+
/**
@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 @e ptr and stores
- @e ptr in the location specified by @e ppTie which must not be
- @NULL.
+ 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.
*/
- wxScopedTiedPtr(T ** ppTie, T * ptr);
+ wxScopedTiedPtr(T** ppTie, T* ptr);
/**
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();
};
+
/**
- @class wxScopedPtrT
@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}
- @seealso
- wxSharedPtr, wxWeakRef
+ @see wxSharedPtr<T>, wxWeakRef<T>
*/
+template<typename T>
class wxScopedPtr<T>
{
public:
/**
Constructor.
*/
- wxScopedPtrT(T * ptr = @NULL);
+ wxScopedPtr(T* ptr = NULL);
/**
Destructor.
*/
- ~wxScopedPtrT();
+ ~wxScopedPtr();
/**
Returns pointer to object or @NULL.
*/
- T * get();
+ T* get() const;
/**
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();
+ 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*();
+ T operator*() const;
/**
Returns pointer to object. If the pointer is @NULL this method will
cause an assert in debug mode.
*/
- T * operator-();
+ 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);
+ void reset(T* ptr = NULL);
/**
Swaps pointers.
*/
- void swap(wxScopedPtr<T> & ot);
+ void swap(wxScopedPtr<T>& ot);
};
+
projects / wxWidgets.git / blobdiff