stlsoft.h

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

 /* Leave it to whatever the compiler's capability discrimination has determined */
#endif /* __STLSOFT_CF_NOTHROW_BAD_ALLOC */


/* Template specialisation syntax support
 */
/** \def STLSOFT_TEMPLATE_SPECIALISATION
 * \brief Resolves to <code>template <></code>  for compilers that support correct
 *  template specialisation syntax, and to nothing for those that do not.
 */
#ifdef STLSOFT_TEMPLATE_SPECIALISATION
# undef STLSOFT_TEMPLATE_SPECIALISATION
#endif /* STLSOFT_TEMPLATE_SPECIALISATION */

#ifdef STLSOFT_CF_TEMPLATE_SPECIALISATION_SYNTAX
# define STLSOFT_TEMPLATE_SPECIALISATION                template <>
#else /* ? STLSOFT_CF_TEMPLATE_SPECIALISATION_SYNTAX */
# define STLSOFT_TEMPLATE_SPECIALISATION
#endif /* STLSOFT_CF_TEMPLATE_SPECIALISATION_SYNTAX */


/* Keyword support.
 *
 * Define _STLSOFT_FORCE_ALL_KEYWORDS to force the assumption of compiler
 * support for all keywords.
 *
 * Define _STLSOFT_FORCE_KEYWORD_EXPLICIT to force the assumption of compiler
 * support for the explicit keyword
 *
 * Define _STLSOFT_FORCE_KEYWORD_MUTABLE to force the assumption of compiler
 * support for the mutable keyword
 *
 * Define _STLSOFT_FORCE_KEYWORD_TYPENAME to force the assumption of compiler
 * support for the typename keyword
 */

#ifdef _STLSOFT_FORCE_ALL_KEYWORDS
# define _STLSOFT_FORCE_KEYWORD_EXPLICIT
# define _STLSOFT_FORCE_KEYWORD_MUTABLE
# define _STLSOFT_FORCE_KEYWORD_TYPENAME
#endif /* _STLSOFT_FORCE_ALL_KEYWORDS */

#if !defined(STLSOFT_CF_EXPLICIT_KEYWORD_SUPPORT) && \
    defined(_STLSOFT_FORCE_KEYWORD_EXPLICIT)
# define STLSOFT_CF_EXPLICIT_KEYWORD_SUPPORT
#endif /* !STLSOFT_CF_EXPLICIT_KEYWORD_SUPPORT && _STLSOFT_FORCE_KEYWORD_EXPLICIT */

#if !defined(STLSOFT_CF_MUTABLE_KEYWORD_SUPPORT) && \
    defined(_STLSOFT_FORCE_KEYWORD_MUTABLE)
# define STLSOFT_CF_MUTABLE_KEYWORD_SUPPORT
#endif /* !STLSOFT_CF_MUTABLE_KEYWORD_SUPPORT && _STLSOFT_FORCE_KEYWORD_MUTABLE */

#if !defined(STLSOFT_CF_TYPENAME_PARAM_KEYWORD_SUPPORT) && \
    defined(_STLSOFT_FORCE_KEYWORD_TYPENAME)
# define STLSOFT_CF_TYPENAME_PARAM_KEYWORD_SUPPORT
#endif /* !STLSOFT_CF_TYPENAME_PARAM_KEYWORD_SUPPORT && _STLSOFT_FORCE_KEYWORD_TYPENAME */

#if !defined(STLSOFT_CF_TYPENAME_TYPE_KEYWORD_SUPPORT) && \
    defined(_STLSOFT_FORCE_KEYWORD_TYPENAME)
# define STLSOFT_CF_TYPENAME_TYPE_KEYWORD_SUPPORT
#endif /* !STLSOFT_CF_TYPENAME_TYPE_KEYWORD_SUPPORT && _STLSOFT_FORCE_KEYWORD_TYPENAME */

#if !defined(STLSOFT_CF_TYPENAME_TYPE_DEF_KEYWORD_SUPPORT) && \
    defined(_STLSOFT_FORCE_KEYWORD_TYPENAME)
# define STLSOFT_CF_TYPENAME_TYPE_DEF_KEYWORD_SUPPORT
#endif /* !STLSOFT_CF_TYPENAME_TYPE_DEF_KEYWORD_SUPPORT && _STLSOFT_FORCE_KEYWORD_TYPENAME */

#if !defined(STLSOFT_CF_TYPENAME_TYPE_MIL_KEYWORD_SUPPORT) && \
    defined(_STLSOFT_FORCE_KEYWORD_TYPENAME)
# define STLSOFT_CF_TYPENAME_TYPE_MIL_KEYWORD_SUPPORT
#endif /* !STLSOFT_CF_TYPENAME_TYPE_MIL_KEYWORD_SUPPORT && _STLSOFT_FORCE_KEYWORD_TYPENAME */

/* /////////////////////////////////////////////////////////////////////////
 * Calling convention
 */

#ifdef STLSOFT_DOCUMENTATION_SKIP_SECTION
/** \def STLSOFT_CDECL_SUPPORTED
 * \brief When defined, indicates that the compiler supports the <b>cdecl</b> calling convention.
 */
# define    STLSOFT_CDECL_SUPPORTED

/** \def STLSOFT_FASTCALL_SUPPORTED
 * \brief When defined, indicates that the compiler supports the <b>fastcall</b> calling convention.
 */
# define    STLSOFT_FASTCALL_SUPPORTED

/** \def STLSOFT_STDCALL_SUPPORTED
 * \brief When defined, indicates that the compiler supports the <b>stdcall</b> calling convention.
 */
# define    STLSOFT_STDCALL_SUPPORTED
#endif /* STLSOFT_DOCUMENTATION_SKIP_SECTION */


/** \def STLSOFT_CDECL
 * \brief Resolves to the <b>cdecl</b> keyword for the current compiler, or to nothing for compilers
 *  that do not support any calling conventions.
 */

#if !defined(STLSOFT_CDECL)
# define                        STLSOFT_CDECL
#endif /* !STLSOFT_CDECL */

/** \def STLSOFT_FASTCALL
 * \brief Resolves to the <b>fastcall</b> keyword for the current compiler
 */

#if !defined(STLSOFT_FASTCALL)
# if defined(STLSOFT_CF_FASTCALL_SUPPORTED)
#  error Compiler discrimination must define STLSOFT_FASTCALL if STLSOFT_CF_FASTCALL_SUPPORTED is defined
# else /* ? STLSOFT_CF_FASTCALL_SUPPORTED */
#  define                       STLSOFT_FASTCALL
# endif /* STLSOFT_CF_FASTCALL_SUPPORTED */
#endif /* !STLSOFT_FASTCALL */

/** \def STLSOFT_STDCALL
 * \brief Resolves to the <b>stdcall</b> keyword for the current compiler
 */

#if !defined(STLSOFT_STDCALL)
# if defined(STLSOFT_CF_STDCALL_SUPPORTED)
#  error Compiler discrimination must define STLSOFT_STDCALL if STLSOFT_CF_STDCALL_SUPPORTED is defined
# else /* ? STLSOFT_CF_STDCALL_SUPPORTED */
#  define                       STLSOFT_STDCALL
# endif /* STLSOFT_CF_STDCALL_SUPPORTED */
#endif /* !STLSOFT_STDCALL */



#define STLSOFT_CDECL_VALUE         (1)     /*!< \brief A unique value indicating <b>cdecl</b> calling convention. */

#if defined(STLSOFT_CF_FASTCALL_SUPPORTED)
# define STLSOFT_FASTCALL_VALUE     (2)     /*!< \brief A unique value indicating <b>fastcall</b> calling convention. */
#endif /* STLSOFT_CF_FASTCALL_SUPPORTED */

#if defined(STLSOFT_CF_STDCALL_SUPPORTED)
# define STLSOFT_STDCALL_VALUE      (3)     /*!< \brief A unique value indicating <b>stdcall</b> calling convention. */
#endif /* STLSOFT_CF_STDCALL_SUPPORTED */

/* /////////////////////////////////////////////////////////////////////////
 * operator bool()
 *
 * If the symbol STLSOFT_CF_OPERATOR_BOOL_AS_OPERATOR_POINTER_TO_MEMBER_SUPPORT
 * is defined, operator bool should be defined as follows:
 *
 *  class X
 *  {
 *  private:
 *    struct boolean { int i; }
 *    typedef int boolean::*boolean_t;
 *  public:
 *    operator boolean_t () const;
 *
 * otherwise it should be
 *
 *  class X
 *  {
 *  private:
 *    typedef ss_bool_t boolean_t;
 *  public:
 *    operator boolean_t () const;
 *
 *
 * If the symbol STLSOFT_CF_OPERATOR_NOT_VIA_OPERATOR_POINTER_TO_MEMBER_SUPPORT
 * is defined, it means that (!x) can de deduced by the compiler, otherwise it
 * will need to be provided
 *
 * If STLSOFT_CF_OPERATOR_BOOL_AS_OPERATOR_POINTER_TO_MEMBER_SUPPORT is not defined
 * then STLSOFT_CF_OPERATOR_NOT_VIA_OPERATOR_POINTER_TO_MEMBER_SUPPORT should not be
 * defined, so we do a check here.
 *
 */

#if !defined(STLSOFT_CF_OPERATOR_BOOL_AS_OPERATOR_POINTER_TO_MEMBER_SUPPORT) && \
    defined(STLSOFT_CF_OPERATOR_NOT_VIA_OPERATOR_POINTER_TO_MEMBER_SUPPORT)
# error Cannot rely on use of boolean as pointer to member for operator !
# error Undefine STLSOFT_CF_OPERATOR_NOT_VIA_OPERATOR_POINTER_TO_MEMBER_SUPPORT when
# error STLSOFT_CF_OPERATOR_BOOL_AS_OPERATOR_POINTER_TO_MEMBER_SUPPORT is not defined
#endif /* !STLSOFT_CF_OPERATOR_BOOL_AS_OPERATOR_POINTER_TO_MEMBER_SUPPORT && STLSOFT_CF_OPERATOR_NOT_VIA_OPERATOR_POINTER_TO_MEMBER_SUPPORT */

/* /////////////////////////////////////////////////////////////////////////
 * Obsolete symbol definitions
 *
 * Define _STLSOFT_INCLUDE_OBSOLETE to include the definitions of symbols prior
 * to version 1.5.1
 */

/* Verify that the significant changes to STLSoft 1.5.1 are checked with respect
 * to other previously released projects
 */

#if (   defined(_ATLSTL_VER) && \
        _ATLSTL_VER <= 0x00010204) || \
    (   defined(_COMSTL_VER) && \
        _COMSTL_VER <= 0x00010201) || \
    (   defined(_MFCSTL_VER) && \
        _MFCSTL_VER <= 0x00010202) || \
    (   defined(_UNIXSTL_VER) && \
        _UNIXSTL_VER <= 0x00000901) || \
    (   defined(_WINSTL_VER) && \
        _WINSTL_VER <= 0x00010201)
# ifdef STLSOFT_STRICT
#  error You are using an old version of one or more of ATLSTL, COMSTL, MFCSTL, UNIXSTL and WinSTL. Please upgrade all dependent projects in line with the STLSoft version you are using
# else /* ? STLSOFT_STRICT */
#  ifdef STLSOFT_CF_PRAGMA_MESSAGE_SUPPORT
#   pragma message("You are using an old version of one or more of ATLSTL, COMSTL, MFCSTL, UNIXSTL and WinSTL. _STLSOFT_INCLUDE_OBSOLETE will be defined (but is not guaranteed to work!)")
#  endif /* STLSOFT_CF_PRAGMA_MESSAGE_SUPPORT */
#  ifndef _STLSOFT_INCLUDE_OBSOLETE
#   define _STLSOFT_INCLUDE_OBSOLETE
#  endif /* !_STLSOFT_INCLUDE_OBSOLETE */
# endif /* STLSOFT_STRICT */
#endif /* sub-project versions */

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

#ifndef _STLSOFT_NO_STD_INCLUDES
# include <stddef.h>    /* standard types */
# include <stdlib.h>    /* standard constants */
#endif /* !_STLSOFT_NO_STD_INCLUDES */

/* /////////////////////////////////////////////////////////////////////////
 * Debugging
 *
 * The macro STLSOFT_ASSERT provides standard debug-mode assert functionality.
 */

/** \defgroup assertion_macros Assertion Macros
 * \ingroup group__project__stlsoft
 * \brief These macros are used for debugging / contract-enforcement
 * @{
 */

#if defined(_STLSOFT_NO_ASSERT) && \
    defined(STLSOFT_CF_ASSERT_SUPPORT)
# undef STLSOFT_CF_ASSERT_SUPPORT
#endif /* _STLSOFT_NO_ASSERT && STLSOFT_CF_ASSERT_SUPPORT */

/** \def STLSOFT_ASSERT(ex)
 * \brief Defines an assertion construct for runtime verification.
 *
 * \param ex Must be non-zero, or an assertion will be fired
 *
 * \note By default, the macro resolves to the standard macro 
 *  <code>assert()</code> or the equivalent default assertion macro
 *  for the compiler (e.g. <code>_ASSERTE()</code> for Visual C++).
 *  This behaviour can be overriden by not defining: see the
 *  compiler capability file for your compiler (e.g. 
 *  <code>include/stlsoft/internal/cccap/gcc.h</code>) for further
 *  details.
 */
#if defined(STLSOFT_DOCUMENTATION_SKIP_SECTION)
# define STLSOFT_ASSERT(ex)                     assert(ex)
#elif defined(STLSOFT_CF_ASSERT_SUPPORT)
# ifdef __STLSOFT_CF_USE_cassert
  /* Using the standard assertion mechanism, located in <cassert> */
#  include <cassert>
#  define STLSOFT_ASSERT(ex)                    assert(ex)
# else /* ? __STLSOFT_CF_USE_cassert */
  /* Using either a custom or proprietary assertion mechanism, so must
   * provide the header include name
   */
#  ifndef __STLSOFT_CF_ASSERT_INCLUDE_NAME
#   error Must supply an assert include filename with custom or proprietary assertion mechanism
#  else /* ? __STLSOFT_CF_ASSERT_INCLUDE_NAME */
#   include __STLSOFT_CF_ASSERT_INCLUDE_NAME
#  endif /* !__STLSOFT_CF_ASSERT_INCLUDE_NAME */
# endif /* __STLSOFT_CF_USE_cassert */
# if !defined(STLSOFT_ASSERT) && \
     defined(stlsoft_assert)
#  define STLSOFT_ASSERT                        stlsoft_assert
# elif defined(STLSOFT_ASSERT) && \
       defined(stlsoft_assert)
#  error Your compiler discrimination file cannot define both STLSOFT_ASSERT and stlsoft_assert. The former is the new version, and replaces the latter
# endif /* STLSOFT_ASSERT / stlsoft_assert */
# ifndef STLSOFT_ASSERT
#  error If your compiler discrimination file supports assertions, it must define STLSOFT_ASSERT() (taking a single parameter)
# endif /* !STLSOFT_ASSERT */
#endif /* !STLSOFT_CF_ASSERT_SUPPORT */


#ifdef STLSOFT_DOCUMENTATION_SKIP_SECTION
# undef stlsoft_assert
#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

/** \def stlsoft_assert(ex)
 *
 * \brief [DEPRECATED] Defines a runtime assertion
 *
 * \param ex Must be non-zero, or an assertion will be fired
 *
 * \deprecated This is deprecated in favour of \ref STLSOFT_ASSERT().
 *
 * \note This is a simple \#define for STLSOFT_ASSERT()
 */
#ifndef stlsoft_assert
# define stlsoft_assert(ex)                     STLSOFT_ASSERT(ex)
#endif /* !stlsoft_assert */


/** \def STLSOFT_MESSAGE_ASSERT(msg, ex)
 * \brief Defines a runtime assertion, with message
 *
 * \param ex Must be non-zero, or an assertion will be fired
 * \param msg The literal character string message to be included in the assertion