| ## Public API Reference

- Main Page
- Modules
- Namespaces
- Classes
- Files
- Related Pages

- Alphabetical List
- Class List
- Class Hierarchy
- Class Members

# csRef< T > Class Template Reference

A smart pointer. More...

`#include <csutil/ref.h>`

List of all members.

## Public Member Functions
void | AttachNew (csPtr< T > newObj)
| Assign an object reference created with the new operator to this smart pointer.
| csRef (csRef const &other)
| Smart pointer copy constructor.
template<class T2>
| csRef (csRef< T2 > const &other)
| Smart pointer copy constructor from assignment-compatible csRef<T2>.
template<class T2>
| csRef (T2 *newobj)
| Construct a smart pointer from a raw object reference with a compatible type.
| csRef (T *newobj)
| Construct a smart pointer from a raw object reference.
| csRef (const csPtr< T > &newobj)
| Construct a smart pointer from a csPtr.
| csRef ()
| Construct an invalid smart pointer (that is, one pointing at nothing).
uint | GetHash () const
| Return a hash value for this smart pointer.
void | Invalidate ()
| Invalidate the smart pointer by setting it to null.
bool | IsValid () const
| Smart pointer validity check.
T & | operator * () const
| Dereference underlying object.
| operator T * () const
| Cast smart pointer to a pointer to the underlying object.
T * | operator-> () const
| Dereference underlying object.
csRef & | operator= (csRef const &other)
| Assign another csRef<> of the same type to this one.
template<class T2>
csRef & | operator= (csRef< T2 > const &other)
| Assign another assignment-compatible csRef<T2> to this one.
csRef & | operator= (T *newobj)
| Assign a raw object reference to this smart pointer.
csRef & | operator= (const csPtr< T > &newobj)
| Assign a csPtr to a smart pointer.
| ~csRef ()
| Smart pointer destructor.
## Friends
bool | operator!= (T *obj, const csRef &r1)
| Test if object pointed to by reference is different from obj.
bool | operator!= (const csRef &r1, T *obj)
| Test if object pointed to by reference is different from obj.
bool | operator!= (const csRef &r1, const csRef &r2)
| Test if the two references point to different object.
bool | operator< (const csRef &r1, const csRef &r2)
| Test the relationship of the addresses of two objects.
bool | operator== (T *obj, const csRef &r1)
| Test if object pointed to by reference is same as obj.
bool | operator== (const csRef &r1, T *obj)
| Test if object pointed to by reference is same as obj.
bool | operator== (const csRef &r1, const csRef &r2)
| Test if the two references point to same object.

## Detailed Description

### template<class T>
class csRef< T >

A smart pointer.

Maintains and correctly manages a reference to a reference-counted object. This template requires only that the object type T implement the methods IncRef() and DecRef(). No other requirements are placed upon T.

Remarks:
  An extended explanation on smart pointers - how they work and what type to use in what scenario - is contained in the User's manual, section "Correctly Using Smart Pointers".

Definition at line 133 of file ref.h.

## Constructor & Destructor Documentation

template<class T>

csRef< T >::csRef | ( |  | ) | `[inline]`

Construct an invalid smart pointer (that is, one pointing at nothing).

Dereferencing or attempting to use the invalid pointer will result in a run-time error, however it is safe to invoke IsValid().

Definition at line 144 of file ref.h.

template<class T>

csRef< T >::csRef | ( | const csPtr< T > & | newobj | ) | `[inline]`

Construct a smart pointer from a csPtr.

Doesn't call IncRef() on the object since it is assumed that the object in csPtr is already IncRef()'ed.

Definition at line 151 of file ref.h.

template<class T>

csRef< T >::csRef | ( | T * | newobj | ) | `[inline]`

Construct a smart pointer from a raw object reference.

Calls IncRef() on the object.

Definition at line 167 of file ref.h.

template<class T>
template<class T2>

csRef< T >::csRef | ( | T2 * | newobj | ) | `[inline]`

Construct a smart pointer from a raw object reference with a compatible type.

Calls IncRef() on the object.

Definition at line 177 of file ref.h.

template<class T>
template<class T2>

csRef< T >::csRef | ( | csRef< T2 > const & | other | ) | `[inline]`

Smart pointer copy constructor from assignment-compatible csRef<T2>.

Definition at line 186 of file ref.h.

template<class T>

csRef< T >::csRef | ( | csRef< T > const & | other | ) | `[inline]`

Smart pointer copy constructor.

Definition at line 194 of file ref.h.

template<class T>

csRef< T >::~csRef | ( |  | ) | `[inline]`

Smart pointer destructor.

Invokes DecRef() upon the underlying object.

Definition at line 202 of file ref.h.

## Member Function Documentation

template<class T>

void csRef< T >::AttachNew | ( | csPtr< T > | newObj | ) | `[inline]`

Assign an object reference created with the new operator to this smart pointer.

Remarks:
  This function allows you to assign an object pointer created with the `new` operator to the csRef object. Proper usage would be:

       csRef<iEvent> event;
       event.AttachNew (new csEvent);

  While not recommended, you can also use this function to assign a csPtr object or csRef object to the csRef. In both of these cases, using AttachNew is equivalent to performing a simple assignment using the `=` operator.

Note:
  Calling this function is equivalent to casting an object to a csPtr<T> and then assigning the csPtr<T> to the csRef, as follows:

       // Same effect as above code.
       csRef<iEvent> event = csPtr<iEvent> (new csEvent);

Definition at line 282 of file ref.h.

Referenced by CS::ImageAutoConvert::ImageAutoConvert().

template<class T>

uint csRef< T >::GetHash | ( |  | ) | const`[inline]`

Return a hash value for this smart pointer.

Definition at line 372 of file ref.h.

template<class T>

void csRef< T >::Invalidate | ( |  | ) | `[inline]`

Invalidate the smart pointer by setting it to null.

Definition at line 368 of file ref.h.

template<class T>

bool csRef< T >::IsValid | ( |  | ) | const`[inline]`

Smart pointer validity check.

Returns true if smart pointer is pointing at an actual object, otherwise returns false.

Definition at line 364 of file ref.h.

Referenced by csG2DDrawText< Tpixel, Tpixmixer1, Tpixmixer2, Tpixmixer3 >::DrawText(), csShaderProgram::GetParamFloatVal(), csShaderProgram::GetParamTransformVal(), csShaderProgram::GetParamVectorVal(), and CS::DocumentHelper::Implementation::FilterDocumentNodeIterator< T >::HasNext().

template<class T>

T& csRef< T >::operator * | ( |  | ) | const`[inline]`

Dereference underlying object.

Definition at line 357 of file ref.h.

template<class T>

csRef< T >::operator T * | ( |  | ) | const`[inline]`

Cast smart pointer to a pointer to the underlying object.

Definition at line 353 of file ref.h.

template<class T>

T* csRef< T >::operator-> | ( |  | ) | const`[inline]`

Dereference underlying object.

Definition at line 349 of file ref.h.

template<class T>

csRef& csRef< T >::operator= | ( | csRef< T > const & | other | ) | `[inline]`

Assign another csRef<> of the same type to this one.

Definition at line 301 of file ref.h.

template<class T>
template<class T2>

csRef& csRef< T >::operator= | ( | csRef< T2 > const & | other | ) | `[inline]`

Assign another assignment-compatible csRef<T2> to this one.

Definition at line 293 of file ref.h.

template<class T>

csRef& csRef< T >::operator= | ( | T * | newobj | ) | `[inline]`

Assign a raw object reference to this smart pointer.

Remarks:
  This function calls the object's IncRef() method. Because of this you should not assign a reference created with the new operator to a csRef object driectly. The following code will produce a memory leak:

       csRef<iEvent> event = new csEvent;

  If you are assigning a new object to a csRef, use AttachNew(T* newObj) instead.

Definition at line 244 of file ref.h.

template<class T>

csRef& csRef< T >::operator= | ( | const csPtr< T > & | newobj | ) | `[inline]`

Assign a csPtr to a smart pointer.

Doesn't call IncRef() on the object since it is assumed that the object in csPtr is already IncRef()'ed.

Remarks:
  After this assignment, the csPtr<T> object is invalidated and cannot be used. You should not (and in fact cannot) decref the csPtr<T> after this assignment has been made.

Definition at line 216 of file ref.h.

Referenced by csRef< iGraphics2D >::operator=().

## Friends And Related Function Documentation

template<class T>

bool operator!= | ( | T * | obj,
|  | const csRef< T > & | r1 |
| ) |  |  | `[friend]`

Test if object pointed to by reference is different from obj.

Definition at line 333 of file ref.h.

template<class T>

bool operator!= | ( | const csRef< T > & | r1,
|  | T * | obj |
| ) |  |  | `[friend]`

Test if object pointed to by reference is different from obj.

Definition at line 323 of file ref.h.

template<class T>

bool operator!= | ( | const csRef< T > & | r1,
|  | const csRef< T > & | r2 |
| ) |  |  | `[friend]`

Test if the two references point to different object.

Definition at line 313 of file ref.h.

template<class T>

bool operator< | ( | const csRef< T > & | r1,
|  | const csRef< T > & | r2 |
| ) |  |  | `[friend]`

Test the relationship of the addresses of two objects.

Remarks:
  Mainly useful when csRef<> is used as the subject of csComparator<>, which employs operator< for comparisons.

Definition at line 342 of file ref.h.

template<class T>

bool operator== | ( | T * | obj,
|  | const csRef< T > & | r1 |
| ) |  |  | `[friend]`

Test if object pointed to by reference is same as obj.

Definition at line 328 of file ref.h.

template<class T>

bool operator== | ( | const csRef< T > & | r1,
|  | T * | obj |
| ) |  |  | `[friend]`

Test if object pointed to by reference is same as obj.

Definition at line 318 of file ref.h.

template<class T>

bool operator== | ( | const csRef< T > & | r1,
|  | const csRef< T > & | r2 |
| ) |  |  | `[friend]`

Test if the two references point to same object.

Definition at line 308 of file ref.h.

The documentation for this class was generated from the following file:

- csutil/ref.h