enumeration_policies.hpp

新版本TR1的stl

/* /////////////////////////////////////////////////////////////////////////
 * File:        comstl/collections/enumeration_policies.hpp
 *
 * Purpose:     Policies for enumerator interface handling.
 *
 * Created:     20th December 2003
 * Updated:     22nd March 2007
 *
 * Home:        http://stlsoft.org/
 *
 * Copyright (c) 2003-2007, 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/enumeration_policies.hpp
 *
 * \brief [C++ only] Policies for enumerator interface handling
 *   (\ref group__library__collections "Collections" Library).
 */

#ifndef COMSTL_INCL_COMSTL_COLLECTIONS_HPP_ENUMERATION_POLICIES
#define COMSTL_INCL_COMSTL_COLLECTIONS_HPP_ENUMERATION_POLICIES

#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
# define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATION_POLICIES_MAJOR       6
# define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATION_POLICIES_MINOR       1
# define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATION_POLICIES_REVISION    6
# define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATION_POLICIES_EDIT        49
#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 STLSOFT_INCL_STLSOFT_UTIL_STD_HPP_ITERATOR_HELPER
# include <stlsoft/util/std/iterator_helper.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_UTIL_STD_HPP_ITERATOR_HELPER */
#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 */

/* /////////////////////////////////////////////////////////////////////////
 * 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
 */

#ifdef STLSOFT_CF_EXCEPTION_SUPPORT

/** \brief Exception class thrown when Clone() method fails
 *
 * \ingroup group__library__collections
 */
// [[synesis:class:exception: comstl::clone_failure]]
class clone_failure
    : public com_exception
{
/// \name Member Types
/// @{
public:
    /// \brief The parent class type
    typedef com_exception       parent_class_type;
    /// \brief The type of this class
    typedef clone_failure       class_type;
/// @}

/// \name Construction
/// @{
public:
    /// \brief Constructs an instance from the given HRESULT code
    ss_explicit_k clone_failure(HRESULT hr)
        : parent_class_type(hr)
    {}
/// @}

/// \name Accessors
/// @{
public:
    /// \brief Returns a human-readable description of the exceptional condition
#if defined(STLSOFT_COMPILER_IS_DMC)
    char const  *what() const throw()
#else /* ? compiler */
    char const  *what() const stlsoft_throw_0()
#endif /* compiler */
    {
        return "Request to clone enumerator failed";
    }
/// @}

/// \name Not to be implemented
/// @{
private:
    class_type& operator =(class_type const&);
/// @}
};

#endif /* STLSOFT_CF_EXCEPTION_SUPPORT */


/** \brief Policy tag type that indicates an enumerator's Clone() method
 *    will fail.
 *
 * \ingroup group__library__collections
 */
struct noncloneable_enumerator_tag
{};

/** \brief Policy tag type that indicates an enumerator's Clone() method
 *    will succeed.
 *
 * \ingroup group__library__collections
 */
struct cloneable_enumerator_tag
{};

/** \brief Policy tag type that indicates an enumerator's Clone() method
 *    will succeed, and return an enumerator that will provide the same
 *    sequence of items as the source instance.
 *
 * \ingroup group__library__collections
 */
struct repeatable_enumerator_tag
    : public cloneable_enumerator_tag
{};



/** \brief Policy type that causes COM enumerator cloning according the STL Input Iterator concept
 *
 * \ingroup group__library__collections
 *
 * \param I The enumeration interface
 */
template<ss_typename_param_k I>
struct input_cloning_policy
    : public noncloneable_enumerator_tag
{
public:
    typedef I                                       interface_type;
    typedef interface_type                          *value_type;
    typedef comstl_ns_qual_std(input_iterator_tag)  iterator_tag_type;

public:
    /// \brief Gets a working "copy" of the given enumerator root
    ///
    /// \remarks For this policy, this simply calls AddRef()
    static interface_type *get_working_instance(interface_type *root)
    {
        COMSTL_ASSERT(NULL != root);

        root->AddRef();

        return root;
    }

    /// \brief "Clones" the given COM enumerator interface according to the Input Iterator concept
    static interface_type *share(interface_type *src)
    {
        COMSTL_ASSERT(NULL != src);

        src->AddRef();

        return src;
    }
    static cs_bool_t clone(interface_type *src, interface_type **pdest)
    {
        COMSTL_ASSERT(NULL != src);
        COMSTL_ASSERT(NULL != pdest);
        STLSOFT_SUPPRESS_UNUSED(src);

        *pdest = NULL;

        return false;
    }
};

/** \brief Policy type that causes COM enumerator cloning according the STL Input Iterator concept
 *
 * \ingroup group__library__collections
 *
 * \param I The enumeration interface
 */
template<ss_typename_param_k I>
struct cloneable_cloning_policy
    : public cloneable_enumerator_tag
{
public:
    typedef I                                       interface_type;
    typedef interface_type                          *value_type;
    typedef comstl_ns_qual_std(input_iterator_tag)  iterator_tag_type;

public:
    /// \brief Gets a working "copy" of the given enumerator root
    ///
    /// \remarks For this policy, this calls Clone(), and returns NULL
    ///   if that fails.
    static interface_type *get_working_instance(interface_type *root)
    {
        COMSTL_ASSERT(NULL != root);

        interface_type  *ret;
        HRESULT         hr  =   const_cast<interface_type*>(root)->Clone(&ret);

        if(FAILED(hr))
        {
            ret = NULL;
        }

        return ret;
    }

    static interface_type *share(interface_type *src)
    {
        COMSTL_ASSERT(NULL != src);

        interface_type  *ret;
        HRESULT         hr  =   const_cast<interface_type*>(src)->Clone(&ret);

        if(FAILED(hr))
        {
#ifdef STLSOFT_CF_EXCEPTION_SUPPORT
            STLSOFT_THROW_X(clone_failure(hr));
#else /* ? STLSOFT_CF_EXCEPTION_SUPPORT */
            ret = NULL;
#endif /* STLSOFT_CF_EXCEPTION_SUPPORT */
        }

        return ret;
    }