ai::Ref< X > Class Template Reference

Many object types are reference counted, such as dictionaries (AIDictionaryRef) and arrays (AIArrayRef). More...

#include <IAIRef.h>

List of all members.

Public Member Functions
	Ref ()
	Constructs a null reference.
	Ref (const X &x, IncrementPolicy policy=DoIncrement)
	Constructs a reference to an object and conditionally increments the reference count based on 'policy'.
	Ref (const Ref< X > &ref)
	Copy-constructs a reference from another reference, and increments the reference count.
	~Ref ()
	Destructor.
	operator X () const
	Implicit conversion to an X allows a Ref<X> to be used wherever an X can appear.
void	Assign (const X &x, IncrementPolicy policy=DoIncrement)
	Assignment function, decrements the reference count of the current object and conditionally increments the count of the newly assigned object based on 'policy'.
Ref< X > &	operator= (const Ref< X > &ref)
	Assignment operator, decrements the reference count of the current object and increments the count of the newly assigned object.
bool	operator== (const Ref< X > &ref) const
	Comparison operator, tests whether the same objects are identified by both references.
bool	operator!= (const Ref< X > &ref) const
	Comparison operator, tests whether the same objects are identified by both references.
X *	operator<< (void(*f)(const RefReplaceParam &p))
	Allows a Ref<X> to be passed to a function that takes an X*.
Ref< X > &	to ()
	Allows a Ref<X> to be passed to the AIEntrySuite ToXXX functions.
Protected Attributes
X	x

---

Detailed Description

template<class X>
class ai::Ref< X >

Many object types are reference counted, such as dictionaries (AIDictionaryRef) and arrays (AIArrayRef).

When a plug-in acquires such an object, the reference count is automatically incremented. The plug-in is responsible for releasing the object when it is no longer needed, to avoid memory leaks.

You can avoid the responsibility for memory management by using the Ref<X> template class. This is a "smart pointer" class which automatically takes care of incrementing and decrementing the count of the referenced object. For example the following code manipulates a hypothetical art object's dictionary without reference counting.

Ref<AIDictionaryRef> dict1, dict2;
sAIArt->GetDictionary(art, dict1 << Replace);
sAIDictionary->CreateDictionary(dict2 << Replace);
sAIDictionary->SetBooleanEntry(dict2, "my boolean", true);
sAIDictionary->SetDictEntry(dict1, "first dictionary", dict2);
sAIDictionary->CreateDictionary(dict2 << Replace);
sAIDictionary->SetBooleanEntry(dict2, "my boolean", false);
sAIDictionary->SetDictEntry(dict1, "second dictionary", dict2);

AIEntryRefs retrieved via AIDictionarySuite::Get and passed into functions like AIDictionarySuite::Set or AIEntrySuite::To* functions (ex. ToInteger, also AsUnicodeString) end up with no net change to their reference count since the former increments the count and the latter decrement the count. However functions like AIEntrySuite::GetType and AIEntrySuite::Equiv do not decrement the reference count so if no other functions are called the count must be decremented, which can be done as follows:

Ref<AIEntryRef> entry(sAIDictionary->Get(dict, key1), ai::DontIncrement);
gEntryType = sAIEntry->GetType(entry);
return;

See also:

AICountedObjectSuite

---

Constructor & Destructor Documentation

template<class X>

ai::Ref< X >::Ref

(

)

[inline]

Constructs a null reference.

template<class X >

ai::Ref< X >::Ref	(	const X &	x,
		IncrementPolicy	policy = DoIncrement
	)			[inline]

Constructs a reference to an object and conditionally increments the reference count based on 'policy'.

References AICountedObjectSuite::AddRef, ai::DoIncrement, ai::GetAICountedObjectSuitePtr(), and ai::Ref< X >::x.

template<class X >

ai::Ref< X >::Ref

(

const Ref< X > &

ref

)

[inline]

Copy-constructs a reference from another reference, and increments the reference count.

References AICountedObjectSuite::AddRef, ai::GetAICountedObjectSuitePtr(), and ai::Ref< X >::x.

template<class X >

ai::Ref< X >::~Ref

(

)

[inline]

Destructor.

Decrements the reference count.

References ai::GetAICountedObjectSuitePtr(), AICountedObjectSuite::Release, and ai::Ref< X >::x.

---

Member Function Documentation

template<class X >

void ai::Ref< X >::Assign	(	const X &	x,
		IncrementPolicy	policy = DoIncrement
	)			[inline]

Assignment function, decrements the reference count of the current object and conditionally increments the count of the newly assigned object based on 'policy'.

References AICountedObjectSuite::AddRef, ai::DoIncrement, ai::GetAICountedObjectSuitePtr(), AICountedObjectSuite::Release, and ai::Ref< X >::x.

template<class X>

ai::Ref< X >::operator X

(

)

const [inline]

Implicit conversion to an X allows a Ref<X> to be used wherever an X can appear.

References ai::Ref< X >::x.

template<class X>

bool ai::Ref< X >::operator!=

(

const Ref< X > &

ref

)

const [inline]

Comparison operator, tests whether the same objects are identified by both references.

References ai::Ref< X >::x.

template<class X >

X * ai::Ref< X >::operator<<

(

void(*)(const RefReplaceParam &p)

f

)

[inline]

Allows a Ref<X> to be passed to a function that takes an X*.

Releases the current referenced object and expects the function to assign a new object to the pointer and increment its reference count. Use the function Replace() for the dummy parameter p.

References ai::GetAICountedObjectSuitePtr(), AICountedObjectSuite::Release, and ai::Ref< X >::x.

template<class X >

Ref< X > & ai::Ref< X >::operator=

(

const Ref< X > &

ref

)

[inline]

Assignment operator, decrements the reference count of the current object and increments the count of the newly assigned object.

References AICountedObjectSuite::AddRef, ai::GetAICountedObjectSuitePtr(), AICountedObjectSuite::Release, and ai::Ref< X >::x.

template<class X>

bool ai::Ref< X >::operator==

(

const Ref< X > &

ref

)

const [inline]

Comparison operator, tests whether the same objects are identified by both references.

References ai::Ref< X >::x.

template<class X >

Ref< X > & ai::Ref< X >::to

(

)

[inline]

Allows a Ref<X> to be passed to the AIEntrySuite ToXXX functions.

Increments the reference count to offset the decremented count on the API side, keeping the count correct and allowing the destructor on the plug-in side to dispose of the object.

References AICountedObjectSuite::AddRef, ai::GetAICountedObjectSuitePtr(), and ai::Ref< X >::x.

---

Member Data Documentation

template<class X>

X ai::Ref< X >::x [protected]

Referenced by ai::Ref< X >::Assign(), ai::Ref< X >::operator X(), ai::Ref< X >::operator!=(), ai::Ref< X >::operator<<(), ai::Ref< X >::operator=(), ai::Ref< X >::operator==(), ai::Ref< X >::Ref(), ai::Ref< X >::to(), and ai::Ref< X >::~Ref().

---

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

• IAIRef.h