enumerator_sequence Class Template Reference
[Collections Library]

#include <comstl/collections/enumerator_sequence.hpp>

Inheritance diagram for enumerator_sequence:

stl_collection_tag collection_tag

List of all members.

Detailed Description

template<typename I, typename V, typename VP, typename R = V const&, typename CP = cloneable_cloning_policy<I>, size_t Q = 10>
class comstl::enumerator_sequence< I, V, VP, R, CP, Q >

A template for adapting COM enumerators to STL-compatible sequence iteration.

I Interface
V Value type
VP Value policy type
R Reference type. The type returned by the iterator's dereference operator. Defaults to V const&. To make it mutable, set to V&
CP Cloning policy type. Defaults to cloneable_cloning_policy<I>
Q Quanta. The number of elements retrieved from the enumerator with each invocation of Next(). Defaults to 10
The various parameterising types are used to stipulate the interface and the value type, and how they are to be handled.

For example, the following parameterisation defines a sequence operating over an IEnumGUID enumerator instance.

typedef enumerator_sequence<IEnumGUID
                          , GUID
                          , GUID_policy
                          , GUID const&
                          , forward_cloning_policy<IEnumGUID>
                          , 5
                          >    enum_sequence_t;

The value type is GUID and it is returned as a reference, as the GUID const& in fact.

The COMSTL type GUID_policy controls how the GUID instances are initialised, copied and destroyed.

The COMSTL type forward_cloning_policy allows the sequence to provide Forward Iterator semantics.

And the 5 indicates that the sequence should grab 5 values at a time, to save round trips to the enumerator.

This would be used as follows:

void dump_GUID(GUID const&);

LPENUMGUID        penGUIDs = . . .;       // Create an instance from wherever
enum_sequence_t   guids(penGUIDs, false); // Consume the reference

std::for_each(guids.begin(), guids.end(), dump_GUID);

The iterator instances returned by begin() and end() are valid outside the lifetime of the collection instance from which they are obtained
A detailed examination of the design and implementation of this class template is described in Chapters 28 and 29 of Extended STL, volume 1 (published by Addison-Wesley, June 2007).
See also:



typedef iterator const_iterator
 The non-mutating (const) iterator type.
iterator begin () const
 Begins the iteration.
iterator end () const
 Ends the iteration.

Public Types

Member Types
enum  { retrievalQuanta = Q }
 Retrieval quanta. More...
typedef I interface_type
 Interface type.
typedef V value_type
 Value type.
typedef value_policy_adaptor< VP > value_policy_type
 Value policy type.
typedef R reference
 Reference type.
typedef value_typepointer
 The mutating (non-const) pointer type.
typedef value_type const * const_pointer
 The non-mutating (const) pointer type.
typedef CP cloning_policy_type
 Cloning policy type.
 Iterator tag type.
typedef enumerator_sequence< I,
V, VP, R, CP, Q > 
 Type of the current parameterisation.
typedef class_type sequence_type
 Type of the current parameterisation.
typedef size_t size_type
 The size type.
typedef cs_ptrdiff_t difference_type
 The difference type.
typedef bool bool_type
 The Boolean type.

Public Member Functions

 enumerator_sequence (interface_type *i, bool_type bAddRef, size_type quanta=0, bool_type bReset=true)
 Conversion constructor.
 ~enumerator_sequence () throw ()
 Releases the adapted interface pointer.

Static Public Member Functions

static size_type quanta ()


class  iterator
 Iterator for the enumerator_sequence class. More...

Member Typedef Documentation

typedef I interface_type

Interface type.

typedef V value_type

Value type.

Value policy type.

typedef R reference

Reference type.

typedef value_type* pointer

The mutating (non-const) pointer type.

typedef value_type const* const_pointer

The non-mutating (const) pointer type.

typedef CP cloning_policy_type

Cloning policy type.

typedef cloning_policy_type::iterator_tag_type iterator_tag_type

Iterator tag type.

typedef enumerator_sequence<I, V, VP, R, CP, Q> class_type

Type of the current parameterisation.

Type of the current parameterisation.

typedef size_t size_type

The size type.

typedef cs_ptrdiff_t difference_type

The difference type.

typedef bool bool_type

The Boolean type.

The non-mutating (const) iterator type.

Member Enumeration Documentation

anonymous enum

Retrieval quanta.

Constructor & Destructor Documentation

enumerator_sequence ( interface_type i,
bool_type  bAddRef,
size_type  quanta = 0,
bool_type  bReset = true 
) [inline]

Conversion constructor.

i The enumeration interface pointer to adapt
bAddRef Causes a reference to be added if true, otherwise the sequence is deemed to sink, or consume, the interface pointer
quanta The actual quanta required for this instance. Must be <= Q. Defaults to 0, which causes it to be Q
bReset Determines whether the Reset() method is invoked on the enumerator instance upon construction. Defaults to true
This does not throw an exception, so it is safe to be used to "eat" the reference. The only possible exception to this is if COMSTL_ASSERT() or COMSTL_MESSAGE_ASSERT(), which are used to validate that the given quanta size is within the limit specified in the specialisation, has been redefined to throw an exception. But since precondition violations are no more recoverable than any others (see the article "The Nuclear Reactor and the Deep Space Probe"), this does not represent a concerning contradiction to the no-throw status of the constructor.


~enumerator_sequence (  )  throw () [inline]

Releases the adapted interface pointer.


Member Function Documentation

iterator begin (  )  const [inline]

Begins the iteration.

An iterator representing the start of the sequence
The first time this is called, the iterated range represented by [begin(), end()) directly uses that of the enumerator interface pointer passed to the constructor. When specialised with cloneable_cloning_policy and forward_cloning_policy policies, all subsequent calls to begin() will use a cloned enumerator instance, retrieved via I::Clone(). If the enumerator instance is not cloneable, then begin() will throw an instance of clone_failure on all subsequent invocations.


iterator end (  )  const [inline]

Ends the iteration.

An iterator representing the end of the sequence


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

Generated on Thu Jun 10 08:58:25 2010 for STLSoft by  doxygen 1.5.6