iterator.hpp

用STL的方式封装了WindowsAPI、COM调用、ACE、ATL、MFC、WTL等多种组件

/* /////////////////////////////////////////////////////////////////////////
 * File:        stlsoft/iterator.hpp (formerly stlsoft_iterator.h; originally MTIter.h, ::SynesisStl)
 *
 * Purpose:     iterator class templates and macros for abstracting away standard
 *              library inconsistencies.
 *
 * Created:     2nd January 2000
 * Updated:     10th June 2006
 *
 * Home:        http://stlsoft.org/
 *
 * Copyright (c) 2000-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 stlsoft/iterator.hpp
///
/// iterator class templates and macros for abstracting away standard library inconsistencies.

#ifndef STLSOFT_INCL_STLSOFT_HPP_ITERATOR
#define STLSOFT_INCL_STLSOFT_HPP_ITERATOR

#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
# define STLSOFT_VER_STLSOFT_HPP_ITERATOR_MAJOR     4
# define STLSOFT_VER_STLSOFT_HPP_ITERATOR_MINOR     3
# define STLSOFT_VER_STLSOFT_HPP_ITERATOR_REVISION  6
# define STLSOFT_VER_STLSOFT_HPP_ITERATOR_EDIT      92
#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

/* /////////////////////////////////////////////////////////////////////////
 * Compatibility
 */

/*
[Incompatibilies-start]
STLSOFT_COMPILER_IS_WATCOM:
[Incompatibilies-end]
 */

/* /////////////////////////////////////////////////////////////////////////
 * Includes
 */

#ifndef STLSOFT_INCL_STLSOFT_H_STLSOFT
# include <stlsoft/stlsoft.h>
#endif /* !STLSOFT_INCL_STLSOFT_H_STLSOFT */
#ifndef STLSOFT_INCL_STLSOFT_UTIL_STD_LIBRARY_DISCRIMINATOR
# include <stlsoft/util/std/library_discriminator.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_UTIL_STD_LIBRARY_DISCRIMINATOR */

#include <iterator>    // for std::iterator, std::reverse_iterator, std::reverse_bidirectional_iterator

#ifdef STLSOFT_CF_HAS_MEMBER_TYPE_SUPPORTED_XXXX
# ifndef STLSOFT_INCL_STLSOFT_TYPEFIXER_HPP_POINTER
#  include <stlsoft/typefixer/pointer.hpp>
# endif /* !STLSOFT_INCL_STLSOFT_TYPEFIXER_HPP_POINTER */
# ifndef STLSOFT_INCL_STLSOFT_TYPEFIXER_HPP_POINTER_TYPE
#  include <stlsoft/typefixer/pointer_type.hpp>
# endif /* !STLSOFT_INCL_STLSOFT_TYPEFIXER_HPP_POINTER_TYPE */
# ifndef STLSOFT_INCL_STLSOFT_TYPEFIXER_HPP_REFERENCE
#  include <stlsoft/typefixer/reference.hpp>
# endif /* !STLSOFT_INCL_STLSOFT_TYPEFIXER_HPP_REFERENCE */
# ifndef STLSOFT_INCL_STLSOFT_TYPEFIXER_HPP_REFERENCE_TYPE
#  include <stlsoft/typefixer/reference_type.hpp>
# endif /* !STLSOFT_INCL_STLSOFT_TYPEFIXER_HPP_REFERENCE_TYPE */
#endif /* STLSOFT_CF_HAS_MEMBER_TYPE_SUPPORTED */

/* /////////////////////////////////////////////////////////////////////////
 * Warnings
 */

/* This is here temporarily, until a better solution can be found. */
#ifdef STLSOFT_COMPILER_IS_MSVC
# pragma warning(disable : 4097)    // suppresses: typedef-name 'identifier1' used as synonym for class-name 'identifier2'
#endif /* compiler */

/* /////////////////////////////////////////////////////////////////////////
 * Namespace
 */

#ifndef _STLSOFT_NO_NAMESPACE
namespace stlsoft
{
#endif /* _STLSOFT_NO_NAMESPACE */

/* /////////////////////////////////////////////////////////////////////////
 * Tested compatibilities
 */

#if !defined(STLSOFT_OVERRIDE_COMPILER_STD_LIBRARY_CHECK)

# if 0
    /* Now we Must be either Dinkumware or STLport if compiling with Intel or Visual C++
     */

#    if (   defined(STLSOFT_COMPILER_IS_INTEL) || \
            (   defined(STLSOFT_COMPILER_IS_MSVC) && \
                _MSC_VER >= 1200 && \
                _MSC_VER < 1310)) && \
        (   !defined(STLSOFT_CF_STD_LIBRARY_IS_DINKUMWARE_VC) && \
            !defined(STLSOFT_CF_STD_LIBRARY_IS_STLPORT))
#     error When compiling with Intel C/C++ or Microsoft Visual C++, only the Dinkumware or STLport STL implementations are currently supported.
#     error  Please contact STLSoft ([e-mail]) if you need to support a different STL implementation with these compilers.
#    endif /* (Intel || MSVC) && !DinkumWare && !STLport */
# endif /* 0 */

#endif /* !STLSOFT_OVERRIDE_COMPILER_STD_LIBRARY_CHECK */

/* /////////////////////////////////////////////////////////////////////////
 * Iterator macros
 */

/* iterator
 *
 * There are
 *
 * 1. Form 1. This is the standard (C++-98: 24.2) form, and looks like the following
 *
 *    template< typename C
 *            , typename V
 *            , typename D = ptrdiff_t
 *            , typename P = V*
 *            , typename R = V&
 *            >
 *    struct iterator
 *    {
 *      typedef C   iterator_category;
 *      typedef V   value_type;
 *      typedef D  difference_type;
 *      typedef P  pointer;
 *      typedef R  reference;
 *    };
 *
 * 2. Form 2. This is found with Dinkumware / Visual C++ (versions 4.2, 5.0, 6.0)
 *
 *    template< typename C
 *            , typename V
 *            , typename D = ptrdiff_t
 *            >
 *    struct iterator
 *    {
 *      typedef C iterator_category;
 *      typedef V value_type;
 *      typedef D distance_type;
 *    };
 *
 * 3. Form 3. This is found in quite old versions of the STL, and in fact does not define
 *            an iterator template at all. Each container has its own iterator type
 */


#ifdef STLSOFT_ITERATOR_ITERATOR_FORM1_SUPPORT
# undef STLSOFT_ITERATOR_ITERATOR_FORM1_SUPPORT
#endif /* !STLSOFT_ITERATOR_ITERATOR_FORM1_SUPPORT */

#ifdef STLSOFT_ITERATOR_ITERATOR_FORM2_SUPPORT
# undef STLSOFT_ITERATOR_ITERATOR_FORM2_SUPPORT
#endif /* !STLSOFT_ITERATOR_ITERATOR_FORM2_SUPPORT */

#ifdef STLSOFT_ITERATOR_ITERATOR_FORM3_SUPPORT
# undef STLSOFT_ITERATOR_ITERATOR_FORM3_SUPPORT
#endif /* !STLSOFT_ITERATOR_ITERATOR_FORM3_SUPPORT */


#if defined(STLSOFT_COMPILER_IS_GCC) && \
    __GNUC__ < 3
 /* GCC 2.95 */
# define STLSOFT_ITERATOR_ITERATOR_FORM3_SUPPORT
#elif defined(STLSOFT_CF_STD_LIBRARY_IS_DINKUMWARE_VC)
# if  STLSOFT_CF_STD_LIBRARY_DINKUMWARE_VC_VERSION == STLSOFT_CF_DINKUMWARE_VC_VERSION_4_2 || \
      STLSOFT_CF_STD_LIBRARY_DINKUMWARE_VC_VERSION == STLSOFT_CF_DINKUMWARE_VC_VERSION_5_0 || \
      STLSOFT_CF_STD_LIBRARY_DINKUMWARE_VC_VERSION == STLSOFT_CF_DINKUMWARE_VC_VERSION_6_0
 /* Visual C++ + Dinkumware (pre v7.0) */
#  define STLSOFT_ITERATOR_ITERATOR_FORM2_SUPPORT
# else
#  define STLSOFT_ITERATOR_ITERATOR_FORM1_SUPPORT
# endif /* STLSOFT_CF_STD_LIBRARY_IS_DINKUMWARE_VC */
#elif defined(STLSOFT_CF_STD_LIBRARY_IS_MSL)
# define STLSOFT_ITERATOR_ITERATOR_FORM1_SUPPORT
#elif defined(STLSOFT_CF_STD_LIBRARY_IS_STLPORT)
# define STLSOFT_ITERATOR_ITERATOR_FORM1_SUPPORT
#elif defined(STLSOFT_CF_STD_LIBRARY_IS_HP_SGI)
# if defined(__STL_USE_NAMESPACES)
#  define STLSOFT_ITERATOR_ITERATOR_FORM1_SUPPORT
# else /* ? __STL_USE_NAMESPACES */
#  define STLSOFT_ITERATOR_ITERATOR_FORM3_SUPPORT
# endif /* __STL_USE_NAMESPACES */
#elif defined(STLSOFT_CF_STD_LIBRARY_IS_HP_SGI_GNU)
# define STLSOFT_ITERATOR_ITERATOR_FORM1_SUPPORT
#elif defined(STLSOFT_CF_STD_LIBRARY_IS_HP_RW)
# define STLSOFT_ITERATOR_ITERATOR_FORM1_SUPPORT
#elif defined(STLSOFT_CF_STD_LIBRARY_IS_WATCOM_PATCH)
# define STLSOFT_ITERATOR_ITERATOR_FORM1_SUPPORT
#else
# error Library version not recognised
#endif /* library */


/* reverse_iterator
 *
 * There are four known forms for reverse_iterators:
 *
 * 1. Form 1. This is the standard (C++-98: 24.4.1.1) form, and looks like the following
 *
 *    template <typename I>
 *      : public iterator<  typename iterator_traits<I>::iterator_category,
 *                          typename iterator_traits<I>::value_type,
 *                          typename iterator_traits<I>::difference_type,
 *                          typename iterator_traits<I>::pointer,
 *                          typename iterator_traits<I>::reference>
 *    {
 *      . . .
 *      typedef I                                               iterator_type;
 *      typedef typename iterator_traits<I>::difference_type    difference_type;
 *      typedef typename iterator_traits<I>::reference          reference;
 *      typedef typename iterator_traits<I>::pointer            pointer;
 *      . . .
 *    };
 *
 *
 * 2. Form 2. This is effectively standard, but does not derive from std::iterator. It looks
 *            like the following
 *
 *    template <typename I>
 *    {
 *      typedef typename iterator_traits<I>::iterator_category  iterator_category;
 *      typedef typename iterator_traits<I>::value_type         value_type;
 *      typedef typename iterator_traits<I>::difference_type    difference_type;
 *      typedef typename iterator_traits<I>::pointer            pointer;
 *      typedef typename iterator_traits<I>::reference          reference;
 *      . . .
 *    };
 *
 * 3. Form 3.
 *
 *    template< typename I
 *            , typename V
 *            , typename R = V&
 *            , typename P = V*
 *            , typename D = ptrdiff_t
 *            >
 *      : public _Ranit<V, D>
 *    {
 *      . . .
 *      typedef _Rt reference_type;
 *      typedef _Pt pointer_type;
 *      . . .
 *    };
 *
 *
 * 4. Form 4.
 *
 *    template< typename I
 *            , typename IC
 *            , typename V
 *            , typename R = V&
 *            , typename P = V*
 *            , typename D = ptrdiff_t
 *            >
 *    class reverse_iterator
 *      : public iterator<IC, V, D, P, R>
 *    {
 *      typedef D difference_type;
 *      typedef V value_type;
 *      typedef R reference;
 *      typedef P pointer;
 *      . . .
 *    };
 *
 *
 * 5. Form 5.
 *
 *    template< typename I
 *            , typename V
 *            , typename R = V&
 *            , typename D = ptrdiff_t
 *            >
 *    class reverse_iterator
 *      : public iterator<I, V, R, D>
 *    {
 *      typedef random_access_iterator_tag  iterator_category;
 *      typedef V                           value_type;
 *      typedef D                           difference_type;
 *      typedef V                           *pointer;
 *      typedef R                           reference;
 *      . . .
 *    };
 *
 */

#ifdef STLSOFT_ITERATOR_REVERSE_ITERATOR_FORM1_SUPPORT
# undef STLSOFT_ITERATOR_REVERSE_ITERATOR_FORM1_SUPPORT
#endif /* !STLSOFT_ITERATOR_REVERSE_ITERATOR_FORM1_SUPPORT */

#ifdef STLSOFT_ITERATOR_REVERSE_ITERATOR_FORM2_SUPPORT
# undef STLSOFT_ITERATOR_REVERSE_ITERATOR_FORM2_SUPPORT
#endif /* !STLSOFT_ITERATOR_REVERSE_ITERATOR_FORM2_SUPPORT */

#ifdef STLSOFT_ITERATOR_REVERSE_ITERATOR_FORM3_SUPPORT
# undef STLSOFT_ITERATOR_REVERSE_ITERATOR_FORM3_SUPPORT
#endif /* !STLSOFT_ITERATOR_REVERSE_ITERATOR_FORM3_SUPPORT */

#ifdef STLSOFT_ITERATOR_REVERSE_ITERATOR_FORM4_SUPPORT
# undef STLSOFT_ITERATOR_REVERSE_ITERATOR_FORM4_SUPPORT
#endif /* !STLSOFT_ITERATOR_REVERSE_ITERATOR_FORM4_SUPPORT */