Spec:o3tl/utilities/heap ptr
From Apache OpenOffice Wiki
o3tl::heap_ptr<> - a Const-Transitive Smart Pointer Class
Specification Status | |
Author | Nikolai Pretzell |
Last Change | 2007-05-15 |
Status | Preliminary |
Abstract
heap_ptr<>
is a const-transitive, non-copyable, C++ smart pointer class.
- smart pointer: A class that holds a pointer to memory allocated on the heap. The destructor automatically deletes (deallocates) the memory.
- const-transitive: In
const heap_ptr<int> pX( new int(25) );
not only pX is const, but also the integer value it points to. This is useful for member variables of classes, because if the class administrates the heap memory, it is normally part of its state. - non-copyable: When copying pointers to heap-memory, there either must be a reference counting or the pointer must not be copyable to make sure, delete is called at the right time for the heap memory.
References
Reference Document | Location (URL) |
Product Requirement, RFE, Issue ID | IssueZilla 76768 |
Test case specification | Unit Tests in module o3tl/qa/test-heap_ptr.cxx |
Coding Standards this class helps to match | http://wiki.services.openoffice.org/wiki/Cpp_Coding_Standards/GEN#RAII |
Contacts
Role | Name | E-Mail Address |
Developer | Nikolai Pretzell | np@openoffice.org |
Quality Assurance | Thorsten Behrens | thb@openoffice.org |
Documentation | Nikolai Pretzell | np@openoffice.org |
Detailed Specification
Member Functions
Function | Precondition | Semantic | Postcondition |
---|---|---|---|
heap_ptr(T * pass_heapObject = 0)
|
- | The object pointed to by pass_heapObject is remembered by this instance. It will be deleted, if ~heap_ptr() would be called immediately after. | get() == pass_heapObject |
~heap_ptr()
|
- | If previously get() != 0, the object pointed to by get() now is deleted. | |
self & operator=(T * pass_heapObject)
|
- | Any previously hold object will be deleted. pass_heapObject will be remembered. If before the function get() == pass_heapObject, nothing will happen. |
get() == pass_heapObject |
const T & operator*() const
|
get() != 0 | Returns a const reference to the remembered object on the heap. | returnvalue == *get() |
T & operator*()
|
get() != 0 | Returns a reference to the remembered object on the heap. | returnvalue == *get() |
const T * operator->() const
|
- | Returns a const pointer to the remembered object on the heap. | returnvalue == get() |
T * operator->()
|
- | Returns a pointer to the remembered object on the heap. | returnvalue == get() |
void reset(T * pass_heapObject)
|
- | Any previously hold object will be deleted. pass_heapObject will be remembered. If before the function get() == pass_heapObject, nothing will happen. |
get() == pass_heapObject |
T * release()
|
- | Returns a pointer to the heap object previously remembered. This object will not be remembered by this any more. | get() == 0 |
void swap(self & io_other)
|
- | Objects remembered to by this and io_other are exchanged. | - |
bool is() const
|
- | Returns true, if get() != 0. | - |
const T * get() const
|
- | Returns a pointer to the hold heap object . | - |
T * get()
|
- | Returns a pointer to the hold heap object . | - |
Migration
- Member data on the heap
- This class should be the default for class members that are pointers to heap memory and are not shared with other instances, but administrated only by one object. Plain pointers, std::auto_ptr<> and non const-transitive pointers should be replaced, when refactoring.
- RAII in function bodies
- It can be used in new code, when using RAII for heap memory within a function body.
Open Issues
-