auto_buffer.hpp

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

/* /////////////////////////////////////////////////////////////////////////
 * File:        stlsoft/memory/auto_buffer.hpp (originally MTLocBfr.h, ::SynesisStl)
 *
 * Purpose:     Contains the auto_buffer template class.
 *
 * Created:     19th January 2002
 * Updated:     18th June 2006
 *
 * Home:        http://stlsoft.org/
 *
 * Copyright (c) 2002-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/memory/auto_buffer.hpp
 *
 * \brief [C++ only] Definition of the stlsoft::auto_buffer class template.
 *  (\ref group__library__memory "Memory" Library.)
 */

#ifndef STLSOFT_INCL_STLSOFT_MEMORY_HPP_AUTO_BUFFER
#define STLSOFT_INCL_STLSOFT_MEMORY_HPP_AUTO_BUFFER

#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
# define STLSOFT_VER_STLSOFT_MEMORY_HPP_AUTO_BUFFER_MAJOR       5
# define STLSOFT_VER_STLSOFT_MEMORY_HPP_AUTO_BUFFER_MINOR       0
# define STLSOFT_VER_STLSOFT_MEMORY_HPP_AUTO_BUFFER_REVISION    3
# define STLSOFT_VER_STLSOFT_MEMORY_HPP_AUTO_BUFFER_EDIT        141
#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

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

/*
[Incompatibilies-start]
STLSOFT_COMPILER_IS_GCC:     __GNUC__ < 3
[Incompatibilies-end]
 */

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

#ifndef STLSOFT_INCL_STLSOFT_H_STLSOFT
# include <stlsoft/stlsoft.h>
#endif /* !STLSOFT_INCL_STLSOFT_H_STLSOFT */
#ifndef STLSOFT_INCL_STLSOFT_MEMORY_HPP_ALLOCATOR_FEATURES
# include <stlsoft/memory/allocator_features.hpp>   // for STLSOFT_LF_ALLOCATOR_ALLOCATE_HAS_HINT
#endif /* !STLSOFT_INCL_STLSOFT_MEMORY_HPP_ALLOCATOR_FEATURES */
#ifndef STLSOFT_INCL_STLSOFT_MEMORY_HPP_ALLOCATOR_SELECTOR
# include <stlsoft/memory/allocator_selector.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_MEMORY_HPP_ALLOCATOR_SELECTOR */
#ifndef STLSOFT_INCL_STLSOFT_ALGORITHMS_HPP_POD
# include <stlsoft/algorithms/pod.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_HPP_ALGORITHMS_POD */
#ifndef STLSOFT_INCL_STLSOFT_UTIL_HPP_STD_SWAP
# include <stlsoft/util/std_swap.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_UTIL_HPP_STD_SWAP */
#ifdef _STLSOFT_AUTO_BUFFER_ALLOW_UDT
# define _STLSOFT_AUTO_BUFFER_ALLOW_NON_POD
# ifdef STLSOFT_CF_PRAGMA_MESSAGE_SUPPORT
#  pragma message("_STLSOFT_AUTO_BUFFER_ALLOW_UDT is deprecated. Use _STLSOFT_AUTO_BUFFER_ALLOW_NON_POD instead")
# endif /* STLSOFT_CF_PRAGMA_MESSAGE_SUPPORT */
#endif /* _STLSOFT_AUTO_BUFFER_ALLOW_UDT */
#if defined(STLSOFT_CF_BIDIRECTIONAL_ITERATOR_SUPPORT)
# ifndef STLSOFT_INCL_STLSOFT_HPP_ITERATOR
#  include <stlsoft/iterator.hpp>           // for reverse_iterator_base
# endif /* !STLSOFT_INCL_STLSOFT_HPP_ITERATOR */
#endif /* STLSOFT_CF_BIDIRECTIONAL_ITERATOR_SUPPORT */
#ifndef _STLSOFT_AUTO_BUFFER_ALLOW_NON_POD
# ifndef STLSOFT_INCL_STLSOFT_HPP_CONSTRAINTS
#  include <stlsoft/constraints.hpp>
# endif /* !STLSOFT_INCL_STLSOFT_HPP_CONSTRAINTS */
#endif /* _STLSOFT_AUTO_BUFFER_ALLOW_NON_POD */
#ifndef STLSOFT_INCL_STLSOFT_COLLECTIONS_HPP_COLLECTIONS
# include <stlsoft/collections/collections.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_COLLECTIONS_HPP_COLLECTIONS */

#ifdef STLSOFT_UNITTEST
# include <algorithm>
# if defined(STLSOFT_CF_BIDIRECTIONAL_ITERATOR_SUPPORT)
#  include <numeric>
# endif /* STLSOFT_CF_BIDIRECTIONAL_ITERATOR_SUPPORT */
# include <stdio.h>
#endif /* STLSOFT_UNITTEST */

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

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

/* /////////////////////////////////////////////////////////////////////////
 * Classes
 */

#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
#  if !defined(STLSOFT_COMPILER_IS_BORLAND) && \
      !defined(STLSOFT_COMPILER_IS_DMC)

struct auto_buffer_internal_default
{
    enum { min_value        =   32      };
    enum { max_value        =   256     };
    enum { division_factor  =   2       };
};

template <ss_typename_param_k T>
struct auto_buffer_internal_size_calculator
    : private auto_buffer_internal_default
{
private:
    // Stupid, stupid, stupid GCC requires them all to share the same
    // enum, which totally sucks. It whinges about comparisons between
    // enumerals (sic.) of different types. Thankfully it's irrelevant
    // because they're private
    enum
    {
            min_value        =   auto_buffer_internal_default::min_value
        ,   max_value        =   auto_buffer_internal_default::max_value
        ,   division_factor  =   auto_buffer_internal_default::division_factor
        ,   divided_value_   =   static_cast<int>((division_factor * max_value) / sizeof(T))
        ,   divided_value    =   (max_value < divided_value_)
                                    ?   max_value
                                    :   divided_value_
    };
public:
    enum { value            =   1 == sizeof(T)
                                    ?   max_value
                                    :   divided_value < min_value
                                        ?   min_value
                                        :   divided_value           };
};

STLSOFT_TEMPLATE_SPECIALISATION
struct auto_buffer_internal_size_calculator<ss_char_a_t>
{
    enum { value    =   auto_buffer_internal_default::max_value     };
};
#  if defined(STLSOFT_CF_NATIVE_WCHAR_T_SUPPORT) || \
      defined(STLSOFT_CF_TYPEDEF_WCHAR_T_SUPPORT)
STLSOFT_TEMPLATE_SPECIALISATION
struct auto_buffer_internal_size_calculator<ss_char_w_t>
{
    enum { value    =   auto_buffer_internal_default::max_value     };
};
#  endif /* STLSOFT_CF_NATIVE_WCHAR_T_SUPPORT */

# endif /* compiler */
#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */



// class auto_buffer
//
/** \brief This class provides an efficient variable automatic buffer
 *
 * \ingroup group__library__memory
 *
 * This class provides an efficient replacement for dynamic memory block
 * allocation when the block size generally falls under a certain limit. In
 * such cases, significant performance benefits can be achieved by using an
 * instance of a parameterisation of auto_buffer, whose size parameter SPACE
 * is set to a level to cater for most of the requested sizes. Only where
 * the size of the buffer needs to be larger than this limit does an
 * allocation occur from the heap/free-store via the given allocator.
 *
 * \param T The type of the elements in the array
 * \param SPACE The number of elements in the array. For translators that
 *   support default template arguments, this is defaulted to 256
 * \param A The allocator type. Defaults to allocator_selector<T>::allocator_type for translators
 *   that support default template arguments.
 *
 * \remarks auto_buffer works correctly whether the given allocator throws an
 *   exception on allocation failure, or returns NULL. In the latter case,
 *   construction failure to allocate results in the size() method returning
 *   0.
 *
 * \note With version 1.9 of STLSoft, the order of the space and allocator
 *   arguments were reversed. Further, the allocator default changed from
 *   stlsoft::new_allocator to std::allocator for translators that support
 *   the standard library. If you need the old characteristics, you can
 *   \#define the symbol <b>STLSOFT_AUTO_BUFFER_USE_PRE_1_9_CHARACTERISTICS</b>.
 */

#if defined(STLSOFT_COMPILER_IS_MSVC) && \
    _MSC_VER < 1200
# define STLSOFT_AUTO_BUFFER_USE_PRE_1_9_CHARACTERISTICS
#endif /* compiler */


#if defined(STLSOFT_AUTO_BUFFER_USE_PRE_1_9_CHARACTERISTICS)

# ifdef STLSOFT_AUTO_BUFFER_NEW_FORM
#  undef STLSOFT_AUTO_BUFFER_NEW_FORM
# endif /* STLSOFT_AUTO_BUFFER_NEW_FORM */

 // //////////////////////////////////////////////
 // This is the pre-1.9 template parameter list

template<   ss_typename_param_k T
# ifdef STLSOFT_CF_TEMPLATE_CLASS_DEFAULT_CLASS_ARGUMENT_SUPPORT
        ,   ss_typename_param_k A = ss_typename_type_def_k allocator_selector<T>::allocator_type
# else /* ? STLSOFT_CF_TEMPLATE_CLASS_DEFAULT_CLASS_ARGUMENT_SUPPORT */
        ,   ss_typename_param_k A
# endif /* STLSOFT_CF_TEMPLATE_CLASS_DEFAULT_CLASS_ARGUMENT_SUPPORT */
# ifdef STLSOFT_CF_TEMPLATE_CLASS_DEFAULT_FUNDAMENTAL_ARGUMENT_SUPPORT
#  if defined(STLSOFT_COMPILER_IS_BORLAND)
        ,   ss_size_t           space   =   256
#  elif defined(STLSOFT_COMPILER_IS_DMC)
        ,   ss_size_t           SPACE   =   256
#  else /* ? compiler */
        ,   ss_size_t           SPACE   =   auto_buffer_internal_size_calculator<T>::value
#  endif /* compiler */
# else /* ? STLSOFT_CF_TEMPLATE_CLASS_DEFAULT_CLASS_ARGUMENT_SUPPORT */
#  if !defined(STLSOFT_COMPILER_IS_BORLAND)
        ,   ss_size_t           SPACE   /* =   auto_buffer_internal_size_calculator<T>::value */
#  else /* ? compiler */
        ,   ss_size_t           space   /* =   256 */
#  endif /* compiler */
# endif /* STLSOFT_CF_TEMPLATE_CLASS_DEFAULT_FUNDAMENTAL_ARGUMENT_SUPPORT */
        >

 // End of pre-1.9 template parameter list
 // //////////////////////////////////////////////

#else /* ? STLSOFT_AUTO_BUFFER_USE_PRE_1_9_CHARACTERISTICS */

 // //////////////////////////////////////////////
 // This is the 1.9+ template parameter list

# ifndef STLSOFT_AUTO_BUFFER_NEW_FORM
#  define STLSOFT_AUTO_BUFFER_NEW_FORM
# endif /* !STLSOFT_AUTO_BUFFER_NEW_FORM */

template<   ss_typename_param_k T
# ifdef STLSOFT_CF_TEMPLATE_CLASS_DEFAULT_FUNDAMENTAL_ARGUMENT_SUPPORT
#  if defined(STLSOFT_COMPILER_IS_BORLAND)
        ,   ss_size_t           space   =   256
#  elif defined(STLSOFT_COMPILER_IS_DMC)
        ,   ss_size_t           SPACE   =   256
#  else /* ? compiler */
        ,   ss_size_t           SPACE   =   auto_buffer_internal_size_calculator<T>::value
#  endif /* compiler */
# else /* ? STLSOFT_CF_TEMPLATE_CLASS_DEFAULT_FUNDAMENTAL_ARGUMENT_SUPPORT */
#  if !defined(STLSOFT_COMPILER_IS_BORLAND)
        ,   ss_size_t           SPACE   /* =   auto_buffer_internal_size_calculator<T>::value */
#  else /* ? compiler */
        ,   ss_size_t           space   /* =   256 */
#  endif /* compiler */
# endif /* STLSOFT_CF_TEMPLATE_CLASS_DEFAULT_FUNDAMENTAL_ARGUMENT_SUPPORT */
# ifdef STLSOFT_CF_TEMPLATE_CLASS_DEFAULT_CLASS_ARGUMENT_SUPPORT
#  if defined(STLSOFT_CF_std_NAMESPACE)
        ,   ss_typename_param_k A = stlsoft_ns_qual_std(allocator)<T>
#  else /* ? STLSOFT_CF_std_NAMESPACE */
        ,   ss_typename_param_k A = new_allocator<T>
#  endif /* STLSOFT_CF_std_NAMESPACE */
# else /* ? STLSOFT_CF_TEMPLATE_CLASS_DEFAULT_CLASS_ARGUMENT_SUPPORT */
        ,   ss_typename_param_k A
# endif /* STLSOFT_CF_TEMPLATE_CLASS_DEFAULT_CLASS_ARGUMENT_SUPPORT */
        >

 // End of 1.9+ template parameter list
 // //////////////////////////////////////////////

#endif /* STLSOFT_AUTO_BUFFER_USE_PRE_1_9_CHARACTERISTICS */

class auto_buffer
#if !defined(STLSOFT_CF_ALLOCATOR_BASE_EXPENSIVE)
    : protected A
    , public stl_collection_tag
#else /* ? STLSOFT_CF_ALLOCATOR_BASE_EXPENSIVE */
    : public stl_collection_tag
#endif /* !STLSOFT_CF_ALLOCATOR_BASE_EXPENSIVE */
{
/// \name Member Types
/// @{
public:
    /// The value type
    typedef T                                                   value_type;
    /// The allocator type
    typedef A                                                   allocator_type;
#if !defined(STLSOFT_COMPILER_IS_BORLAND)
    enum
    {
        /// The number of items in the internal buffer
        space = SPACE
    };
#endif /* compiler */
    /// The type of the current parameterisation
#ifdef STLSOFT_AUTO_BUFFER_USE_PRE_1_9_CHARACTERISTICS
    typedef auto_buffer<T, A, space>                            class_type;
#else /* ? STLSOFT_AUTO_BUFFER_USE_PRE_1_9_CHARACTERISTICS */
    typedef auto_buffer<T, space, A>                            class_type;
#endif /* STLSOFT_AUTO_BUFFER_USE_PRE_1_9_CHARACTERISTICS */
    /// The reference type
    typedef ss_typename_type_k allocator_type::reference        reference;
    /// The non-mutable (const) reference type
    typedef ss_typename_type_k allocator_type::const_reference  const_reference;
    /// The pointer type
    typedef ss_typename_type_k allocator_type::pointer          pointer;
    /// The non-mutable (const) pointer type
    typedef ss_typename_type_k allocator_type::const_pointer    const_pointer;
    /// The size type
    typedef ss_size_t                                           size_type;
    /// The difference type
    typedef ss_ptrdiff_t                                        difference_type;
#if !defined(STLSOFT_CF_BIDIRECTIONAL_ITERATOR_SUPPORT)
    /// The iterator type
    typedef value_type                                          *iterator;
    /// The non-mutable (const) iterator type
    typedef value_type const                                    *const_iterator;
#else /* ? !STLSOFT_CF_BIDIRECTIONAL_ITERATOR_SUPPORT */
    /// The iterator type
    typedef
# if !defined(STLSOFT_COMPILER_IS_BORLAND)
           ss_typename_type_k
# endif /* compiler */
                       pointer_iterator <   value_type
                                        ,   pointer
                                        ,   reference
                                        >::type             iterator;
    /// The non-mutating (const) iterator type
    typedef
# if !defined(STLSOFT_COMPILER_IS_BORLAND)
         ss_typename_type_k
# endif /* compiler */
                       pointer_iterator <   value_type const
                                        ,   const_pointer
                                        ,   const_reference
                                        >::type             const_iterator;

    /// The mutating (non-const) reverse iterator type
    typedef reverse_iterator_base       <   iterator
                                        ,   value_type
                                        ,   reference
                                        ,   pointer
                                        ,   difference_type
                                        >                   reverse_iterator;

    /// The non-mutating (const) reverse iterator type
    typedef const_reverse_iterator_base <   const_iterator
                                        ,   value_type const
                                        ,   const_reference
                                        ,   const_pointer
                                        ,   difference_type
                                        >                   const_reverse_iterator;
#endif /* !STLSOFT_CF_BIDIRECTIONAL_ITERATOR_SUPPORT */
/// @}

/// \name Implementation
/// @{
private:
    pointer allocate_(size_type cItems, void const *hint)
    {
#ifdef STLSOFT_LF_ALLOCATOR_ALLOCATE_HAS_HINT
        return get_allocator().allocate(cItems, hint);
#else /* ? STLSOFT_LF_ALLOCATOR_ALLOCATE_HAS_HINT */
        STLSOFT_SUPPRESS_UNUSED(hint);

        return get_allocator().allocate(cItems);
#endif /* STLSOFT_LF_ALLOCATOR_ALLOCATE_HAS_HINT */
    }

    pointer allocate_(size_type cItems)
    {
#ifdef STLSOFT_LF_ALLOCATOR_ALLOCATE_HAS_HINT
        return get_allocator().allocate(cItems, NULL);