collection_sequence.hpp

来自「用STL的方式封装了WindowsAPI、COM调用、ACE、ATL、MFC、W」· HPP 代码 · 共 429 行 · 第 1/2 页

/* /////////////////////////////////////////////////////////////////////////
 * File:        comstl/collection_sequence.hpp (formerly comstl/coll_sequence.hpp, comstl_collection_sequence.h; originally MOEnSeq.h, ::SynesisCom)
 *
 * Purpose:     STL sequence for COM collection interfaces.
 *
 * Created:     17th September 1998
 * Updated:     10th June 2006
 *
 * Home:        http://stlsoft.org/
 *
 * Copyright (c) 1998-2006, 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/collection_sequence.hpp
///
/// STL sequence for COM collection interfaces.

#ifndef COMSTL_INCL_COMSTL_HPP_COLLECTION_SEQUENCE
#define COMSTL_INCL_COMSTL_HPP_COLLECTION_SEQUENCE

#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
# define COMSTL_VER_COMSTL_HPP_COLLECTION_SEQUENCE_MAJOR    5
# define COMSTL_VER_COMSTL_HPP_COLLECTION_SEQUENCE_MINOR    5
# define COMSTL_VER_COMSTL_HPP_COLLECTION_SEQUENCE_REVISION 2
# define COMSTL_VER_COMSTL_HPP_COLLECTION_SEQUENCE_EDIT     78
#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_H_REFCOUNT_FUNCTIONS
# include <comstl/refcount_functions.h>     // for safe_release(), release_set_null()
#endif /* !COMSTL_INCL_COMSTL_H_REFCOUNT_FUNCTIONS */
#ifndef COMSTL_INCL_COMSTL_HPP_ENUMERATION_POLICIES
# include <comstl/enumeration_policies.hpp> // for input_cloning_policy
#endif /* !COMSTL_INCL_COMSTL_HPP_ENUMERATION_POLICIES */
#ifndef COMSTL_INCL_COMSTL_HPP_INTERFACE_TRAITS
# include <comstl/interface_traits.hpp>
#endif /* !COMSTL_INCL_COMSTL_HPP_INTERFACE_TRAITS */
#ifdef STLSOFT_CF_EXCEPTION_SUPPORT
# ifndef COMSTL_INCL_COMSTL_HPP_EXCEPTIONS
#  include <comstl/exceptions.hpp>
# endif /* !COMSTL_INCL_COMSTL_HPP_EXCEPTIONS */
#endif /* STLSOFT_CF_EXCEPTION_SUPPORT */
#ifndef COMSTL_INCL_COMSTL_HPP_ENUMERATOR_SEQUENCE
# include <comstl/enumerator_sequence.hpp>
#endif /* !COMSTL_INCL_COMSTL_HPP_ENUMERATOR_SEQUENCE */
#ifndef STLSOFT_INCL_STLSOFT_HPP_ITERATOR
# include <stlsoft/iterator.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_HPP_ITERATOR */
#ifndef STLSOFT_INCL_STLSOFT_COLLECTIONS_HPP_COLLECTIONS
# include <stlsoft/collections/collections.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_COLLECTIONS_HPP_COLLECTIONS */
#include <algorithm>

#ifdef STLSOFT_UNITTEST
# include <comstl/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
 */

/// A template for adapting COM enumeration to STL-compatible sequence iteration
///
/// \param I Interface
/// \param V Value type
/// \param VP Value policy type
/// \param R Reference type
/// \param CP Cloning policy type
/// \param Q Quanta
///
/// 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.
///
/// \htmlonly
/// <table border = 0 cellspacing = 0 cellpadding = 0 >
///  <tr><td>&nbsp;&nbsp;</td><td><code>typedef collection_sequence</code></td><td><code>&lt;&nbsp;IGUIDCollection</code></td></tr>
///  <tr><td>&nbsp;&nbsp;</td><td><code>&nbsp;</code></td><td><code>,&nbsp;IEnumGUID</code></td></tr>
///  <tr><td>&nbsp;&nbsp;</td><td><code>&nbsp;</code></td><td><code>,&nbsp;GUID</code></td></tr>
///  <tr><td>&nbsp;&nbsp;</td><td><code>&nbsp;</code></td><td><code>,&nbsp;GUID_policy</code></td></tr>
///  <tr><td>&nbsp;&nbsp;</td><td><code>&nbsp;</code></td><td><code>,&nbsp;GUID const &</code></td></tr>
///  <tr><td>&nbsp;&nbsp;</td><td><code>&nbsp;</code></td><td><code>,&nbsp;forward_cloning_policy&lt;IEnumGUID&gt;</code></td></tr>
///  <tr><td>&nbsp;&nbsp;</td><td><code>&nbsp;</code></td><td><code>,&nbsp;5</code></td></tr>
///  <tr><td>&nbsp;&nbsp;</td><td><code>&nbsp;</code></td><td><code>&gt;&nbsp;&nbsp;&nbsp;collection_sequence_t;</code></td></tr>
/// </table>
/// \endhtmlonly
///
/// The value type is <b>GUID</b> and it is returned as a reference, as
/// the <b>GUID const &</b> in fact.
///
/// The \ref COMSTL type <b>GUID_policy</b> controls how the <b>GUID</b>
/// instances are initialised, copied and destroyed.
///
/// The \ref 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 5 values at a time,
/// to save round trips to the enumerator.
///
/// So this would be used like the following:
///
/// \htmlonly
/// <code>
/// &nbsp;&nbsp;void dump_GUID(GUID const &);
/// <br>
///
/// <br>
/// &nbsp;&nbsp;IGUIDCollection&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*penGUIDs = . . .;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;// Create an instance from wherever
/// <br>
/// &nbsp;&nbsp;collection_sequence_t&nbsp;&nbsp;&nbsp;guids(penGUIDs, false); // Eat the reference
/// <br>
///
/// <br>
/// &nbsp;&nbsp;std::for_each(guids.begin(), guids.end(), dump_GUID);
/// <br>
/// </code>
/// \endhtmlonly
///
/// \note The iterator instances returned by begin() and end() are valid outside
/// the lifetime of the collection instance from which they are obtained
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:
    /// Collection interface type
    typedef CI                                                                  collection_interface_type;
    /// Enumerator interface type
    typedef ss_typename_type_k enumerator_sequence_type::interface_type         enumerator_interface_type;
    /// Value type
    typedef ss_typename_type_k enumerator_sequence_type::value_type             value_type;