/* ///////////////////////////////////////////////////////////////////////// * File: comstl/collections/enumerator_sequence.hpp (originally MOEnSeq.h, ::SynesisCom) * * Purpose: STL sequence for IEnumXXXX enumerator 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/enumerator_sequence.hpp * * \brief [C++ only] Definition of the comstl::enumerator_sequence * collection class template * (\ref group__library__collections "Collections" Library). */ #ifndef COMSTL_INCL_COMSTL_COLLECTIONS_HPP_ENUMERATOR_SEQUENCE #define COMSTL_INCL_COMSTL_COLLECTIONS_HPP_ENUMERATOR_SEQUENCE #ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION # define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATOR_SEQUENCE_MAJOR 6 # define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATOR_SEQUENCE_MINOR 1 # define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATOR_SEQUENCE_REVISION 4 # define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATOR_SEQUENCE_EDIT 251 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ /* ///////////////////////////////////////////////////////////////////////// * Compatibility */ /* [Incompatibilies-start] STLSOFT_COMPILER_IS_WATCOM: [Incompatibilies-end] */ /* ///////////////////////////////////////////////////////////////////////// * Includes */ #ifndef COMSTL_INCL_COMSTL_H_COMSTL # include #endif /* !COMSTL_INCL_COMSTL_H_COMSTL */ #ifndef COMSTL_INCL_COMSTL_COLLECTIONS_HPP_ENUMERATION_POLICIES # include #endif /* !COMSTL_INCL_COMSTL_COLLECTIONS_HPP_ENUMERATION_POLICIES */ #ifndef STLSOFT_INCL_STLSOFT_UTIL_STD_HPP_ITERATOR_HELPER # include #endif /* !STLSOFT_INCL_STLSOFT_UTIL_STD_HPP_ITERATOR_HELPER */ #ifndef STLSOFT_INCL_STLSOFT_COLLECTIONS_UTIL_HPP_COLLECTIONS # include #endif /* !STLSOFT_INCL_STLSOFT_COLLECTIONS_UTIL_HPP_COLLECTIONS */ #ifndef STLSOFT_INCL_STLSOFT_META_HPP_CAPABILITIES # include #endif /* !STLSOFT_INCL_STLSOFT_META_HPP_CAPABILITIES */ #ifdef STLSOFT_CF_TEMPLATE_PARTIAL_SPECIALISATION_SUPPORT # ifndef STLSOFT_INCL_STLSOFT_META_HPP_BASE_TYPE_TRAITS # include # endif /* !STLSOFT_INCL_STLSOFT_META_HPP_BASE_TYPE_TRAITS */ # ifndef STLSOFT_INCL_STLSOFT_META_HPP_SELECT_FIRST_TYPE_IF # include # endif /* !STLSOFT_INCL_STLSOFT_META_HPP_SELECT_FIRST_TYPE_IF */ #endif /* !STLSOFT_CF_TEMPLATE_PARTIAL_SPECIALISATION_SUPPORT */ #ifndef STLSOFT_INCL_ALGORITHM # define STLSOFT_INCL_ALGORITHM # include #endif /* !STLSOFT_INCL_ALGORITHM */ #ifdef STLSOFT_UNITTEST # include # if !defined(STLSOFT_COMPILER_IS_DMC) # include "./unittest/_recls_COM_decl_.h" # endif /* compiler */ # if !defined(STLSOFT_COMPILER_IS_COMO) # include # endif /* compiler */ #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 enumerators 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. The type returned by the iterator's dereference * operator. Defaults to V const&. To make it mutable, set to * V& * \param CP Cloning policy type. Defaults to cloneable_cloning_policy<I> * \param 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. * \code typedef enumerator_sequence , 5 > enum_sequence_t; \endcode * * The value type is GUID and it is returned as a reference, as * the GUID const& in fact. * * The \ref group__project__comstl type * GUID_policy controls how the * GUID instances are initialised, copied and * destroyed. * * The \ref group__project__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: * \code 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); \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 * Extended STL, volume 1 * (published by Addison-Wesley, June 2007). * * \sa comstl::collection_sequence */ template< ss_typename_param_k I /* 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 = cloneable_cloning_policy /* Cloning policy type */ , cs_size_t Q = 10 /* Quanta */ > class enumerator_sequence : public stlsoft_ns_qual(stl_collection_tag) { /// \name Member Types /// @{ public: /// \brief Interface type typedef I interface_type; /// \brief Value type typedef V value_type; /// \brief Value policy type typedef value_policy_adaptor value_policy_type; /// \brief Reference type typedef R reference; #ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION typedef R reference_type; // For backwards compatiblity #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ /// \brief The mutating (non-const) pointer type #if defined(STLSOFT_META_HAS_SELECT_FIRST_TYPE_IF) && \ !defined(STLSOFT_COMPILER_IS_BORLAND) typedef ss_typename_type_k stlsoft_ns_qual(select_first_type_if)< value_type const* , value_type* , stlsoft_ns_qual(base_type_traits)::is_const >::type pointer; #else /* ? STLSOFT_META_HAS_SELECT_FIRST_TYPE_IF */ typedef value_type* pointer; #endif /* !STLSOFT_META_HAS_SELECT_FIRST_TYPE_IF */ /// \brief The non-mutating (const) pointer type typedef value_type const* const_pointer; /// \brief Cloning policy type typedef CP cloning_policy_type; /// \brief Iterator tag type typedef ss_typename_type_k cloning_policy_type::iterator_tag_type iterator_tag_type; #ifdef STLSOFT_COMPILER_IS_BORLAND # define retrievalQuanta Q #else /* ? compiler */ /// \brief Retrieval quanta enum { retrievalQuanta = Q }; #endif /* compiler */ /// \brief Type of the current parameterisation typedef enumerator_sequence class_type; /// \brief Type of the current parameterisation typedef class_type sequence_type; /// \brief The size type typedef cs_size_t size_type; /// \brief The difference type typedef cs_ptrdiff_t difference_type; /// \brief The Boolean type typedef cs_bool_t bool_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 sink, or consume, the interface pointer /// \param quanta The actual quanta required for this instance. Must be <= Q. Defaults to 0, which causes it to be Q /// \param 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. enumerator_sequence(interface_type* i, bool_type bAddRef, size_type quanta = 0, bool_type bReset = true) : m_root(i) , m_enumerator(NULL) , m_quanta(validate_quanta_(quanta)) , m_bFirst(true) { COMSTL_MESSAGE_ASSERT("Precondition violation: interface cannot be NULL!", NULL != i); if(bAddRef) { m_root->AddRef(); } if(bReset) { m_root->Reset(); } // Here we instantiate m_enumerator // // If noncloneable, then just AddRef() // Otherwise Clone() and fail // // At this point, m_enumerator will be non-NULL, and // can be used in all invocations of begin(), or it // will be NULL, in which case the 2nd or subsequent // invocations of begin() must be directed to throw. m_enumerator = cloning_policy_type::get_working_instance(m_root); if(NULL != m_enumerator) { m_bFirst = false; } COMSTL_ASSERT(is_valid()); } /// \brief Releases the adapted interface pointer ~enumerator_sequence() stlsoft_throw_0() { COMSTL_ASSERT(is_valid()); m_root->Release(); if(NULL != m_enumerator) { m_enumerator->Release(); } } /// \name Iteration /// @{ public: /// \brief Iterator for the enumerator_sequence class class iterator : public stlsoft_ns_qual(iterator_base) { public: typedef iterator class_type; #if defined(STLSOFT_COMPILER_IS_GCC) typedef ss_typename_type_k sequence_type::cloning_policy_type cloning_policy_type; typedef ss_typename_type_k sequence_type::value_type value_type; #endif /* compiler */ private: struct enumeration_context { /// \name Member Types /// @{ public: typedef enumeration_context class_type; typedef V value_type; typedef CP cloning_policy_type; /// @} /// \name Construction /// @{ private: /// \brief Copying constructor /// /// This constructor copies the state of rhs, and is given a new /// cloned enumerator instance pointer. enumeration_context(interface_type* i, class_type const& rhs) : m_enumerator(i) , m_acquired(rhs.m_acquired) , m_current(rhs.m_current) , m_quanta(rhs.m_quanta) , m_refCount(1) , m_previousBlockTotal(rhs.m_previousBlockTotal) { COMSTL_ASSERT(rhs.m_acquired <= m_quanta); // Initialise all elements first, so that if a copy() throws an exception // all is cleared up simply. init_elements_(m_quanta); #ifdef STLSOFT_CF_EXCEPTION_SUPPORT try #endif /* STLSOFT_CF_EXCEPTION_SUPPORT */ { value_type* begin = &m_values[0]; value_type* end = &m_values[0] + m_quanta; value_type const* src_begin = &rhs.m_values[0]; value_type const* src_end = &rhs.m_values[0] + rhs.m_acquired; // Copy each element up to the common extent ... for(; src_begin != src_end; ++begin, ++src_begin) { value_policy_type::copy(begin, src_begin); } COMSTL_ASSERT(begin <= end); STLSOFT_SUPPRESS_UNUSED(end); } #ifdef STLSOFT_CF_EXCEPTION_SUPPORT catch(...) { // Must clear everything up here, since the enumeration_context will // not be destroyed (because it is not fully constructed). clear_elements_(); throw; } #endif /* STLSOFT_CF_EXCEPTION_SUPPORT */ COMSTL_ASSERT(is_valid()); COMSTL_ASSERT(this->index() == rhs.index()); } public: /// \brief Sharing constructor /// /// The iterator is enumeration_context(interface_type* i, size_type quanta, bool_type bFirst) : m_enumerator(bFirst ? (i->AddRef(), i) : cloning_policy_type::share(i)) , m_acquired(0) , m_current(0) , m_quanta(static_cast(quanta)) , m_refCount(1) , m_previousBlockTotal(0) { COMSTL_ASSERT(quanta <= STLSOFT_NUM_ELEMENTS(m_values)); init_elements_(m_quanta); // Note: We don't add a reference here, because share() increments the reference count. acquire_next_(); COMSTL_ASSERT(is_valid()); } ~enumeration_context() stlsoft_throw_0() { ++m_refCount; COMSTL_ASSERT(is_valid()); --m_refCount; clear_elements_(); if(NULL != m_enumerator) { m_enumerator->Release(); } } void AddRef() { ++m_refCount; } void Release() { if(0 == --m_refCount) { delete this; } } static class_type* make_clone(class_type* ctxt) { if(NULL == ctxt) { return NULL; } else { COMSTL_ASSERT(NULL != ctxt->m_enumerator); // Must always have one, so can test its cloneability interface_type* copy; const bool bTrueClone = cloning_policy_type::clone(ctxt->m_enumerator, ©); if(!bTrueClone) { COMSTL_ASSERT(NULL == copy); // Either forward_cloning_policy/input_cloning_policy that failed, or input_cloning_policy // // No reference will have been taken on m_ctxt->m_enumerator // // Just add ref on context, and return ctxt->AddRef(); return ctxt; } else { COMSTL_ASSERT(NULL != copy); // Either forward_cloning_policy that succeeded, or degenerate_cloning_policy that succeeded // // class_type* newCtxt; #ifdef STLSOFT_CF_EXCEPTION_SUPPORT try #endif /* STLSOFT_CF_EXCEPTION_SUPPORT */ { newCtxt = new class_type(copy, *ctxt); if(NULL == newCtxt) { copy->Release(); } } #ifdef STLSOFT_CF_EXCEPTION_SUPPORT catch(...) { copy->Release(); throw; } #endif /* STLSOFT_CF_EXCEPTION_SUPPORT */ return newCtxt; } } } /// @} /// \name Iteration /// @{ public: void advance() stlsoft_throw_0() { COMSTL_ASSERT(NULL != m_enumerator); // Four possibilities here: // // 1. Called when in an invalid state. This is determined by: // - // - // - // 2. next iteration point is within the number acquired // 3. need to acquire more elements from IEnumXXXX::Next() // 1. COMSTL_MESSAGE_ASSERT("Attempting to increment an invalid iterator: m_refCount < 1", 0 < m_refCount); COMSTL_MESSAGE_ASSERT("Attempting to increment an invalid iterator: 0 == m_acquired", 0 != m_acquired); COMSTL_MESSAGE_ASSERT("Attempting to increment an invalid iterator: m_current >= m_acquired", m_current < m_acquired); COMSTL_MESSAGE_ASSERT("Attempting to increment an invalid iterator: m_acquired > m_quanta", m_acquired <= m_quanta); COMSTL_MESSAGE_ASSERT("Attempting to increment an invalid iterator: m_quanta > dimensionof(m_values)", m_quanta <= STLSOFT_NUM_ELEMENTS(m_values)); if(++m_current < m_acquired) { // 2. // Do nothing } else { COMSTL_MESSAGE_ASSERT("Attempting to increment an invalid iterator", NULL != m_enumerator); clear_elements_(); // Reset enumeration m_current = 0; acquire_next_(); } } value_type ¤t() stlsoft_throw_0() { COMSTL_ASSERT(!empty()); return m_values[m_current]; } size_type index() const stlsoft_throw_0() { return m_previousBlockTotal + m_current; } bool empty() const stlsoft_throw_0() { return 0 == m_acquired /* && NULL == m_enumerator */; } /// @} /// \name Invariant /// @{ public: bool_type is_valid() const { if(m_refCount < 1) { #ifdef STLSOFT_UNITTEST fprintf(err, "invalid reference count (%ld) \n", m_refCount); #endif /* STLSOFT_UNITTEST */ return false; } if( NULL == m_enumerator && 0 == m_quanta) { if(0 != m_acquired) { #ifdef STLSOFT_UNITTEST fprintf(err, "m_acquired == %lu when m_quanta == 0\n", m_acquired); #endif /* STLSOFT_UNITTEST */ return false; } if(0 != m_current) { #ifdef STLSOFT_UNITTEST fprintf(err, "m_current == %lu when m_quanta == 0\n", m_current); #endif /* STLSOFT_UNITTEST */ return false; } if(0 != m_quanta) { return false; } } else { if(m_acquired < m_current) { #ifdef STLSOFT_UNITTEST fprintf(err, "m_acquired (%lu) not less than m_current (%lu)\n", m_acquired, m_current); #endif /* STLSOFT_UNITTEST */ return false; } if(m_quanta < m_current) { #ifdef STLSOFT_UNITTEST fprintf(err, "m_quanta (%lu) not less than m_current (%lu)\n", m_quanta, m_current); #endif /* STLSOFT_UNITTEST */ return false; } if(m_quanta < m_acquired) { #ifdef STLSOFT_UNITTEST fprintf(err, "m_quanta (%lu) not less than m_acquired (%lu)\n", m_quanta, m_acquired); #endif /* STLSOFT_UNITTEST */ return false; } } return true; } /// @} /// \name Implementation /// @{ private: void acquire_next_() stlsoft_throw_0() { // COMSTL_ASSERT(0 == m_acquired); COMSTL_ASSERT(0 == m_current); ULONG cFetched = 0; m_enumerator->Next(m_quanta, &m_values[0], &cFetched); m_acquired = cFetched; m_previousBlockTotal += cFetched; // We no longer checked for a FAILED(hr), since some enumerators // return invalid results. We rely on cFetched, which is the // only reliable guide when marshalling anyway } void clear_elements_() stlsoft_throw_0() { COMSTL_ASSERT(m_acquired <= STLSOFT_NUM_ELEMENTS(m_values)); typedef ss_typename_type_k value_policy_type::clear_element clear_t; comstl_ns_qual_std(for_each)(&m_values[0], &m_values[0] + m_acquired, clear_t()); } void init_elements_(size_type n) stlsoft_throw_0() { COMSTL_ASSERT(n <= STLSOFT_NUM_ELEMENTS(m_values)); typedef ss_typename_type_k value_policy_type::init_element init_t; comstl_ns_qual_std(for_each)(&m_values[0], &m_values[0] + n, init_t()); } /// @} /// \name Members /// @{ private: interface_type* m_enumerator; size_type m_acquired; size_type m_current; ULONG const m_quanta; value_type m_values[retrievalQuanta]; long m_refCount; size_type m_previousBlockTotal; /// @} // Not to be implemented private: enumeration_context(class_type const&); class_type& operator =(class_type const&); }; /// \name Construction /// @{ private: friend class enumerator_sequence; /// \brief Constructor iterator(interface_type* i, size_type quanta, bool_type &bFirst) : m_ctxt(new enumeration_context(i, quanta, bFirst)) { bFirst = false; COMSTL_ASSERT(is_valid()); } public: /// \brief Default constructor iterator() : m_ctxt(NULL) { COMSTL_ASSERT(is_valid()); } /// \brief Copy constructor iterator(class_type const& rhs) : m_ctxt(enumeration_context::make_clone(rhs.m_ctxt)) { COMSTL_ASSERT(is_valid()); } /// \brief Releases any internal storage ~iterator() stlsoft_throw_0() { COMSTL_ASSERT(is_valid()); if(NULL != m_ctxt) { m_ctxt->Release(); } } class_type& operator =(class_type const& rhs) { enumeration_context *newCtxt = enumeration_context::make_clone(rhs.m_ctxt); if(NULL != m_ctxt) { m_ctxt->Release(); } m_ctxt = newCtxt; return *this; } /// @} /// \name Forward Iterator Methods /// @{ public: /// \brief Pre-increment operator class_type& operator ++() { COMSTL_ASSERT(is_valid()); m_ctxt->advance(); COMSTL_ASSERT(is_valid()); return *this; } /// \brief Post-increment operator class_type operator ++(int) { COMSTL_ASSERT(is_valid()); class_type r(*this); operator ++(); COMSTL_ASSERT(is_valid()); return r; } /// \brief Returns the value represented by the current iteration position reference operator *() { COMSTL_ASSERT(is_valid()); COMSTL_MESSAGE_ASSERT("Attempting to dereference an invalid iterator", (NULL != m_ctxt && !m_ctxt->empty())); return m_ctxt->current(); } /// \brief Returns the value represented by the current iteration position pointer operator ->() { COMSTL_ASSERT(is_valid()); COMSTL_MESSAGE_ASSERT("Attempting to dereference an invalid iterator", (NULL != m_ctxt && !m_ctxt->empty())); return &m_ctxt->current(); } private: static bool_type equal_(class_type const& lhs, class_type const& rhs, stlsoft_ns_qual_std(input_iterator_tag)) { // The only valid comparison is when they both represent the end values. return lhs.is_end_point() && rhs.is_end_point(); } static bool_type equal_(class_type const& lhs, class_type const& rhs, stlsoft_ns_qual_std(forward_iterator_tag)) { // The iterators can be equal under two conditions: // // 1. The end iterator (as in the case for input iterators) // 2. Both have a context, and the index of both contexts are the same // // otherwise: // // 3. They're not equal if(lhs.is_end_point()) { return rhs.is_end_point(); // 1 or 3 } else { if(rhs.is_end_point()) { return false; // 3 } else { COMSTL_ASSERT(NULL != lhs.m_ctxt); COMSTL_ASSERT(NULL != rhs.m_ctxt); return lhs.m_ctxt->index() == rhs.m_ctxt->index(); // 2 or 3 } } } public: /// \brief Evaluates whether \c this and \c rhs are equivalent bool_type equal(class_type const& rhs) const { COMSTL_ASSERT(is_valid()); return class_type::equal_(*this, rhs, iterator_tag_type()); } /// \brief Evaluates whether \c this and \c rhs are equivalent bool_type operator == (class_type const& rhs) const { COMSTL_ASSERT(is_valid()); return this->equal(rhs); } /// \brief Evaluates whether \c this and \c rhs are not equivalent bool_type operator != (class_type const& rhs) const { COMSTL_ASSERT(is_valid()); return !this->equal(rhs); } /// @} /// \name Invariant /// @{ private: bool_type is_valid() const { return (NULL == m_ctxt) || m_ctxt->is_valid(); } /// @} /// \name Implementation /// @{ private: bool_type is_end_point() const { return NULL == m_ctxt || m_ctxt->empty(); } /// @} /// \name Members /// @{ private: enumeration_context *m_ctxt; /// @} }; /// \brief The non-mutating (const) iterator type typedef iterator const_iterator; public: /// \brief Begins the iteration /// /// \return 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. iterator begin() const { COMSTL_ASSERT(is_valid()); interface_type* en = NULL; if(NULL != m_enumerator) { en = m_enumerator; } else { if(!m_bFirst) { #ifdef STLSOFT_CF_EXCEPTION_SUPPORT STLSOFT_THROW_X(clone_failure(E_NOTIMPL)); #else /* ? STLSOFT_CF_EXCEPTION_SUPPORT */ return end(); #endif /* STLSOFT_CF_EXCEPTION_SUPPORT */ } else { en = m_root; } } COMSTL_ASSERT(NULL != en); return iterator(en, m_quanta, m_bFirst); } /// \brief Ends the iteration /// /// \return An iterator representing the end of the sequence iterator end() const { COMSTL_ASSERT(is_valid()); return iterator(); } /// @} /// \name Attributes /// @{ public: static size_type quanta() { return retrievalQuanta; } /// @} /// \name Invariant /// @{ private: bool_type is_valid() const { if(NULL == m_root) { #ifdef STLSOFT_UNITTEST fprintf(err, "enumerator_sequence: m_root is NULL\n"); COMSTL_ASSERT(0); #endif /* STLSOFT_UNITTEST */ 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: interface_type* m_root; interface_type* m_enumerator; size_type const m_quanta; ss_mutable_k bool_type m_bFirst; // Not to be implemented private: enumerator_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/enumerator_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_ENUMERATOR_SEQUENCE */ /* ///////////////////////////// end of file //////////////////////////// */