avr-classes
Classes | Public Types | Public Member Functions | List of all members
ItemCollection< BASETYPE, COUNT > Class Template Reference

#include <itemcollection.h>

Public Types

typedef void(* ForEachCallback) (BASETYPE &item, const void *context)
 

Public Member Functions

 ItemCollection (void)
 
bool add (BASETYPE &item)
 
bool addUnique (BASETYPE &item)
 
void remove (BASETYPE &item)
 
void compact (void)
 
void forEach (ForEachCallback action, const void *context=nullptr)
 

Detailed Description

template<class BASETYPE, uint16_t COUNT>
class ItemCollection< BASETYPE, COUNT >

The ItemCollection template class allows to create a collection of arbitrary items. Using the forEach() method, a custom callback method is invoked for each item in the collection. A context is available which allows the callback's owner to pass arguments to the callback method which are specific to this forEach() invocation and thus cannot be stored statically at the caller site.

Parameters
BASETYPEType of items to be collected.
COUNTMaximum number of items in the collection.
Note
Due to the way the ItemCollection stores elements internally, the order of elements is hard to predict. An application designer should not make any assumptions about the order in which elements are handled using the forEach() method.
avr-gcc currently doesn't support std::function, and when using "normal" function pointers to catch lambda expressions you cannot use captures.
Todo:
This one needs thorough testing! Especially compact() and its dependencies.

Member Typedef Documentation

◆ ForEachCallback

template<class BASETYPE, uint16_t COUNT>
typedef void(* ItemCollection< BASETYPE, COUNT >::ForEachCallback) (BASETYPE &item, const void *context)

Type for callback method for forEach() method.

Parameters
itemCurrent item in iteration.
contextPointer to context that was passed to forEach() invocation.

Constructor & Destructor Documentation

◆ ItemCollection()

template<class BASETYPE, uint16_t COUNT>
ItemCollection< BASETYPE, COUNT >::ItemCollection ( void  )
inline

Constructor.

Member Function Documentation

◆ add()

template<class BASETYPE, uint16_t COUNT>
bool ItemCollection< BASETYPE, COUNT >::add ( BASETYPE &  item)
inline

Adds an item to the collection. This method does not enforce the item to be unique. See addUnique() if this is a requirement.

Parameters
itemItem to be added.
Returns
True if item was added successfully, false otherwise.

◆ addUnique()

template<class BASETYPE, uint16_t COUNT>
bool ItemCollection< BASETYPE, COUNT >::addUnique ( BASETYPE &  item)
inline

Adds an item to the collection. This method enforcse the item to be unique. See add() if duplicates should be allowed.

Parameters
itemItem to be added.
Returns
True if item was added successfully, false otherwise.

◆ compact()

template<class BASETYPE, uint16_t COUNT>
void ItemCollection< BASETYPE, COUNT >::compact ( void  )
inline

Compacts the internal data storage by filling "holes" with items from other positions. This can be useful after removing items from the collection to improve the performance of forEach() runs.

Warning
This operation affects the order of elements and may disturb ongoing forEach() runs.

◆ forEach()

template<class BASETYPE, uint16_t COUNT>
void ItemCollection< BASETYPE, COUNT >::forEach ( ForEachCallback  action,
const void *  context = nullptr 
)
inline

Iterates through all items in the collection and invokes the specified callback method on each item. The context is passed to each callback invocation to allow the caller passing information which needs to be specific for this forEach() run.

Parameters
actionCallback method to be called for each item.
contextPointer to context to be passed to each callback invocation.
Note
Removing items from the collection in context of the callback method is safe, but when adding items it is not guaranteed if they are part of this forEach() run or not.

◆ remove()

template<class BASETYPE, uint16_t COUNT>
void ItemCollection< BASETYPE, COUNT >::remove ( BASETYPE &  item)
inline

Removes an item from the collection. If there are duplicates, only one instance is removed.

Parameters
itemItem to be removed.
Note
Removing items creates "holes" inside the internal data structure which affect the performance of forEach() runs. These holes can be removed using the compact() method.