collection_sequence Class Template Reference
[Collections Library]

#include <comstl/collections/collection_sequence.hpp>

Inheritance diagram for collection_sequence:

List of all members.

---

Detailed Description

template<typename CI, typename EI, typename V, typename VP, typename R = V const&, typename CP = input_cloning_policy<EI>, size_t Q = 8, typename EAP = new_enum_property_policy<CI>>
class comstl::collection_sequence< CI, EI, V, VP, R, CP, Q, EAP >

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

Parameters:

	I	Interface
	V	Value type
	VP	Value policy type
	R	Reference type. Defaults to V const&
	CP	Cloning policy type. Defaults to comstl::input_cloning_policy
	Q	Quanta. Defaults to 8
	EAP	Enumerate acquisition policy type. Defaults to comstl::new_enum_property_policy

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 a notional IGUIDCollection collection instance.

typedef collection_sequence<IGUIDCollection
                          , IEnumGUID
                          , GUID
                          , GUID_policy
                          , GUID const&
                          , forward_cloning_policy<IEnumGUID>
                          , 5
                          >    collection_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 five values at a time, to save round trips to the enumerator.

This would be used as follows:

  void dump_GUID(GUID const&);

  IGUIDCollection       *penGUIDs = . . .;      // Create an instance from wherever
  collection_sequence_t guids(penGUIDs, false); // Eat 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::enumerator_sequence

Member Types
enum	{ retrievalQuanta = enumerator_sequence_type::retrievalQuanta }
	Retrieval quanta. More...
typedef CI	collection_interface_type
	Collection interface type.
typedef enumerator_sequence_type::interface_type	enumerator_interface_type
	Enumerator interface type.
typedef enumerator_sequence_type::value_type	value_type
	Value type.
typedef enumerator_sequence_type::value_policy_type	value_policy_type
	Value policy type.
typedef enumerator_sequence_type::reference	reference
	Reference type.
typedef enumerator_sequence_type::pointer	pointer
	The mutating (non-const) pointer type.
typedef enumerator_sequence_type::const_pointer	const_pointer
	The non-mutating (const) pointer type.
typedef enumerator_sequence_type::iterator	iterator
	The mutating (non-const) iterator type.
typedef enumerator_sequence_type::const_iterator	const_iterator
	The non-mutating (const) iterator type.
typedef enumerator_sequence_type::cloning_policy_type	cloning_policy_type
	Cloning policy type.
typedef enumerator_sequence_type::iterator_tag_type	iterator_tag_type
	Iterator tag type.
typedef EAP	enumerator_acquisition_policy_type
	The policy for acquiring the enumerator from the collection.
typedef collection_sequence < CI, EI, V, VP, R, CP, Q, EAP >	class_type
	Type of the current parameterisation.
typedef enumerator_sequence_type::size_type	size_type
	The size type.
typedef enumerator_sequence_type::difference_type	difference_type
	The difference type.
Public Member Functions
	collection_sequence (collection_interface_type *i, bool bAddRef, size_type quanta=0)
	Conversion constructor.
	~collection_sequence () throw ()
	Releases the adapted interface pointer.
Iteration
iterator	begin () const
	Begins the iteration.
iterator	end () const
	Ends the iteration.
Capacity
size_type	size () const
	Returns the number of items in the collection.

---

Member Typedef Documentation

typedef CI collection_interface_type

Collection interface type.

typedef enumerator_sequence_type::interface_type enumerator_interface_type

Enumerator interface type.

typedef enumerator_sequence_type::value_type value_type

Value type.

typedef enumerator_sequence_type::value_policy_type value_policy_type

Value policy type.

typedef enumerator_sequence_type::reference reference

Reference type.

typedef enumerator_sequence_type::pointer pointer

The mutating (non-const) pointer type.

typedef enumerator_sequence_type::const_pointer const_pointer

The non-mutating (const) pointer type.

typedef enumerator_sequence_type::iterator iterator

The mutating (non-const) iterator type.

typedef enumerator_sequence_type::const_iterator const_iterator

The non-mutating (const) iterator type.

typedef enumerator_sequence_type::cloning_policy_type cloning_policy_type

Cloning policy type.

typedef enumerator_sequence_type::iterator_tag_type iterator_tag_type

Iterator tag type.

typedef EAP enumerator_acquisition_policy_type

The policy for acquiring the enumerator from the collection.

typedef collection_sequence<CI, EI, V, VP, R, CP, Q, EAP> class_type

Type of the current parameterisation.

typedef enumerator_sequence_type::size_type size_type

The size type.

typedef enumerator_sequence_type::difference_type difference_type

The difference type.

---

Member Enumeration Documentation

anonymous enum

Retrieval quanta.

---

Constructor & Destructor Documentation

collection_sequence	(	collection_interface_type *	i,
		bool	bAddRef,
		size_type	quanta = 0
	)			[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

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(), which is 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.

~collection_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

References COMSTL_ASSERT.

iterator end

(

)

const [inline]

Ends the iteration.

Returns:

An iterator representing the end of the sequence

References COMSTL_ASSERT.

size_type size

(

)

const [inline]

Returns the number of items in the collection.

    IGUIDCollection       *penGUIDs = . . .;        // Create an instance from wherever
    collection_sequence_t guids(penGUIDs, false);   // Eat the reference
    size_t                numItems = guids.size();  // Evaluate the number of elements in the collection

Note:

This method will not compile for collection interfaces that do not contain the get_Count method

References COMSTL_ASSERT.

---

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

• comstl/collections/collection_sequence.hpp