4a31b0c34f
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@53120 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
369 lines
11 KiB
Objective-C
369 lines
11 KiB
Objective-C
/////////////////////////////////////////////////////////////////////////////
|
|
// Name: ptr_scpd.h
|
|
// Purpose: interface of wxScopedPtr
|
|
// Author: wxWidgets team
|
|
// RCS-ID: $Id$
|
|
// Licence: wxWindows license
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
/**
|
|
@class wxScopedPtr
|
|
@wxheader{ptr_scpd.h}
|
|
|
|
This is a simple scoped smart pointer implementation that is similar to
|
|
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 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
|
|
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.
|
|
|
|
@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{smartpointers}
|
|
|
|
@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.
|
|
*/
|
|
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.
|
|
*/
|
|
const T* get();
|
|
|
|
/**
|
|
This operator works like the standard C++ pointer operator to return the object
|
|
being pointed to by the pointer.
|
|
|
|
@note
|
|
If the pointer is @NULL or invalid this will crash.
|
|
*/
|
|
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 ->();
|
|
|
|
/**
|
|
Returns the currently hold pointer and resets the smart pointer object to
|
|
@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.
|
|
|
|
@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);
|
|
|
|
/**
|
|
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& other);
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
@class wxScopedArray
|
|
@wxheader{ptr_scpd.h}
|
|
|
|
This is a simple scoped smart pointer array implementation that is similar 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{smartpointers}
|
|
|
|
@see wxScopedPtr
|
|
*/
|
|
class wxScopedArray
|
|
{
|
|
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);
|
|
|
|
/**
|
|
This operator gets the pointer stored in the smart pointer or returns @NULL if
|
|
there is none.
|
|
*/
|
|
const T* get();
|
|
|
|
/**
|
|
This operator acts like the standard [] indexing operator for C++ arrays. The
|
|
function does not do bounds checking.
|
|
*/
|
|
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);
|
|
|
|
/**
|
|
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& 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.
|
|
|
|
@library{wxbase}
|
|
@category{smartpointers}
|
|
*/
|
|
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.
|
|
*/
|
|
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!
|
|
*/
|
|
~wxScopedTiedPtr();
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
@wxheader{ptr_scpd.h}
|
|
|
|
A scoped pointer template class. It is the template version of
|
|
the old-style @ref classwx_scoped_ptr "scoped pointer macros".
|
|
|
|
@library{wxbase}
|
|
@category{smartpointers}
|
|
|
|
@see wxSharedPtr<T>, wxWeakRef<T>
|
|
*/
|
|
template<typename T>
|
|
class wxScopedPtr<T>
|
|
{
|
|
public:
|
|
/**
|
|
Constructor.
|
|
*/
|
|
wxScopedPtr(T* ptr = NULL);
|
|
|
|
/**
|
|
Destructor.
|
|
*/
|
|
~wxScopedPtr();
|
|
|
|
/**
|
|
Returns pointer to object or @NULL.
|
|
*/
|
|
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 @true, if it contains
|
|
a @NULL pointer it will return @false.
|
|
*/
|
|
operator unspecified_bool_type() const;
|
|
|
|
/**
|
|
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;
|
|
|
|
/**
|
|
Returns pointer to object. If the pointer is @NULL this method will
|
|
cause an assert in debug mode.
|
|
*/
|
|
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 @a ptr.
|
|
The previous pointer will be deleted.
|
|
*/
|
|
void reset(T* ptr = NULL);
|
|
|
|
/**
|
|
Swaps pointers.
|
|
*/
|
|
void swap(wxScopedPtr<T>& ot);
|
|
};
|
|
|