string_access.hpp

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

/* /////////////////////////////////////////////////////////////////////////
 * File:        stlsoft/string_access.hpp (formerly stlsoft_string_access.h)
 *
 * Purpose:     Contains the c_str_ptr, c_str_ptr_null, c_str_len, and
 *              c_str_size accessors.
 *
 * Created:     16th January 2002
 * Updated:     10th June 2006
 *
 * Thanks to:   Robert Kreger for spotting a bug in the discrimination of wide
 *              character support on GCC 3.3.3.
 *
 * 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/string_access.hpp
///
/// \brief [C++ only] Contains the c_str_ptr, c_str_ptr_null, c_str_len, and c_str_size accessors.

#ifndef STLSOFT_INCL_STLSOFT_HPP_STRING_ACCESS
#define STLSOFT_INCL_STLSOFT_HPP_STRING_ACCESS

#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
# define STLSOFT_VER_STLSOFT_HPP_STRING_ACCESS_MAJOR       3
# define STLSOFT_VER_STLSOFT_HPP_STRING_ACCESS_MINOR       5
# define STLSOFT_VER_STLSOFT_HPP_STRING_ACCESS_REVISION    1
# define STLSOFT_VER_STLSOFT_HPP_STRING_ACCESS_EDIT        81
#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

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

#ifndef STLSOFT_INCL_STLSOFT_H_STLSOFT
# include <stlsoft/stlsoft.h>
#endif /* !STLSOFT_INCL_STLSOFT_H_STLSOFT */
#ifndef STLSOFT_INCL_STLSOFT_HPP_STRING_ACCESS_FWD
# include <stlsoft/string_access_fwd.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_HPP_STRING_ACCESS_FWD */

#ifdef STLSOFT_CF_STRING_ACCESS_USE_std_char_traits
# undef STLSOFT_CF_STRING_ACCESS_USE_std_char_traits
#endif /* STLSOFT_CF_STRING_ACCESS_USE_std_char_traits */

/* No currently supported Watcom version can handle std::string. */
#ifdef STLSOFT_COMPILER_IS_WATCOM
# define STLSOFT_STRING_ACCESS_NO_STD_STRING
#endif /* compiler */

/* <string> is included for two reasons:
 *
 * (i) for std::string
 * (ii) for std::char_traits
 *
 * If STLSOFT_STRING_ACCESS_NO_STD_STRING is defined, then <string> is not
 * included, and STLSOFT_CF_STRING_ACCESS_USE_std_char_traits is not
 * defined.
 *
 * If _STLSOFT_NO_NAMESPACE is defined then
 * STLSOFT_CF_STRING_ACCESS_USE_std_char_traits is not defined.
 *
 * If STLSOFT_CF_std_char_traits_AVAILABLE is not defined then
 * STLSOFT_CF_STRING_ACCESS_USE_std_char_traits is not defined.
 *
 */

#ifdef _STLSOFT_STRING_ACCESS_NO_STD_STRING
# define STLSOFT_STRING_ACCESS_NO_STD_STRING
#endif /* _STLSOFT_STRING_ACCESS_NO_STD_STRING */

#if defined(STLSOFT_STRING_ACCESS_NO_STD_STRING)
# undef STLSOFT_CF_STRING_ACCESS_USE_std_char_traits
#elif defined(_STLSOFT_NO_NAMESPACE)
# undef STLSOFT_CF_STRING_ACCESS_USE_std_char_traits
#elif !defined(STLSOFT_CF_std_char_traits_AVAILABLE)
# undef STLSOFT_CF_STRING_ACCESS_USE_std_char_traits
#else /* ? Use char_traits? */
# define STLSOFT_CF_STRING_ACCESS_USE_std_char_traits
#endif /* Use char_traits? */

/* Are we going to cater for std::(w)string? */
#ifndef STLSOFT_STRING_ACCESS_NO_STD_STRING
# include <string>
#endif /* STLSOFT_STRING_ACCESS_NO_STD_STRING */

/* Include stlsoft_char_traits if not using std::string, or std::char_traits
 * is not available.
 */
#if !defined(STLSOFT_CF_STRING_ACCESS_USE_std_char_traits)
# ifndef STLSOFT_INCL_STLSOFT_STRING_HPP_CHAR_TRAITS
#  include <stlsoft/string/char_traits.hpp>
# endif /* !STLSOFT_INCL_STLSOFT_STRING_HPP_CHAR_TRAITS */
#endif /* !STLSOFT_CF_STRING_ACCESS_USE_std_char_traits */

#if defined(STLSOFT_COMPILER_IS_GCC)
# include <wchar.h>
#endif /* compiler */

#ifdef STLSOFT_UNITTEST
# include <stdio.h>
#endif /* STLSOFT_UNITTEST */

/* /////////////////////////////////////////////////////////////////////////
 * Pre-processor control
 *
 * By default, conversions from non-const strings, or rather from pointers to
 * non-const characters, are not allowed, since the implied semantics for a
 * pointer-to-const character representing a null-terminated string are stronger
 * than those for a pointer-to-non-const character.
 *
 * However, you can override this by defining the symbol
 * _STLSOFT_STRING_ACCESS_ALLOW_NON_CONST, which will then treat both the types
 * (in fact all four types: char*; char const*; wchar_t*; wchar_t const*) as
 * representing null-terminated strings.
 */

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

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

/* /////////////////////////////////////////////////////////////////////////
 * Typedefs
 */

#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION

#ifndef STLSOFT_STRING_ACCESS_NO_STD_STRING
# if defined(STLSOFT_COMPILER_IS_GCC) && \
     (   __GNUC__ < 3 /* TODO: This is probably not needed now, so may remove it in a future version ... */ || \
         !defined(_GLIBCPP_USE_WCHAR_T)) // Thanks to Robert Kreger for suggesting this fix for GCC 3.3.3 on HP UX
  typedef stlsoft_ns_qual_std(basic_string)<ss_char_w_t>    _stlsoft_wstring_t;
# else /* ? GCC */
  typedef stlsoft_ns_qual_std(wstring)                      _stlsoft_wstring_t;
# endif /* STLSOFT_COMPILER_IS_GCC) && __GNUC__ < 3 */
#endif /* STLSOFT_STRING_ACCESS_NO_STD_STRING */

#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

/** \brief Inert class that connotes an invalid use of a string access shim
 *   function by forcing a compile-time error.
 *
 * \ingroup group__library__string__string_access_shims
 */
struct cannot_use_untyped_0_or_NULL_with_shims;

/* /////////////////////////////////////////////////////////////////////////
 * c_str_ptr_null
 *
 * This can be applied to an expression, and the return value is either a
 * pointer to the character string or NULL.
 */

/* C-style ANSI string */
/// \brief Returns the corresponding C-string pointer of \c s, or a null pointer
inline ss_char_a_t const *c_str_ptr_null_a(ss_char_a_t const *s)
{
    return (NULL == s || '\0' == *s) ? NULL : s;
}

/// \brief Returns the corresponding C-string pointer of \c s, or a null pointer
inline ss_char_a_t const *c_str_ptr_null(ss_char_a_t const *s)
{
    return c_str_ptr_null_a(s);
}

/* C-style Unicode string */
/// \brief Returns the corresponding C-string pointer of \c s, or a null pointer
inline ss_char_w_t const *c_str_ptr_null_w(ss_char_w_t const *s)
{
    return (NULL == s || L'\0' == *s) ? NULL : s;
}

/// \brief Returns the corresponding C-string pointer of \c s, or a null pointer
inline ss_char_w_t const *c_str_ptr_null(ss_char_w_t const *s)
{
    return c_str_ptr_null_w(s);
}

/* C-style ANSI string */
#ifdef _STLSOFT_STRING_ACCESS_ALLOW_NON_CONST
/// \brief Returns the corresponding C-string pointer of \c s, or a null pointer
inline ss_char_a_t const *c_str_ptr_null_a(ss_char_a_t *s)
{
    return (NULL == s || '\0' == *s) ? NULL : s;
}

/// \brief Returns the corresponding C-string pointer of \c s, or a null pointer
inline ss_char_a_t const *c_str_ptr_null(ss_char_a_t *s)
{
    return c_str_ptr_null_a(s);
}

/* C-style Unicode string */
/// \brief Returns the corresponding C-string pointer of \c s, or a null pointer
inline ss_char_w_t const *c_str_ptr_null_w(ss_char_w_t *s)
{
    return (NULL == s || L'\0' == *s) ? NULL : s;
}

/// \brief Returns the corresponding C-string pointer of \c s, or a null pointer
inline ss_char_w_t const *c_str_ptr_null(ss_char_w_t *s)
{
    return c_str_ptr_null_w(s);
}
#endif /* _STLSOFT_STRING_ACCESS_ALLOW_NON_CONST */

/* std::basic_string */
#ifndef STLSOFT_STRING_ACCESS_NO_STD_STRING
# if defined(STLSOFT_COMPILER_IS_MSVC) && \
     _MSC_VER < 1100
/// \brief Returns the corresponding C-string pointer of \c s, or a null pointer
inline ss_char_a_t const *c_str_ptr_null_a(string const &s)
{
    return (0 == s.length()) ? 0 : s.c_str();
}

/// \brief Returns the corresponding C-string pointer of \c s, or a null pointer
inline ss_char_a_t const *c_str_ptr_null(string const &s)
{
    return c_str_ptr_null_a(s);
}

/// \brief Returns the corresponding C-string pointer of \c s, or a null pointer
inline ss_char_w_t const *c_str_ptr_null_w(wstring const &s)
{
    return (0 == s.length()) ? 0 : s.c_str();
}

/// \brief Returns the corresponding C-string pointer of \c s, or a null pointer
inline ss_char_w_t const *c_str_ptr_null(wstring const &s)
{
    return c_str_ptr_null_w(s);
}
# else /* ? compiler */
/// \brief Returns the corresponding C-string pointer of \c s, or a null pointer
inline ss_char_a_t const *c_str_ptr_null_a(stlsoft_ns_qual_std(string) const &s)
{
    return (0 == s.length()) ? 0 : s.c_str();
}

#  if !defined(STLSOFT_COMPILER_IS_GCC) || \
      !(__GNUC__ < 3)
/// \brief Returns the corresponding C-string pointer of \c s, or a null pointer
inline ss_char_w_t const *c_str_ptr_null_w(_stlsoft_wstring_t const &s)
{
    return (0 == s.length()) ? 0 : s.c_str();
}
#  endif /* compiler */

/// \brief Returns the corresponding C-string pointer of \c s, or a null pointer
template<   ss_typename_param_k C
        ,   ss_typename_param_k T
        ,   ss_typename_param_k A
        >
inline C const *c_str_ptr_null(stlsoft_ns_qual_std(basic_string)<C, T, A> const &s)
{
    return (0 == s.length()) ? 0 : s.c_str();
}

# endif /* STLSOFT_COMPILER_IS_MSVC && _MSC_VER < 1100 */
#endif /* STLSOFT_STRING_ACCESS_NO_STD_STRING */

/* stlport::basic_string */
#if defined(_STLP_USE_NAMESPACES) && \
    defined(_STLP_USE_OWN_NAMESPACE) && \
    !defined(_STLP_REDEFINE_STD) && \
    (   !defined(_STLPORT_MAJOR) || \
        _STLPORT_MAJOR < 5)
/// \brief Returns the corresponding C-string pointer of \c s, or a null pointer
inline ss_char_a_t const *c_str_ptr_null_a(stlport::string const &s)
{
    return (0 == s.length()) ? 0 : s.c_str();
}

/// \brief Returns the corresponding C-string pointer of \c s, or a null pointer
inline ss_char_w_t const *c_str_ptr_null_w(stlport::wstring const &s)
{
    return (0 == s.length()) ? 0 : s.c_str();
}

/// \brief Returns the corresponding C-string pointer of \c s, or a null pointer
template <ss_typename_param_k C>
inline C const *c_str_ptr_null(stlport::basic_string<C> const &s)
{
    return (0 == s.length()) ? 0 : s.c_str();
}
#endif /* _STLP_USE_NAMESPACES && _STLP_USE_OWN_NAMESPACE */

#if 0
/** \brief Function template that provide generic implementations of
 *   c_str_ptr_null_a for any type for which c_str_ptr_a is defined.
 *
 * \ingroup group__shims__string_access
 */
template <ss_typename_param_k S>
inline ss_char_a_t const *c_str_ptr_null_a(S const &s)