stlsoft/string/special_string_instance.hpp

Go to the documentation of this file.

/* /////////////////////////////////////////////////////////////////////////
 * File:        stlsoft/string/special_string_instance.hpp
 *
 * Purpose:     Special string instance class template.
 *
 * Created:     3rd June 2006
 * Updated:     10th August 2009
 *
 * Thanks to:   Pablo Aguilar for spotting my omission of string access shims
 *              for special_string_instance_1.
 *
 * Home:        http://stlsoft.org/
 *
 * Copyright (c) 2006-2009, 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.
 *
 * ////////////////////////////////////////////////////////////////////// */


#ifndef STLSOFT_INCL_STLSOFT_STRING_HPP_SPECIAL_STRING_INSTANCE
#define STLSOFT_INCL_STLSOFT_STRING_HPP_SPECIAL_STRING_INSTANCE

#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
# define STLSOFT_VER_STLSOFT_STRING_HPP_SPECIAL_STRING_INSTANCE_MAJOR       1
# define STLSOFT_VER_STLSOFT_STRING_HPP_SPECIAL_STRING_INSTANCE_MINOR       2
# define STLSOFT_VER_STLSOFT_STRING_HPP_SPECIAL_STRING_INSTANCE_REVISION    5
# define STLSOFT_VER_STLSOFT_STRING_HPP_SPECIAL_STRING_INSTANCE_EDIT        19
#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

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

/*
[Incompatibilies-start]
STLSOFT_COMPILER_IS_MSVC:       _MSC_VER<1200
[Incompatibilies-end]
 */

/* Compatibility
[<[STLSOFT-AUTO:NO-DOCFILELABEL]>]
[<[STLSOFT-AUTO:NO-UNITTEST]>]
*/

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

#ifndef STLSOFT_INCL_STLSOFT_H_STLSOFT
# include <stlsoft/stlsoft.h>
#endif /* !STLSOFT_INCL_STLSOFT_H_STLSOFT */
#ifndef STLSOFT_INCL_STLSOFT_MEMORY_HPP_AUTO_BUFFER
# include <stlsoft/memory/auto_buffer.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_MEMORY_HPP_AUTO_BUFFER */
#ifndef STLSOFT_INCL_STLSOFT_META_HPP_IS_SAME_TYPE
# include <stlsoft/meta/is_same_type.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_META_HPP_IS_SAME_TYPE */
#ifndef STLSOFT_INCL_STLSOFT_META_HPP_SELECT_FIRST_TYPE_IF
# include <stlsoft/meta/select_first_type_if.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_META_HPP_SELECT_FIRST_TYPE_IF */
#ifndef STLSOFT_INCL_STLSOFT_SYNCH_HPP_LOCK_SCOPE
# include <stlsoft/synch/lock_scope.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_SYNCH_HPP_LOCK_SCOPE */

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

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

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

#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION

template<   ss_typename_param_k C
        ,   ss_size_t           N
        ,   ss_typename_param_k A
        ,   ss_typename_param_k A0
        >
struct ssi_buffer
{
public:
    typedef C                                                   char_type;
    typedef A                                                   allocator_type;
    typedef ss_size_t                                           size_type;
    typedef A0                                                  argument_0_type;
#if defined(STLSOFT_COMPILER_IS_BORLAND)
    typedef stlsoft::auto_buffer<char_type, 128, allocator_type>  buffer_type;
#else /* ? compiler */
    typedef stlsoft::auto_buffer<char_type, N, allocator_type>  buffer_type;
#endif /* compiler */

public:
    ssi_buffer()
        : m_len(0)
        , m_buffer(0)
    {}

    void init(size_type (*pfn)(char_type*, size_type))
    {
        size_type cch = pfn(NULL, 0);   // We don't pass NULL here, just in case

        if(m_buffer.resize(1 + cch))
        {
            for(;;)
            {
                cch = pfn(&m_buffer[0], m_buffer.size());

                if(cch < m_buffer.size())
                {
                    m_len = cch;
                    break;
                }
                else
                {
                    if(!m_buffer.resize(2 * m_buffer.size()))
                    {
                        m_buffer.resize(0);
                        break;
                    }
                }
            }
        }

        m_buffer[m_len] = '\0';
    }

    void init(argument_0_type arg0, size_type (*pfn)(argument_0_type, char_type*, size_type))
    {
        size_type cch = pfn(arg0, NULL, 0);   // We don't pass NULL here, just in case

        if(m_buffer.resize(1 + cch))
        {
            for(;;)
            {
                cch = pfn(arg0, &m_buffer[0], m_buffer.size());

                if(cch < m_buffer.size())
                {
                    m_len = cch;
                    break;
                }
                else
                {
                    if(!m_buffer.resize(2 * m_buffer.size()))
                    {
                        m_buffer.resize(0);
                        break;
                    }
                }
            }
        }

        m_buffer[m_len] = '\0';
    }

public:
    char_type const* data() const
    {
        return m_buffer.data();
    }
    size_type       length() const
    {
        return m_len;
    }

private:
    size_type       m_len;
    buffer_type     m_buffer;
};

template<   ss_typename_param_k C
        ,   ss_size_t           N
        ,   ss_typename_param_k A
        ,   ss_typename_param_k A0
        >
struct ssi_buffer_non_static
    : public ssi_buffer<C, N, A, A0>
{
public:
    typedef ssi_buffer<C, N, A, A0>                         ssi_buffer_type;
    typedef ssi_buffer<C, N, A, A0>                         parent_class_type;
    typedef ssi_buffer_non_static<C, N, A, A0>              class_type;

    typedef ss_typename_type_k ssi_buffer_type::char_type   char_type;
    typedef ss_typename_type_k ssi_buffer_type::size_type   size_type;

public:
    ssi_buffer_non_static(size_type (*pfn)(char_type*, size_type))
    {
        parent_class_type::init(pfn);
    }
    ssi_buffer_non_static(A0 a0, size_type (*pfn)(A0, char_type*, size_type))
    {
        parent_class_type::init(a0, pfn);
    }

public:
    char_type const* data() const
    {
        return parent_class_type::data();
    }
    size_type       length() const
    {
        return parent_class_type::length();
    }

private:
    ssi_buffer_non_static(class_type const&);
    class_type& operator =(class_type const&);
};

template<   ss_typename_param_k C
        ,   ss_size_t           N
        ,   ss_typename_param_k A
        ,   ss_typename_param_k A0
        ,   ss_typename_param_k P   // Passes policy type, from which spin_mutex_type is elicited, so non-statics do not need to specify it
        >
struct ssi_buffer_static
{
public:
    typedef ssi_buffer<C, N, A, A0>                         ssi_buffer_type;
    typedef ssi_buffer_static<C, N, A, A0, P>               class_type;

    typedef ss_typename_type_k ssi_buffer_type::char_type   char_type;
    typedef ss_typename_type_k ssi_buffer_type::size_type   size_type;
private:
    typedef P                                               policy_type;
    typedef ss_typename_type_k policy_type::spin_mutex_type spin_mutex_type;

public:
    ssi_buffer_static(size_type (*pfn)(char_type*, size_type))
        : m_buffer(get_buffer(pfn))
    {}
    ssi_buffer_static(A0 a0, size_type (*pfn)(A0, char_type*, size_type))
        : m_buffer(a0, get_buffer(a0, pfn))
    {}

public:
    char_type const* data() const
    {
        return m_buffer.data();
    }
    size_type       length() const
    {
        return m_buffer.length();
    }

private:
    static ssi_buffer_type &get_buffer(size_type (*pfn)(char_type*, size_type))
    {
        static ss_sint32_t                      s_count =   0;
        static bool                             s_bInit =   false;
        spin_mutex_type                         mx(&s_count);
        stlsoft::lock_scope<spin_mutex_type>    lock(mx);

        static ssi_buffer_type                  s_buffer;

        if(!s_bInit)
        {
            s_buffer.init(pfn);

            s_bInit = true;
        }

        return s_buffer;
    }
    static ssi_buffer_type &get_buffer(A0 a0, size_type (*pfn)(A0, char_type*, size_type))
    {
        static ss_sint32_t                      s_count =   0;
        static bool                             s_bInit =   false;
        spin_mutex_type                         mx(&s_count);
        stlsoft::lock_scope<spin_mutex_type>    lock(mx);

        static ssi_buffer_type                  s_buffer;

        if(!s_bInit)
        {
            s_buffer.init(a0, pfn);

            s_bInit = true;
        }

        return s_buffer;
    }

private:
    ssi_buffer_type     &m_buffer;

private:
    ssi_buffer_static(class_type const&);
    class_type& operator =(class_type const&);
};

#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */


template <ss_typename_param_k P>
class special_string_instance_0
{
public:
    typedef P                                                                   policy_type;
    typedef special_string_instance_0<P>                                        class_type;
    typedef ss_typename_type_k policy_type::char_type                           char_type;
    typedef ss_typename_type_k policy_type::size_type                           size_type;

private:
    enum { charTypeIsAnsi = is_same_type<ss_char_a_t, char_type>::value };
public:
    typedef ss_typename_type_k select_first_type_if<
        ss_char_a_t const*
    ,   void
    ,   charTypeIsAnsi
    >::type                                                                     cstring_a_type;
private:
    enum { charTypeIsWide = is_same_type<ss_char_w_t, char_type>::value };
public:
    typedef ss_typename_type_k select_first_type_if<
        ss_char_w_t const*
    ,   void
    ,   charTypeIsWide
    >::type                                                                     cstring_w_type;
private:
    typedef ss_typename_type_k policy_type::pfn_type                            pfn_type;
private:
    // This section allows for the case where the policy does not define an
    // allocator, which it indicates by defining its member type
    // allocator_type to be void.
    typedef ss_typename_type_k policy_type::allocator_type                      putative_allocator_type;
    enum
    {
        policy_has_allocator_type       =   (0 != size_of<putative_allocator_type>::value)
    };
    typedef ss_typename_type_k allocator_selector<char_type>::allocator_type    backup_allocator_type;
public:
    typedef ss_typename_type_k select_first_type_if<
        putative_allocator_type
    ,   backup_allocator_type
    ,   policy_has_allocator_type
    >::type                                                                     allocator_type;
private:
    enum { allowImplicitConversion = policy_type::allowImplicitConversion };
public:
    typedef ss_typename_type_k select_first_type_if<
        char_type const*
    ,   void
    ,   allowImplicitConversion
    >::type                                                                     implicit_conversion_type;
private:
    // This section accounts for whether the policy indicates shared state.
    // If so, then the buffer type resolves to the appropriate
    // specialisation of ssi_buffer_static, which stores a threadsafe buffer
    // shared by all instances. If not, then the buffer type resolves to
    // ssi_buffer_non_static, which stores a buffer per instance.
    enum
    {
        policy_indicates_shared_state   =   (0 != policy_type::sharedState)
    };

    struct null_argument
    {};

    enum { internalBufferSize = policy_type::internalBufferSize };
    typedef ssi_buffer_static<
        char_type
    ,   internalBufferSize
    ,   allocator_type
    ,   null_argument
    ,   policy_type // Passes policy type, from which spin_mutex_type is elicited, so non-statics do not need to specify it
    >                                                                           ssi_buffer_static_type;
    typedef ssi_buffer_non_static<
        char_type
    ,   internalBufferSize
    ,   allocator_type
    ,   null_argument
    >                                                                           ssi_buffer_non_static_type;

    typedef ss_typename_type_k select_first_type_if<
        ssi_buffer_static_type
    ,   ssi_buffer_non_static_type
    ,   policy_indicates_shared_state
    >::type                                                                     buffer_type;

public:
    special_string_instance_0()
        : m_buffer(policy_type::get_fn())
    {}

public:
    size_type       length() const
    {
        return m_buffer.length();
    }
    size_type       size() const
    {
        return length();
    }

    char_type const* data() const
    {
        return m_buffer.data();
    }
    char_type const* c_str() const
    {
        return data();
    }

#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
    cstring_a_type  c_str_a() const
    {
        return c_str();
    }
    cstring_w_type  c_str_w() const
    {
        return c_str();
    }
#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

public:
#if !defined(STLSOFT_COMPILER_IS_BORLAND)
    operator implicit_conversion_type () const
    {
        return this->c_str();
    }
#endif /* compiler */

public:
    static size_type get(char_type* buffer, size_type cchBuffer)
    {
        return (policy_type::get_fn())(buffer, cchBuffer);
    }

private:
    buffer_type     m_buffer;
};

template <ss_typename_param_k P>
class special_string_instance_1
{
public:
    typedef P                                                                   policy_type;
    typedef special_string_instance_1<P>                                        class_type;
    typedef ss_typename_type_k policy_type::char_type                           char_type;
    typedef ss_typename_type_k policy_type::size_type                           size_type;
    typedef ss_typename_type_k policy_type::argument_0_type                     argument_0_type;

private:
    enum { charTypeIsAnsi = is_same_type<ss_char_a_t, char_type>::value };
public:
    typedef ss_typename_type_k select_first_type_if<
        ss_char_a_t const*
    ,   void
    ,   charTypeIsAnsi
    >::type                                                                     cstring_a_type;
private:
    enum { charTypeIsWide = is_same_type<ss_char_w_t, char_type>::value };
public:
    typedef ss_typename_type_k select_first_type_if<
        ss_char_w_t const*
    ,   void
    ,   charTypeIsWide
    >::type                                                                     cstring_w_type;
private:
    typedef ss_typename_type_k policy_type::pfn_type                            pfn_type;
private:
    // This section allows for the case where the policy does not define an
    // allocator, which it indicates by defining its member type
    // allocator_type to be void.
    typedef ss_typename_type_k policy_type::allocator_type                      putative_allocator_type;
    enum
    {
        policy_has_allocator_type       =   (0 != size_of<putative_allocator_type>::value)
    };
    typedef ss_typename_type_k allocator_selector<char_type>::allocator_type    backup_allocator_type;
public:
    typedef ss_typename_type_k select_first_type_if<
        putative_allocator_type
    ,   backup_allocator_type
    ,   policy_has_allocator_type
    >::type                                                                     allocator_type;

private:
    enum { allowImplicitConversion = policy_type::allowImplicitConversion };
public:
    typedef ss_typename_type_k select_first_type_if<
        char_type const*
    ,   void
    ,   allowImplicitConversion
    >::type                                                                     implicit_conversion_type;
private:
    // This section accounts for whether the policy indicates shared state.
    // If so, then the buffer type resolves to the appropriate
    // specialisation of ssi_buffer_static, which stores a threadsafe buffer
    // shared by all instances. If not, then the buffer type resolves to
    // ssi_buffer_non_static, which stores a buffer per instance.
    enum
    {
        policy_indicates_shared_state   =   (0 != policy_type::sharedState)
    };

    enum { internalBufferSize = policy_type::internalBufferSize };
    typedef ssi_buffer_static<
        char_type
    ,   internalBufferSize
    ,   allocator_type
    ,   argument_0_type
    ,   policy_type // Passes policy type, from which spin_mutex_type is elicited, so non-statics do not need to specify it
    >                                                                           ssi_buffer_static_type;
    typedef ssi_buffer_non_static<
        char_type
    ,   internalBufferSize
    ,   allocator_type
    ,   argument_0_type
    >                                                                           ssi_buffer_non_static_type;

    typedef ss_typename_type_k select_first_type_if<
        ssi_buffer_static_type
    ,   ssi_buffer_non_static_type
    ,   policy_indicates_shared_state
    >::type                                                                     buffer_type;


public:
    special_string_instance_1(argument_0_type argument)
        : m_buffer(argument, policy_type::get_fn())
    {}

public:
    static size_type get(argument_0_type argument, char_type* buffer, size_type cchBuffer)
    {
        return (policy_type::get_fn())(argument, buffer, cchBuffer);
    }

public:
    char_type const* c_str() const
    {
        return m_buffer.data();
    }
    char_type const* data() const
    {
        return m_buffer.data();
    }
    size_type       length() const
    {
        return m_buffer.length();
    }
    size_type       size() const
    {
        return length();
    }

#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
    cstring_a_type  c_str_a() const
    {
        return c_str();
    }
    cstring_w_type  c_str_w() const
    {
        return c_str();
    }
#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

public:
#if !defined(STLSOFT_COMPILER_IS_BORLAND)
    operator implicit_conversion_type () const
    {
        return this->c_str();
    }
#endif /* compiler */

private:
    buffer_type     m_buffer;
};

/* /////////////////////////////////////////////////////////////////////////
 * Shims
 */

template <ss_typename_param_k P>
inline ss_typename_type_ret_k special_string_instance_0<P>::char_type const* c_str_ptr_null(stlsoft_ns_qual(special_string_instance_0)<P> const& ssi)
{
    return (0 != ssi.length()) ? ssi.c_str() : NULL;
}
#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
template <ss_typename_param_k P>
inline ss_typename_type_ret_k special_string_instance_0<P>::cstring_a_type c_str_ptr_null_a(stlsoft_ns_qual(special_string_instance_0)<P> const& ssi)
{
    return (0 != ssi.length()) ? ssi.c_str_a() : NULL;
}
template <ss_typename_param_k P>
inline ss_typename_type_ret_k special_string_instance_0<P>::cstring_w_type c_str_ptr_null_w(stlsoft_ns_qual(special_string_instance_0)<P> const& ssi)
{
    return (0 != ssi.length()) ? ssi.c_str_w() : NULL;
}
#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

template <ss_typename_param_k P>
inline ss_typename_type_ret_k special_string_instance_0<P>::char_type const* c_str_ptr(stlsoft_ns_qual(special_string_instance_0)<P> const& ssi)
{
    return ssi.c_str();
}
#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
template <ss_typename_param_k P>
inline ss_typename_type_ret_k special_string_instance_0<P>::cstring_a_type c_str_ptr_a(stlsoft_ns_qual(special_string_instance_0)<P> const& ssi)
{
    return ssi.c_str_a();
}
template <ss_typename_param_k P>
inline ss_typename_type_ret_k special_string_instance_0<P>::cstring_w_type c_str_ptr_w(stlsoft_ns_qual(special_string_instance_0)<P> const& ssi)
{
    return ssi.c_str_w();
}
#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

template <ss_typename_param_k P>
inline ss_typename_type_ret_k special_string_instance_0<P>::char_type const* c_str_data(stlsoft_ns_qual(special_string_instance_0)<P> const& ssi)
{
    return ssi.c_str();
}
#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
template <ss_typename_param_k P>
inline ss_typename_type_ret_k special_string_instance_0<P>::cstring_a_type c_str_data_a(stlsoft_ns_qual(special_string_instance_0)<P> const& ssi)
{
    return ssi.c_str_a();
}
template <ss_typename_param_k P>
inline ss_typename_type_ret_k special_string_instance_0<P>::cstring_w_type c_str_data_w(stlsoft_ns_qual(special_string_instance_0)<P> const& ssi)
{
    return ssi.c_str_w();
}
#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

template <ss_typename_param_k P>
inline ss_size_t c_str_len(stlsoft_ns_qual(special_string_instance_0)<P> const& ssi)
{
    return ssi.length();
}
#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
template <ss_typename_param_k P>
inline ss_size_t c_str_len_a(stlsoft_ns_qual(special_string_instance_0)<P> const& ssi)
{
    // If this fires, you're trying to invoke c_str_len_w() on an SSI
    // whose policy defines the character type to be something other
    // than char.
    ss_char_a_t const   *special_string_instance_must_use_narrow_character  =   ssi.c_str_a();

    STLSOFT_SUPPRESS_UNUSED(special_string_instance_must_use_narrow_character);

    return ssi.length();
}
template <ss_typename_param_k P>
inline ss_size_t c_str_len_w(stlsoft_ns_qual(special_string_instance_0)<P> const& ssi)
{
    // If this fires, you're trying to invoke c_str_len_w() on an SSI
    // whose policy defines the character type to be something other
    // than wchar_t.
    ss_char_w_t const   *special_string_instance_must_use_wide_character    =   ssi.c_str_w();

    STLSOFT_SUPPRESS_UNUSED(special_string_instance_must_use_wide_character);

    return ssi.length();
}
#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

template <ss_typename_param_k P>
inline ss_typename_type_ret_k special_string_instance_1<P>::char_type const* c_str_ptr_null(stlsoft_ns_qual(special_string_instance_1)<P> const& ssi)
{
    return (0 != ssi.length()) ? ssi.c_str() : NULL;
}
#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
template <ss_typename_param_k P>
inline ss_typename_type_ret_k special_string_instance_1<P>::cstring_a_type c_str_ptr_null_a(stlsoft_ns_qual(special_string_instance_1)<P> const& ssi)
{
    return (0 != ssi.length()) ? ssi.c_str_a() : NULL;
}
template <ss_typename_param_k P>
inline ss_typename_type_ret_k special_string_instance_1<P>::cstring_w_type c_str_ptr_null_w(stlsoft_ns_qual(special_string_instance_1)<P> const& ssi)
{
    return (0 != ssi.length()) ? ssi.c_str_w() : NULL;
}
#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

template <ss_typename_param_k P>
inline ss_typename_type_ret_k special_string_instance_1<P>::char_type const* c_str_ptr(stlsoft_ns_qual(special_string_instance_1)<P> const& ssi)
{
    return ssi.c_str();
}
#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
template <ss_typename_param_k P>
inline ss_typename_type_ret_k special_string_instance_1<P>::cstring_a_type c_str_ptr_a(stlsoft_ns_qual(special_string_instance_1)<P> const& ssi)
{
    return ssi.c_str_a();
}
template <ss_typename_param_k P>
inline ss_typename_type_ret_k special_string_instance_1<P>::cstring_w_type c_str_ptr_w(stlsoft_ns_qual(special_string_instance_1)<P> const& ssi)
{
    return ssi.c_str_w();
}
#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

template <ss_typename_param_k P>
inline ss_typename_type_ret_k special_string_instance_1<P>::char_type const* c_str_data(stlsoft_ns_qual(special_string_instance_1)<P> const& ssi)
{
    return ssi.c_str();
}
#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
template <ss_typename_param_k P>
inline ss_typename_type_ret_k special_string_instance_1<P>::cstring_a_type c_str_data_a(stlsoft_ns_qual(special_string_instance_1)<P> const& ssi)
{
    return ssi.c_str_a();
}
template <ss_typename_param_k P>
inline ss_typename_type_ret_k special_string_instance_1<P>::cstring_w_type c_str_data_w(stlsoft_ns_qual(special_string_instance_1)<P> const& ssi)
{
    return ssi.c_str_w();
}
#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

template <ss_typename_param_k P>
inline ss_size_t c_str_len(stlsoft_ns_qual(special_string_instance_1)<P> const& ssi)
{
    return ssi.length();
}
#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
template <ss_typename_param_k P>
inline ss_size_t c_str_len_a(stlsoft_ns_qual(special_string_instance_1)<P> const& ssi)
{
    // If this fires, you're trying to invoke c_str_len_w() on an SSI
    // whose policy defines the character type to be something other
    // than char.
    ss_char_a_t const   *special_string_instance_must_use_narrow_character  =   ssi.c_str_a();

    STLSOFT_SUPPRESS_UNUSED(special_string_instance_must_use_narrow_character);

    return ssi.length();
}
template <ss_typename_param_k P>
inline ss_size_t c_str_len_w(stlsoft_ns_qual(special_string_instance_1)<P> const& ssi)
{
    // If this fires, you're trying to invoke c_str_len_w() on an SSI
    // whose policy defines the character type to be something other
    // than wchar_t.
    ss_char_w_t const   *special_string_instance_must_use_wide_character    =   ssi.c_str_w();

    STLSOFT_SUPPRESS_UNUSED(special_string_instance_must_use_wide_character);

    return ssi.length();
}
#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

/* ////////////////////////////////////////////////////////////////////// */

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

/* ////////////////////////////////////////////////////////////////////// */

#endif /* !STLSOFT_INCL_STLSOFT_STRING_HPP_SPECIAL_STRING_INSTANCE */

/* ///////////////////////////// end of file //////////////////////////// */

---