#include <CCompoundEventSegment.h>
class CCompoundEventSegement : public CEventSegment {virtual void initialize();virtual void clear();virtual void disable();virtual size_t read(void* pBuffer, size_t maxwords);virtual void onBegin();virtual void onEnd();virtual void onPause();virtual void onResume();void AddEventSegment(CEventSegment* pSegment);void DeleteEventSegment(CEventSegment* pSegment);virtual const bool isComposite();EventSegmentIterator begin();EventSegmentIterator end();const size_t size();size_t leafCount();size_t fullCount();void visit(CVisitor& visitor);}
CCompoundEventSegemnt provides an ordered
container for event segment objects (or rather pointers to event
segment objects). Since a CCompoundEventSegment
itself is an event segment you can build an arbitrarily deep hierarchy
of event segments using this class.
A rich set of facilities for navigating the event segment hierarchy is provided though normally this hierarchy gets built at program initialization time and is fixed throughout the lifetime of the program. Navigation models include iteration and visitation. See Types and Public Data for information about the class scoped data types that support these models.
Event segments also provide a mechanism to determine if they are
containers via the isComposite member function.
virtual void initialize();
Part of the event segment interface. Does a deep initialization
of all events segments in the compound event segment. This is
done by calling the initialize
member on each element in the container. This implies that
if an element of the container is itself a compound event
segment, it's children will be recursively initialized.
virtual void clear();
Part of the event segment interface. Does a deep clear of all
event segments. This is
done by calling the clear
member on each element in the container. This implies that
if an element of the container is itself a compound event
segment, it's children will be recursively cleared.
virtual void disable();
Part of the event segment interface. Does a deep disable of all
event segments. This is
done by calling the disable
member on each element in the container. This implies that
if an element of the container is itself a compound event
segment, it's children will be recursively disabled.
virtual size_t read(void* pBuffer, size_t maxwords);
Part of the event segment interface. Does a deep read of all
event segments. This is
done by calling the read
member on each element in the container. This implies that
if an element of the container is itself a compound event
segment, it's children will be recursively read.
pBuffer points to the buffer into which
data should be read. maxwords is the
maximum number of words that can still fit in that buffer.
The method returns the number of words that were read by this
segment.
virtual void onBegin();
Invokes onBegin for all
event segments in the compound. If there are nested segments,
traversal is depth first.
virtual void onEnd();
Invokes onEnd for all
event segments in the compound. If there are nested segments,
traversal is depth first.
virtual void onPause();
Invokes onPause for all
event segments in the compound. If there are nested segments,
traversal is depth first.
virtual void onResume();
Invokes onResume for all
event segments in the compound. If there are nested segments,
traversal is depth first.
void AddEventSegment(CEventSegment* pSegment);
Adds an event segment pSegment
to the end of the ordered container of
event segments in the compound. Very bad things will happen if
pSegment's lifetime is not at least that of
the event segment.
void DeleteEventSegment(CEventSegment* pSegment);
If pSegment is one of the immediate
children of the object, it is removed from the container.
If not, this is a no-op. Please note that this is not a deep
delete. If pSegment is actually a child
of some compound event segment in the container, it will not
be found and therefore not removed.
pSegment is removed from the container.
It is up to the calling software, if appropriate, to destroy
the actual object.
virtual const bool isComposite();
This returns true. The member function isComposite
is provided in all event segments. It is true if the object
implements the interface of the compound event segment.
EventSegmentIterator begin();
Returns a begin of iteration iterator. See "Types and Public Data"
below for more about iterators. See as well end
below for typical usage. This iterator is a shallow iterator.
EventSegmentIterator end();
Returns an iterator that points off the end of the container. This can be used to determine when the iterator has visited all members of the container. The function below shows a typical usage.
CCompoundEventSegment es;
...
CCompoundEventSegment::EventSegmentIterator p = es.begin();
while (p != es.end()) {
CEventSegment *pSegment = *p;
//
// Do something with pSegment:
...
p++;
}
const size_t size();
Returns the number of elements in the event segment container. This is a shallow count.
size_t leafCount();
Returns the number of 'terminal' nodes in the hierarchy. A
terminal node is one for which isComposite
returns false. This is a deep count.
size_t fullCount();
Returns the total number of nodes in the hiearchy. This is a deep count.
void visit(CVisitor& visitor);
Visits each node in the hieararchy and invokes the visitor
at each node at this level of the hierarchy. If deep visitation
is required, then whenever the visitor is handed a node for which
isComposite is true, it should invoke
this method on that node with itself as a parameter.
For more on the visitor class, see "Types and public data". For a recipe for doing recursive visitation, see "EXAMPLES"
This class provides an iterator for its container;
CCompoundEventSegment::EventSegmentIterator.
This is a pointer like object. When dereferenced the iterator
returns a CEventSegment* for a segment that is in the
container. Increment moves the 'pointer' to the next item
in the container (shallow iteration).
The class provides an abstract base class on which Visitors can be
built: CCompoundEventSegment::CVisitor.
The definition of this class is shown below:
The idea is that you would derive a class from that and
invoke the visit method with an object
of that class to do something to all nodes in the container.
This section shows how to do deep iteration both with visitors and with iterators. The key is that whenever a compound is found iteration or visitation is done recursively on that compond.
Example 1. Deep iteration of CCompondEventSegment elements
/*
Do something to all leaf nodes of the event segment
hierarchy
*/
void doSomething(CCompoundEventSegment* pSegment)
{
CCompoundEventSegment::EventSegmentIterator p = pSegment->begin();
while (p != pSegment>end()) {
CEventSegment* pSeg = *p;
if (pSeg>isComposite()) {
doSomething(pSeg); // Recurse to go deep.
}
else {
// Do whatever needs doing here....
}
p++;
}
}
Example 2. Deep visitation of CCompoundEventSegment elements
class MyVisitor : public CCompoundEventSegment::CVisitor
{
virtual void operator()(CEventSegment* pSeg)
{
if (pSeg>isCompound()) {
pSeg>visit(*this);
}
else {
// Do what needs doing to terminal nodes....
}
}
};
...
CCompoundEventSegment segment;
MyVisitor visitor;
segment.visit(visitor); // Visitor ensures deep visitation.