bstr.hpp

新版本TR1的stl

/* /////////////////////////////////////////////////////////////////////////
 * File:        comstl/string/bstr.hpp (originally MOBStr.h/.cpp, ::SynesisCom)
 *
 * Purpose:     bstr class.
 *
 * Created:     20th December 1996
 * Updated:     19th August 2007
 *
 * Thanks:      To Gabor Fischer for requesting attach().
 *
 * Home:        http://stlsoft.org/
 *
 * Copyright (c) 1996-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/string/bstr.hpp
 *
 * \brief [C++ only; requires COM] Definition of the comstl::bstr class
 *   (\ref group__library__utility__com "COM Utility" Library).
 */

#ifndef COMSTL_INCL_COMSTL_STRING_HPP_BSTR
#define COMSTL_INCL_COMSTL_STRING_HPP_BSTR

#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
# define _COMSTL_VER_COMSTL_STRING_HPP_BSTR_MAJOR       2
# define _COMSTL_VER_COMSTL_STRING_HPP_BSTR_MINOR       7
# define _COMSTL_VER_COMSTL_STRING_HPP_BSTR_REVISION    1
# define _COMSTL_VER_COMSTL_STRING_HPP_BSTR_EDIT        54
#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

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

#ifndef COMSTL_INCL_COMSTL_H_COMSTL
# include <comstl/comstl.h>
#endif /* !COMSTL_INCL_COMSTL_H_COMSTL */
//#ifndef COMSTL_INCL_COMSTL_SHIMS_ACCESS_HPP_STRING
//# include <comstl/shims/access/string.hpp>
//#endif /* !COMSTL_INCL_COMSTL_SHIMS_ACCESS_HPP_STRING */
#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 */
#ifndef COMSTL_INCL_COMSTL_STRING_H_BSTR_FUNCTIONS
# include <comstl/string/bstr_functions.h>
#endif /* !COMSTL_INCL_COMSTL_STRING_H_BSTR_FUNCTIONS */
#ifndef STLSOFT_INCL_STLSOFT_SHIMS_ACCESS_HPP_STRING
# include <stlsoft/shims/access/string.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_SHIMS_ACCESS_HPP_STRING */
#ifndef STLSOFT_INCL_STLSOFT_STRING_HPP_STRING_TRAITS_FWD
# include <stlsoft/string/string_traits_fwd.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_STRING_HPP_STRING_TRAITS_FWD */
#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 */
#ifndef STLSOFT_INCL_STLSOFT_UTIL_HPP_STD_SWAP
# include <stlsoft/util/std_swap.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_UTIL_HPP_STD_SWAP */
#ifdef STLSOFT_CF_EXCEPTION_SUPPORT
# include <stdexcept>
#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
 */

/** \brief Facade for the COM BSTR type
 *
 * \ingroup group__library__utility__com
 */
class bstr
{
/// \name Member Types
/// @{
public:
    typedef bstr                                            class_type;
    typedef cs_char_o_t                                     char_type;
    typedef char_type                                       value_type;
    typedef char_type*                                      pointer;
    typedef char_type const*                                const_pointer;
    typedef char_type&                                      reference;
    typedef char_type const&                                const_reference;
    typedef cs_ptrdiff_t                                    difference_type;
    typedef cs_size_t                                       size_type;
    typedef cs_bool_t                                       bool_type;
    typedef pointer                                         iterator;
    typedef const_pointer                                   const_iterator;
#if defined(STLSOFT_CF_BIDIRECTIONAL_ITERATOR_SUPPORT)
    typedef stlsoft_ns_qual(reverse_iterator_base)< iterator
                                                ,   value_type
                                                ,   reference
                                                ,   pointer
                                                ,   difference_type
                                                >           reverse_iterator;

    typedef stlsoft_ns_qual(const_reverse_iterator_base)<   const_iterator
                                                    ,   value_type const
                                                    ,   const_reference
                                                    ,   const_pointer
                                                    ,   difference_type
                                                    >       const_reverse_iterator;
#endif /* STLSOFT_CF_BIDIRECTIONAL_ITERATOR_SUPPORT */

    typedef BSTR                                            resource_type;
/// @}

/// \name Construction
/// @{
public:
    bstr();
    ss_explicit_k bstr(cs_char_a_t const* s, int len = -1);
    ss_explicit_k bstr(cs_char_w_t const* s, int len = -1);
    bstr(size_type n, char_type ch);
    /// \brief Copy constructor
    bstr(class_type const& rhs);
    bstr(class_type const& rhs, size_type pos, size_type len);
    ~bstr() stlsoft_throw_0();

    /// \brief Copies the given instance
    class_type& operator =(class_type const& rhs);

    class_type  &assign(cs_char_a_t const* s, int len = -1);
    class_type  &assign(cs_char_w_t const* s, int len = -1);

    class_type  &assign(const_iterator from, const_iterator to);

    class_type& operator =(cs_char_a_t const* s);
    class_type& operator =(cs_char_w_t const* s);

    class_type& attach(BSTR bstr);

    BSTR        detach();

    void        clear();
/// @}

/// \name Operations
/// @{
public:
    class_type& append(class_type const& s, int len = -1);
    class_type& append(cs_char_w_t const* s, int len = -1);

    class_type& operator +=(class_type const& s);
    class_type& operator +=(cs_char_w_t const* s);
/// @}

/// \name Accessors
/// @{
public:
    const_pointer   data() const;
    const_pointer   c_str() const;
    size_type       length() const;
    size_type       size() const;
    bool_type       empty() const;
    BSTR            get() const;
    reference       operator [](size_type);
    const_reference operator [](size_type) const;

    const_pointer   *NonDestructiveAddress() const;
    BSTR            *NonDestructiveAddress();
    BSTR            *DestructiveAddress();
/// @}

/// \name Iteration
/// @{
public:
    /// Begins the iteration
    ///
    /// \return An iterator representing the start of the sequence
    iterator                begin();
    /// Ends the iteration
    ///
    /// \return An iterator representing the end of the sequence
    iterator                end();
    /// Begins the iteration
    ///
    /// \return A non-mutable (const) iterator representing the start of the sequence
    const_iterator          begin() const;
    /// Ends the iteration
    ///
    /// \return A non-mutable (const) iterator representing the end of the sequence
    const_iterator          end() const;

#if defined(STLSOFT_CF_BIDIRECTIONAL_ITERATOR_SUPPORT)
    /// Begins the reverse iteration
    ///
    /// \return A non-mutable (const) iterator representing the start of the reverse sequence
    const_reverse_iterator  rbegin() const;
    /// Ends the reverse iteration
    ///
    /// \return A non-mutable (const) iterator representing the end of the reverse sequence
    const_reverse_iterator  rend() const;
    /// Begins the reverse iteration
    ///
    /// \return An iterator representing the start of the reverse sequence
    reverse_iterator        rbegin();
    /// Ends the reverse iteration
    ///
    /// \return An iterator representing the end of the reverse sequence
    reverse_iterator        rend();
#endif /* STLSOFT_CF_BIDIRECTIONAL_ITERATOR_SUPPORT */
/// @}

/// \name Comparison
/// @{
public:
    /// \brief Evaluates whether the value is equivalent to the given argument
    bool_type equal(class_type const& rhs) const;
    /// \brief Evaluates whether the value is equivalent to the given argument
    bool_type equal(BSTR const& rhs) const;
/// @}

/// \name Operations
/// @{
public:
    /// \brief Swaps the contents with the given instance
    void swap(class_type& rhs) stlsoft_throw_0();
    /// \brief Swaps the contents with the given BSTR
    void swap(BSTR& rhs) stlsoft_throw_0();
/// @}

/// \name Members
/// @{
private:
    BSTR    m_bstr;
/// @}
};

/* /////////////////////////////////////////////////////////////////////////
 * String access shims
 */

/** \brief \ref group__concept__shim__string_access__c_str_data for comstl::bstr
 *
 * \ingroup group__concept__shim__string_access
 */
inline bstr::const_pointer c_str_data(comstl_ns_qual(bstr) const& b)
{
    return b.data();
}

#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION

inline bstr::const_pointer c_str_data_w(comstl_ns_qual(bstr) const& b)
{
    return b.data();
}

inline bstr::const_pointer c_str_data_o(comstl_ns_qual(bstr) const& b)
{
    return b.data();
}

#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

/** \brief \ref group__concept__shim__string_access__c_str_len for comstl::bstr
 *
 * \ingroup group__concept__shim__string_access
 */
inline cs_size_t c_str_len(comstl_ns_qual(bstr) const& b)
{
    return b.length();
}

#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION

inline cs_size_t c_str_len_w(comstl_ns_qual(bstr) const& b)
{
    return b.length();
}

inline cs_size_t c_str_len_o(comstl_ns_qual(bstr) const& b)
{
    return b.length();
}

#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

/** \brief \ref group__concept__shim__string_access__c_str_ptr for comstl::bstr
 *
 * \ingroup group__concept__shim__string_access
 */
inline bstr::const_pointer c_str_ptr(comstl_ns_qual(bstr) const& b)
{
    return b.c_str();
}

#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION

inline bstr::const_pointer c_str_ptr_w(comstl_ns_qual(bstr) const& b)
{
    return b.c_str();
}

inline bstr::const_pointer c_str_ptr_o(comstl_ns_qual(bstr) const& b)
{
    return b.c_str();
}

#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

/** \brief \ref group__concept__shim__string_access__c_str_ptr_null for comstl::bstr
 *
 * \ingroup group__concept__shim__string_access
 */
inline bstr::const_pointer c_str_ptr_null(comstl_ns_qual(bstr) const& b)
{
    return stlsoft_ns_qual(c_str_ptr_null)(b.c_str());
}

#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION

inline bstr::const_pointer c_str_ptr_null_w(comstl_ns_qual(bstr) const& b)
{
    return stlsoft_ns_qual(c_str_ptr_null_w)(b.c_str());
}

inline bstr::const_pointer c_str_ptr_null_o(comstl_ns_qual(bstr) const& b)
{
    return stlsoft_ns_qual(c_str_ptr_null)(b.c_str());
}

/** \brief \ref group__concept__shim__stream_insertion "stream insertion shim" for comstl::bstr
 *
 * \ingroup group__concept__shim__stream_insertion
 */
template<   ss_typename_param_k S
        >
inline S& operator <<(S &stm, comstl_ns_qual(bstr) const& str)
{
    STLSOFT_STATIC_ASSERT(sizeof(OLECHAR) == sizeof(ss_typename_type_k S::char_type));

    stm << str.c_str();

    return stm;
}

#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

/* /////////////////////////////////////////////////////////////////////////
 * Operators
 */

inline cs_bool_t operator ==(bstr const& lhs, bstr const& rhs)
{
    return lhs.equal(rhs);
}

inline cs_bool_t operator !=(bstr const& lhs, bstr const& rhs)
{
    return !operator ==(lhs, rhs);
}

inline cs_bool_t operator ==(bstr const& lhs, BSTR const& rhs)
{
    return lhs.equal(rhs);
}

inline cs_bool_t operator !=(bstr const& lhs, BSTR const& rhs)
{
    return !operator ==(lhs, rhs);
}

inline cs_bool_t operator ==(BSTR const& lhs, bstr const& rhs)
{
    return rhs.equal(lhs);
}

inline cs_bool_t operator !=(BSTR const& lhs, bstr const& rhs)
{
    return !operator ==(lhs, rhs);
}

////////////////////////////////////////////////////////////////////////////
// Unit-testing

#ifdef STLSOFT_UNITTEST
# include "./unittest/bstr_unittest_.h"
#endif /* STLSOFT_UNITTEST */

/* /////////////////////////////////////////////////////////////////////////
 * Implementation
 */

#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION

// Construction
inline bstr::bstr()
    : m_bstr(NULL)
{}

inline /* explicit */ bstr::bstr(cs_char_a_t const* s, int len /* = -1 */)
{
    // Precondition tests
    COMSTL_MESSAGE_ASSERT("Default length must be specified by -1. No other -ve value allowed", len >= 0 || len == -1);
    COMSTL_MESSAGE_ASSERT("Cannot pass in NULL pointer and -1 (default) length", NULL != s || len >= 0);

    // There's a potential problem here (which has actually occurred!):
    //
    // If s is non-NULL and len is non-negative, it's possible for
    // the underlying SysAllocStringLen() to walk into invalid
    // memory while searching s.

    int actualLen = static_cast<int>(stlsoft_ns_qual(c_str_len)(s));

    if( NULL != s &&
        len > actualLen)
    {
        m_bstr = bstr_create(static_cast<cs_char_w_t const*>(NULL), static_cast<cs_size_t>(len));

        if(NULL != m_bstr)
        {
            ::MultiByteToWideChar(0, 0, s, actualLen + 1, m_bstr, actualLen + 1);
        }
    }
    else
    {
        if(-1 == len)
        {
            len = actualLen;
        }