base::Nest

base::Nest< T > Class Template Reference

A container-of-containers class. More...

#include <base_nest.hh>

List of all members.

Public Types

enum  eDestroy { DESTROY = Dlist<T>::DESTROY, KEEP = Dlist<T>::KEEP }

Public Member Functions

 Nest (void)
 Nest (eDestroy destroy)
 ~Nest ()
bool IfEmpty (void) const
 
Returns:
True if Nest has no groups and no items (entirely empty).

GroupId AddGroup (void)
 Add group.
bool IfEmptyGroup (const GroupId &groupId) const
 
Returns:
True if group is empty. False if empty group or ID is invalid.

GroupId FirstGroup (void) const
GroupId NextGroup (const GroupId &groupId) const
T * GetItem (const ItemId &itemId) const
 Get item.
ItemId AddItem (const GroupId &groupId, T *item)
void RemoveItem (GroupId &groupId, ItemId &itemId)
ItemId FirstItem (const GroupId &groupId) const
ItemId NextItem (const GroupId &groupId, const ItemId &itemId) const
template<typename FUNCTOR>
void ForEachItem (FUNCTOR &functor)

Private Types

typedef Dlist< T > InnerDlist
typedef Dlink< T > InnerDlink
typedef Dlist
< InnerDlist > 		OuterDlist
typedef Dlink
< InnerDlist > 		OuterDlink

Private Attributes

eDestroy mDestroy
OuterDlist mOuterDlist

Classes

class  GroupId
 Opaque struct for a group. More...
class  ItemId
 Opaque struct for an item. More...

Detailed Description

template<typename T>
class base::Nest< T >

A container-of-containers class. 

///
/// Features:
/// ---------
/// - Inner containers ("groups") can be added.
/// - Items in groups can be added/removed.
/// - Automatically delete items (can be disabled by passing KEEP to ctor).
/// - Automatically removes groups when last item is removed.
/// - Items/groups are referenced by opaque ID struct (conceals container implementation).
/// - IDs can be tested for validity conveniently in boolean context.
/// - IDs can be invalidated by assigning false.
/// - Items can be traversed circular (Dlist is a circular list).
/// - Can auto-delete items (inherited from Dlists).
/// - Optimal adding/removing of groups/items (being a list as opposed to a STL vector).
/// - Items explicitly removed are NEVER deleted (same behavior as Dlist::Unlink()).
/// - Type-signature checking to detect memory corruption.
/// - Dlist implementation/interface is mostly concealed except
///   that Dlist destroy ctor args are accepted (esp. KEEP).
///
/// Deficiencies:
/// -------------
/// - Limited to containing pointers-to-objects (Dlist links pointers-to-objects).
/// - Slow traversal being a list, lacks operator[].
///
/// GroupId/ItemId, validity checking:
/// --------------------------------------
/// Default ctors makes an invalid IDs (analogous to an uninitialized variable being invalid).
/// Validity can be checked in a boolean context.
/// Assigning false to an ID invalidates it.
/// RemoveItem(GroupId&,ItemId&) invalidates the passed ItemID
/// since afterwards it no longer references an item, and the GroupId
/// may be invalidated if it was auto-removed if the item was the remaining one.
/// Caller should stop using IDs after removing with them.
///
///    class Class
///    {
///        void ProcessData( void )
///        {
///            if ( mGroupId )
///            {
///               ...process group...
///               mGroupId = false;  // invalidate ID (serves as a flag)
///            }
///            
///        }
///        void AddData( void )
///        {
///            mGroupId = mNest.AddGroup();
///        }
///    private:
///        Nest<Object>           mNest;
///        Nest<Object>::GroupId  mGroupId;  // initially invalid
///    };
///
/// Why Remove() never deletes linked objects:
/// ------------------------------------------
/// See comments about Unlink() at Dlist.  Nest::Remove() calls Dlist::Unlink().
///
///

Member Typedef Documentation

template<typename T>
typedef Dlist<T> base::Nest< T >::InnerDlist [private]

template<typename T>
typedef Dlink<T> base::Nest< T >::InnerDlink [private]

template<typename T>
typedef Dlist<InnerDlist> base::Nest< T >::OuterDlist [private]

template<typename T>
typedef Dlink<InnerDlist> base::Nest< T >::OuterDlink [private]

Member Enumeration Documentation

template<typename T>
enum base::Nest::eDestroy

Enumerator:
DESTROY 
KEEP 

Constructor & Destructor Documentation

template<typename T>
base::Nest< T >::Nest ( void   )  [inline]

template<typename T>
base::Nest< T >::Nest ( eDestroy  destroy  )  [inline]

template<typename T>
base::Nest< T >::~Nest (  )  [inline]

Member Function Documentation

template<typename T>
bool base::Nest< T >::IfEmpty ( void   )  const [inline]

Returns:
True if Nest has no groups and no items (entirely empty).

template<typename T>
GroupId base::Nest< T >::AddGroup ( void   )  [inline]

Add group.

template<typename T>
bool base::Nest< T >::IfEmptyGroup ( const GroupId &  groupId  )  const [inline]

Returns:
True if group is empty. False if empty group or ID is invalid.

template<typename T>
GroupId base::Nest< T >::FirstGroup ( void   )  const [inline]

Returns:
ID of first group or invalid ID if none exist. User can check validity in boolean context: Nest<T>::GroupId id = mNest.FirstGroup(); if ( id ) { First group exists. }

template<typename T>
GroupId base::Nest< T >::NextGroup ( const GroupId &  groupId  )  const [inline]

Returns:
Next group or invalid ID if none exist. Circulates back to the first group if the last one was passed.
Precondition:
Passed groupId must be valid.

template<typename T>
T* base::Nest< T >::GetItem ( const ItemId &  itemId  )  const [inline]

Get item.

template<typename T>
ItemId base::Nest< T >::AddItem ( const GroupId &  groupId,
T *  item 
) [inline]

Append item to group.

Precondition:
Passed ID must be valid.

template<typename T>
void base::Nest< T >::RemoveItem ( GroupId &  groupId,
ItemId &  itemId 
) [inline]

Remove item from group. Item is NEVER deleted -- regardless of DESTROY/KEEP ctor arg. Caller must stop using ItemId as it becomes invalid afterwards! groupId will become INVALID when the last remaining item is removed as the empty group will be auto-removed.

template<typename T>
ItemId base::Nest< T >::FirstItem ( const GroupId &  groupId  )  const [inline]

Returns:
ID of first item or invalid ID if no items. GetItem() can then be called to get it.

template<typename T>
ItemId base::Nest< T >::NextItem ( const GroupId &  groupId,
const ItemId &  itemId 
) const [inline]

Returns:
Next item or invalid ID if no items. Clients should use ForEachItem() since traversing is tricky. GetItem() can then be called to get it. If item is last, circulates back to the first. If only one item exists, it circulates to itself (ItemId will be true).

template<typename T>
template<typename FUNCTOR>
void base::Nest< T >::ForEachItem ( FUNCTOR &  functor  )  [inline]

Clients should use ForEach() because traversing is tricky. Example: struct Functor { void operator()( Item* item ) { } }; mNest.ForEach( Functor() );

Member Data Documentation

template<typename T>
eDestroy base::Nest< T >::mDestroy [private]

template<typename T>
OuterDlist base::Nest< T >::mOuterDlist [private]

The documentation for this class was generated from the following file: Palomino 3D Engine documents generated by doxygen 1.5.3 on Fri Nov 23 11:26:19 2007