enumerator_sequence Class Template Reference
[Collections Library]

#include <comstl/collections/enumerator_sequence.hpp>

Inheritance diagram for enumerator_sequence:

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.

Parameters:

	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);

Note:: The iterator instances returned by begin() and end() are valid outside the lifetime of the collection instance from which they are obtained

Remarks:: 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:: comstl::collection_sequence

Examples:: by_library/com_utility/rot_functions/rot_functions.cpp.


Iteration
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_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.
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
Attributes
static size_type	quanta ()
Classes
class	iterator
	Iterator for the enumerator_sequence class. More...

Member Typedef Documentation

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_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.

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.

typedef iterator const_iterator

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.

Parameters:

	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

Note:: 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.

References COMSTL_ASSERT, and COMSTL_MESSAGE_ASSERT.

~enumerator_sequence ( ) throw () [inline]

Releases the adapted interface pointer.

References COMSTL_ASSERT.

Member Function Documentation

iterator begin ( ) const [inline]

Begins the iteration.

Returns:: An iterator representing the start of the sequence

Note:: 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.

References COMSTL_ASSERT.

iterator end ( ) const [inline]

Ends the iteration.