CObList::GetHead

Syntax

CObject*& GetHead();

CObject* GetHead() const;

Remarks

Gets the CObject pointer that represents the head element of this list.

You must ensure that the list is not empty before calling GetHead. If the list is empty, then the Debug version of the library asserts. Use IsEmpty to verify that the list contains elements.

Return Value

If the list is accessed through a pointer to a const CObList, then GetHead returns a CObject pointer. This allows the function to be used only on the right side of an assignment statement and thus protects the list from modification.

If the list is accessed directly or through a pointer to a CObList, then GetHead returns a reference to a CObject pointer. This allows the function to be used on either side of an assignment statement and thus allows the list entries to be modified.

Example

The following example illustrates the use of GetHead on the left side of an assignment statement.

const CObList* cplist;

CObList* plist = new CObList;

CAge* page1 = new CAge( 21 );

CAge* page2 = new CAge( 30 );

CAge* page3 = new CAge( 40 );

plist->AddHead( page1 );

plist->AddHead( page2 ); // List now contains (30, 21)

// The following statement REPLACES the head element

plist->GetHead() = page3; // List now contains (40, 21)

ASSERT( *(CAge*) plist->GetHead() == CAge( 40 ) );

cplist = plist; // cplist is a pointer to a const list

// cplist->GetHead() = page3; // Does not compile!

ASSERT( *(CAge*) plist->GetHead() == CAge( 40 ) ); // OK

delete page1;

delete page2;

delete page3;

delete plist; // Cleans up memory