You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
458 lines
17 KiB
458 lines
17 KiB
/* /////////////////////////////////////////////////////////////////////////
|
|
* File: comstl/collections/collection_sequence.hpp (originally MOEnSeq.h, ::SynesisCom)
|
|
*
|
|
* Purpose: STL sequence for COM collection interfaces.
|
|
*
|
|
* Created: 17th September 1998
|
|
* Updated: 3rd February 2012
|
|
*
|
|
* Thanks: To Eduardo Bezerra and Vivi Orunitia for reporting
|
|
* incompatibilities with Borland's 5.82 (Turbo C++). The awful
|
|
* preprocessor hack around retrievalQuanta are the result. ;)
|
|
*
|
|
* Home: http://stlsoft.org/
|
|
*
|
|
* Copyright (c) 1998-2012, Matthew Wilson and Synesis Software
|
|
* All rights reserved.
|
|
*
|
|
* Redistribution and use in source and binary forms, with or without
|
|
* modification, are permitted provided that the following conditions are met:
|
|
*
|
|
* - Redistributions of source code must retain the above copyright notice, this
|
|
* list of conditions and the following disclaimer.
|
|
* - Redistributions in binary form must reproduce the above copyright notice,
|
|
* this list of conditions and the following disclaimer in the documentation
|
|
* and/or other materials provided with the distribution.
|
|
* - Neither the name(s) of Matthew Wilson and Synesis Software nor the names of
|
|
* any contributors may be used to endorse or promote products derived from
|
|
* this software without specific prior written permission.
|
|
*
|
|
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
|
|
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
* POSSIBILITY OF SUCH DAMAGE.
|
|
*
|
|
* ////////////////////////////////////////////////////////////////////// */
|
|
|
|
|
|
/** \file comstl/collections/collection_sequence.hpp
|
|
*
|
|
* \brief [C++ only] Definition of the comstl::collection_sequence
|
|
* collection class template
|
|
* (\ref group__library__collections "Collections" Library).
|
|
*/
|
|
|
|
#ifndef COMSTL_INCL_COMSTL_COLLECTIONS_HPP_COLLECTION_SEQUENCE
|
|
#define COMSTL_INCL_COMSTL_COLLECTIONS_HPP_COLLECTION_SEQUENCE
|
|
|
|
#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
|
|
# define COMSTL_VER_COMSTL_COLLECTIONS_HPP_COLLECTION_SEQUENCE_MAJOR 6
|
|
# define COMSTL_VER_COMSTL_COLLECTIONS_HPP_COLLECTION_SEQUENCE_MINOR 1
|
|
# define COMSTL_VER_COMSTL_COLLECTIONS_HPP_COLLECTION_SEQUENCE_REVISION 10
|
|
# define COMSTL_VER_COMSTL_COLLECTIONS_HPP_COLLECTION_SEQUENCE_EDIT 104
|
|
#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */
|
|
|
|
/* /////////////////////////////////////////////////////////////////////////
|
|
* Compatibility
|
|
*/
|
|
|
|
/*
|
|
[Incompatibilies-start]
|
|
STLSOFT_COMPILER_IS_WATCOM:
|
|
[Incompatibilies-end]
|
|
*/
|
|
|
|
/* /////////////////////////////////////////////////////////////////////////
|
|
* Includes
|
|
*/
|
|
|
|
#ifndef COMSTL_INCL_COMSTL_H_COMSTL
|
|
# include <comstl/comstl.h>
|
|
#endif /* !COMSTL_INCL_COMSTL_H_COMSTL */
|
|
#ifndef COMSTL_INCL_COMSTL_UTIL_H_REFCOUNT_FUNCTIONS
|
|
# include <comstl/util/refcount_functions.h>
|
|
#endif /* !COMSTL_INCL_COMSTL_UTIL_H_REFCOUNT_FUNCTIONS */
|
|
#ifndef COMSTL_INCL_COMSTL_COLLECTIONS_HPP_ENUMERATION_POLICIES
|
|
# include <comstl/collections/enumeration_policies.hpp>
|
|
#endif /* !COMSTL_INCL_COMSTL_COLLECTIONS_HPP_ENUMERATION_POLICIES */
|
|
#ifndef COMSTL_INCL_COMSTL_UTIL_HPP_INTERFACE_TRAITS
|
|
# include <comstl/util/interface_traits.hpp>
|
|
#endif /* !COMSTL_INCL_COMSTL_UTIL_HPP_INTERFACE_TRAITS */
|
|
#ifdef STLSOFT_CF_EXCEPTION_SUPPORT
|
|
# ifndef COMSTL_INCL_COMSTL_ERROR_HPP_EXCEPTIONS
|
|
# include <comstl/error/exceptions.hpp>
|
|
# endif /* !COMSTL_INCL_COMSTL_ERROR_HPP_EXCEPTIONS */
|
|
#endif /* STLSOFT_CF_EXCEPTION_SUPPORT */
|
|
#ifndef COMSTL_INCL_COMSTL_COLLECTIONS_HPP_ENUMERATOR_SEQUENCE
|
|
# include <comstl/collections/enumerator_sequence.hpp>
|
|
#endif /* !COMSTL_INCL_COMSTL_COLLECTIONS_HPP_ENUMERATOR_SEQUENCE */
|
|
#ifndef STLSOFT_INCL_STLSOFT_UTIL_STD_HPP_ITERATOR_HELPER
|
|
# include <stlsoft/util/std/iterator_helper.hpp>
|
|
#endif /* !STLSOFT_INCL_STLSOFT_UTIL_STD_HPP_ITERATOR_HELPER */
|
|
#ifndef STLSOFT_INCL_STLSOFT_COLLECTIONS_UTIL_HPP_COLLECTIONS
|
|
# include <stlsoft/collections/util/collections.hpp>
|
|
#endif /* !STLSOFT_INCL_STLSOFT_COLLECTIONS_UTIL_HPP_COLLECTIONS */
|
|
|
|
#ifndef STLSOFT_INCL_ALGORITHM
|
|
# define STLSOFT_INCL_ALGORITHM
|
|
# include <algorithm>
|
|
#endif /* !STLSOFT_INCL_ALGORITHM */
|
|
|
|
#ifdef STLSOFT_UNITTEST
|
|
# include <comstl/util/value_policies.hpp>
|
|
# if !defined(STLSOFT_COMPILER_IS_DMC)
|
|
# include "./unittest/_recls_COM_decl_.h"
|
|
# endif /* compiler */
|
|
# include <stdio.h>
|
|
#endif /* STLSOFT_UNITTEST */
|
|
|
|
/* /////////////////////////////////////////////////////////////////////////
|
|
* Namespace
|
|
*/
|
|
|
|
#ifndef _COMSTL_NO_NAMESPACE
|
|
# if defined(_STLSOFT_NO_NAMESPACE) || \
|
|
defined(STLSOFT_DOCUMENTATION_SKIP_SECTION)
|
|
/* There is no stlsoft namespace, so must define ::comstl */
|
|
namespace comstl
|
|
{
|
|
# else
|
|
/* Define stlsoft::comstl_project */
|
|
|
|
namespace stlsoft
|
|
{
|
|
|
|
namespace comstl_project
|
|
{
|
|
|
|
# endif /* _STLSOFT_NO_NAMESPACE */
|
|
#endif /* !_COMSTL_NO_NAMESPACE */
|
|
|
|
/* /////////////////////////////////////////////////////////////////////////
|
|
* Classes
|
|
*/
|
|
|
|
/** \brief A template for adapting COM collections to STL-compatible sequence iteration.
|
|
*
|
|
* \ingroup group__library__collections
|
|
*
|
|
* \param I Interface
|
|
* \param V Value type
|
|
* \param VP Value policy type
|
|
* \param R Reference type. Defaults to <code>V const&</code>
|
|
* \param CP Cloning policy type. Defaults to comstl::input_cloning_policy
|
|
* \param Q Quanta. Defaults to 8
|
|
* \param 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 <b>IGUIDCollection</b> collection instance.
|
|
*
|
|
\code
|
|
typedef collection_sequence<IGUIDCollection
|
|
, IEnumGUID
|
|
, GUID
|
|
, GUID_policy
|
|
, GUID const&
|
|
, forward_cloning_policy<IEnumGUID>
|
|
, 5
|
|
> collection_sequence_t;
|
|
\endcode
|
|
*
|
|
* The value type is <b>GUID</b> and it is returned as a reference, as
|
|
* the <b>GUID const&</b> in fact.
|
|
*
|
|
* The \ref group__project__comstl type <b>GUID_policy</b> controls how the <b>GUID</b>
|
|
* instances are initialised, copied and destroyed.
|
|
*
|
|
* The \ref group__project__comstl type forward_cloning_policy allows the sequence to provide
|
|
* <a href = "http://sgi.com/tech/stl/ForwardIterator.html">Forward Iterator</a>
|
|
* semantics.
|
|
*
|
|
* And the <b>5</b> indicates that the sequence should grab five values at a time,
|
|
* to save round trips to the enumerator.
|
|
*
|
|
* This would be used as follows:
|
|
*
|
|
\code
|
|
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);
|
|
\endcode
|
|
*
|
|
* \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
|
|
* <a href="http://www.extendedstl.com/"><b>Extended STL, volume 1</b></a>
|
|
* (published by Addison-Wesley, June 2007).
|
|
*
|
|
* \sa comstl::enumerator_sequence
|
|
*/
|
|
// [[synesis:class:collection: comstl::collection_sequence<T<CI>, T<EI>, T<V>, T<VP>, T<R>, T<CP>, size_t, T<EAP>>]]
|
|
template< ss_typename_param_k CI /* Collection interface */
|
|
, ss_typename_param_k EI /* Enumerator interface */
|
|
, ss_typename_param_k V /* Value type */
|
|
, ss_typename_param_k VP /* Value policy type */
|
|
, ss_typename_param_k R = V const& /* Reference type */
|
|
, ss_typename_param_k CP = input_cloning_policy<EI> /* Cloning policy type */
|
|
, cs_size_t Q = 8 /* Quanta */
|
|
, ss_typename_param_k EAP = new_enum_property_policy<CI> /* Policy for acquiring the enumerator from the collection */
|
|
>
|
|
class collection_sequence
|
|
: public stlsoft_ns_qual(stl_collection_tag)
|
|
{
|
|
/// \name Member Types
|
|
/// @{
|
|
private:
|
|
typedef enumerator_sequence<EI, V, VP, R, CP, Q> enumerator_sequence_type;
|
|
public:
|
|
/// \brief Collection interface type
|
|
typedef CI collection_interface_type;
|
|
/// \brief Enumerator interface type
|
|
typedef ss_typename_type_k enumerator_sequence_type::interface_type enumerator_interface_type;
|
|
/// \brief Value type
|
|
typedef ss_typename_type_k enumerator_sequence_type::value_type value_type;
|
|
/// \brief Value policy type
|
|
typedef ss_typename_type_k enumerator_sequence_type::value_policy_type value_policy_type;
|
|
/// \brief Reference type
|
|
typedef ss_typename_type_k enumerator_sequence_type::reference reference;
|
|
#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
|
|
typedef ss_typename_type_k enumerator_sequence_type::reference_type reference_type; // For backwards compatiblity
|
|
#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */
|
|
/// \brief The mutating (non-const) pointer type
|
|
typedef ss_typename_type_k enumerator_sequence_type::pointer pointer;
|
|
/// \brief The non-mutating (const) pointer type
|
|
typedef ss_typename_type_k enumerator_sequence_type::const_pointer const_pointer;
|
|
/// \brief The mutating (non-const) iterator type
|
|
typedef ss_typename_type_k enumerator_sequence_type::iterator iterator;
|
|
/// \brief The non-mutating (const) iterator type
|
|
typedef ss_typename_type_k enumerator_sequence_type::const_iterator const_iterator;
|
|
/// \brief Cloning policy type
|
|
typedef ss_typename_type_k enumerator_sequence_type::cloning_policy_type cloning_policy_type;
|
|
/// \brief Iterator tag type
|
|
typedef ss_typename_type_k enumerator_sequence_type::iterator_tag_type iterator_tag_type;
|
|
#ifdef STLSOFT_COMPILER_IS_BORLAND
|
|
# define retrievalQuanta Q
|
|
#else /* ? compiler */
|
|
/// \brief Retrieval quanta
|
|
enum { retrievalQuanta = enumerator_sequence_type::retrievalQuanta };
|
|
#endif /* compiler */
|
|
/// \brief The policy for acquiring the enumerator from the collection
|
|
typedef EAP enumerator_acquisition_policy_type;
|
|
/// \brief Type of the current parameterisation
|
|
typedef collection_sequence<CI, EI, V, VP, R, CP, Q, EAP> class_type;
|
|
/// \brief The size type
|
|
typedef ss_typename_type_k enumerator_sequence_type::size_type size_type;
|
|
/// \brief The difference type
|
|
typedef ss_typename_type_k enumerator_sequence_type::difference_type difference_type;
|
|
/// @}
|
|
|
|
public:
|
|
/// \brief Conversion constructor
|
|
///
|
|
/// \param i The enumeration interface pointer to adapt
|
|
/// \param bAddRef Causes a reference to be added if \c true, otherwise the sequence is deemed to <i>sink</i>, or consume, the interface pointer
|
|
/// \param 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.
|
|
collection_sequence(collection_interface_type *i, cs_bool_t bAddRef, size_type quanta = 0)
|
|
: m_i(i)
|
|
, m_quanta(validate_quanta_(quanta))
|
|
{
|
|
COMSTL_ASSERT(NULL != i);
|
|
COMSTL_MESSAGE_ASSERT("Cannot set a quantum that exceeds the value specified in the template specialisation", quanta <= retrievalQuanta); // Could have named these things better!
|
|
|
|
if(bAddRef)
|
|
{
|
|
m_i->AddRef();
|
|
}
|
|
|
|
COMSTL_ASSERT(is_valid());
|
|
}
|
|
/// \brief Releases the adapted interface pointer
|
|
~collection_sequence() stlsoft_throw_0()
|
|
{
|
|
COMSTL_ASSERT(is_valid());
|
|
|
|
m_i->Release();
|
|
}
|
|
|
|
/// \name Iteration
|
|
/// @{
|
|
public:
|
|
/// \brief Begins the iteration
|
|
///
|
|
/// \return An iterator representing the start of the sequence
|
|
iterator begin() const
|
|
{
|
|
COMSTL_ASSERT(is_valid());
|
|
|
|
LPUNKNOWN punkEnum;
|
|
HRESULT hr = enumerator_acquisition_policy_type::acquire(m_i, &punkEnum);
|
|
|
|
if(SUCCEEDED(hr))
|
|
{
|
|
enumerator_interface_type *ei;
|
|
|
|
hr = punkEnum->QueryInterface(IID_traits<enumerator_interface_type>::iid(), reinterpret_cast<void**>(&ei));
|
|
|
|
punkEnum->Release();
|
|
|
|
if(SUCCEEDED(hr))
|
|
{
|
|
COMSTL_ASSERT(is_valid());
|
|
|
|
return enumerator_sequence_type(ei, false, m_quanta).begin();
|
|
}
|
|
else
|
|
{
|
|
#ifdef STLSOFT_CF_EXCEPTION_SUPPORT
|
|
COMSTL_ASSERT(is_valid());
|
|
|
|
STLSOFT_THROW_X(com_exception("the enumerator does not provide the requested interface", hr));
|
|
#endif /* STLSOFT_CF_EXCEPTION_SUPPORT */
|
|
}
|
|
}
|
|
else
|
|
{
|
|
#ifdef STLSOFT_CF_EXCEPTION_SUPPORT
|
|
COMSTL_ASSERT(is_valid());
|
|
|
|
STLSOFT_THROW_X(com_exception("enumerator could not be elicited from the collection", hr));
|
|
#endif /* STLSOFT_CF_EXCEPTION_SUPPORT */
|
|
}
|
|
|
|
COMSTL_ASSERT(is_valid());
|
|
|
|
return iterator();
|
|
}
|
|
/// \brief Ends the iteration
|
|
///
|
|
/// \return An iterator representing the end of the sequence
|
|
iterator end() const
|
|
{
|
|
COMSTL_ASSERT(is_valid());
|
|
|
|
return iterator();
|
|
}
|
|
/// @}
|
|
|
|
/// \name Capacity
|
|
/// @{
|
|
public:
|
|
/** \brief Returns the number of items in the collection
|
|
*
|
|
\code
|
|
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
|
|
\endcode
|
|
*
|
|
*
|
|
* \note This method will not compile for collection interfaces
|
|
* that do not contain the get_Count method
|
|
*/
|
|
size_type size() const
|
|
{
|
|
COMSTL_ASSERT(is_valid());
|
|
|
|
ULONG count;
|
|
HRESULT hr = m_i->get_Count(&count);
|
|
|
|
COMSTL_ASSERT(is_valid());
|
|
|
|
return SUCCEEDED(hr) ? count : 0;
|
|
}
|
|
/// @}
|
|
|
|
/// \name Invariant
|
|
/// @{
|
|
private:
|
|
cs_bool_t is_valid() const
|
|
{
|
|
if(NULL == m_i)
|
|
{
|
|
return false;
|
|
}
|
|
|
|
return true;
|
|
}
|
|
/// @}
|
|
|
|
// Implementation
|
|
private:
|
|
static size_type validate_quanta_(size_type quanta)
|
|
{
|
|
COMSTL_MESSAGE_ASSERT("Cannot set a quantum that exceeds the value specified in the template specialisation", quanta <= retrievalQuanta); // Could have named these things better!
|
|
|
|
if( 0 == quanta ||
|
|
quanta > retrievalQuanta)
|
|
{
|
|
quanta = retrievalQuanta;
|
|
}
|
|
|
|
return quanta;
|
|
}
|
|
|
|
// Members
|
|
private:
|
|
collection_interface_type *m_i;
|
|
size_type const m_quanta;
|
|
|
|
// Not to be implemented
|
|
private:
|
|
collection_sequence(class_type const&);
|
|
class_type const& operator =(class_type const&);
|
|
};
|
|
|
|
////////////////////////////////////////////////////////////////////////////
|
|
// Compiler compatibility
|
|
|
|
#ifdef STLSOFT_COMPILER_IS_BORLAND
|
|
# undef retrievalQuanta
|
|
#endif /* compiler */
|
|
|
|
////////////////////////////////////////////////////////////////////////////
|
|
// Unit-testing
|
|
|
|
#ifdef STLSOFT_UNITTEST
|
|
# include "./unittest/collection_sequence_unittest_.h"
|
|
#endif /* STLSOFT_UNITTEST */
|
|
|
|
/* ////////////////////////////////////////////////////////////////////// */
|
|
|
|
#ifndef _COMSTL_NO_NAMESPACE
|
|
# if defined(_STLSOFT_NO_NAMESPACE) || \
|
|
defined(STLSOFT_DOCUMENTATION_SKIP_SECTION)
|
|
} // namespace comstl
|
|
# else
|
|
} // namespace stlsoft::comstl_project
|
|
} // namespace stlsoft
|
|
# endif /* _STLSOFT_NO_NAMESPACE */
|
|
#endif /* !_COMSTL_NO_NAMESPACE */
|
|
|
|
/* ////////////////////////////////////////////////////////////////////// */
|
|
|
|
#endif /* !COMSTL_INCL_COMSTL_COLLECTIONS_HPP_COLLECTION_SEQUENCE */
|
|
|
|
/* ///////////////////////////// end of file //////////////////////////// */
|