---

stlsoft_char_traits.h

Go to the documentation of this file.

/* 
 * File:        stlsoft_char_traits.h (originally MTCTrait.h, ::SynesisStl)
 *
 * Purpose:     char_traits classes.
 *
 * Created:     19th November 1998
 * Updated:     11th September 2004
 *
 * Home:        http://stlsoft.org/
 *
 * Copyright (c) 1998-2004, 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_H_STLSOFT_CHAR_TRAITS
#define STLSOFT_INCL_H_STLSOFT_CHAR_TRAITS

#ifndef __STLSOFT_DOCUMENTATION_SKIP_SECTION
# define STLSOFT_VER_H_STLSOFT_CHAR_TRAITS_MAJOR        2
# define STLSOFT_VER_H_STLSOFT_CHAR_TRAITS_MINOR        0
# define STLSOFT_VER_H_STLSOFT_CHAR_TRAITS_REVISION     1
# define STLSOFT_VER_H_STLSOFT_CHAR_TRAITS_EDIT         43
#endif /* !__STLSOFT_DOCUMENTATION_SKIP_SECTION */

/* 
 * Includes
 *
 * There is a degree of complexity with respect to the definition and use of
 * char_traits in the STLSoft libraries, depending on whether the std and/or
 * stlsoft namespaces are defined.
 *
 * 1. If neither std nor stlsoft namespaces are defined, then the standard
 * library char_traits is visible in the global namespace, and no definition is
 * provided in the stlsoft namespace. This is necessary to avoid a clash.
 *
 * 2. If std is defined, and the stlsoft namespace is not defined, then the
 * STLSoft definition of char_traits is provided, and exists in the global
 * namespace.
 *
 * 3. If std is not defined, and the stlsoft namespace is defined, then the
 * STLSoft definition of char_traits is provided, and exists in the stlsoft
 * namespace.
 *
 * 4. If both std and stlsoft namespaces are not defined, then the
 * STLSoft definition of char_traits is provided, and exists in the stlsoft
 * namespace.
 *
 * Also influencing this is whether the compiler/std-library actually provide
 * a char_traits type. GCC 2.95 does not. Presence of this is indicated by the
 * definition of __STLSOFT_CF_std_char_traits_AVAILABLE
 *
 * Finally, DMC++ has a problem whereby, with the SGI libs, the specialisation
 * of char_traits in the global namespace clashes with stlsoft::char_traits<>.
 * This is a combination compiler/library bug, so the only thing we can do is
 * indicate to the STLSoft libs that ("std::")char_traits is unavailable, and
 * "use" the standard library one.
 */

#ifndef STLSOFT_INCL_H_STLSOFT
# include "stlsoft.h"               // Include the STLSoft root header
#endif /* !STLSOFT_INCL_H_STLSOFT */
#ifndef STLSOFT_INCL_H_STLSOFT_SIGN_TRAITS
# include "stlsoft_sign_traits.h"   // stlsoft::sign_traits
#endif /* !STLSOFT_INCL_H_STLSOFT_SIGN_TRAITS */
#if defined(__STLSOFT_CF_std_char_traits_AVAILABLE) && \
    defined(_STLSOFT_NO_NAMESPACE) && \
    !defined(__STLSOFT_CF_std_NAMESPACE)
# include <string>                  // std::char_traits
#elif defined(__STLSOFT_COMPILER_IS_DMC) && \
      !defined(__STLSOFT_CF_std_NAMESPACE)
# include <string>                  // std::char_traits
#endif /* !::stlsoft && !::std */
#if !defined(STLSOFT_NO_CHAR_TRAITS_LIBRARY_CALLS) || \
    defined(_DEBUG)
# include <string.h>
# include <wchar.h>
# if defined(__STLSOFT_COMPILER_IS_BORLAND) && \
     __BORLANDC__ >= 0x0560
#  include <mem.h>
#endif /* __BORLANDC__ == 0x0560 */
#endif /* !STLSOFT_NO_CHAR_TRAITS_LIBRARY_CALLS || _DEBUG */

/* 
 * Namespace
 */

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

/* 
 * Constraints
 */

// class stlsoft_char_traits
template<   ss_typename_param_k C
        >
struct stlsoft_char_traits
{
public:
    typedef C                                   char_type;
    typedef stlsoft_char_traits<C>              class_type;
    typedef ss_int_t                            int_type;
    typedef ss_size_t                           size_type;
    typedef ss_streampos_t                      pos_type;
    typedef ss_streamoff_t                      off_type;

public:
    static void assign(char_type &lhs, char_type const &rhs)
    {
        lhs = rhs;
    }

    static char_type *assign(char_type *dest, size_type cch, char_type const &c)
    {
        char_type * ret;

        stlsoft_message_assert("char_traits<X>::assign called with NULL destination", 0 == cch || NULL != dest);

        for(ret = dest; 0 < cch; --cch, ++dest)
        {
            assign(*dest, c);
        }

        return ret;
    }

    static ss_bool_t eq(char_type const &lhs, char_type const &rhs)
    {
        return lhs == rhs;
    }

    static ss_bool_t lt(char_type const &lhs, char_type const &rhs)
    {
        return lhs < rhs;
    }

    static int_type compare(char_type const *s1, char_type const *s2, size_type cch)
    {
        stlsoft_message_assert("char_traits<X>::compare called with NULL string", 0 == cch || NULL != s1);
        stlsoft_message_assert("char_traits<X>::compare called with NULL string", 0 == cch || NULL != s2);

        for(size_type n = 0; n < cch; ++n, ++s1, ++s2)
        {
            if(!eq(*s1, *s2))
            {
                return lt(*s1, *s2) ? -1 : +1;
            }
        }

        return 0;
    }

    static int_type compare_max(char_type const *s1, char_type const *s2, size_type cch)
    {
        stlsoft_message_assert("char_traits<X>::compare_max called with NULL string", 0 == cch || NULL != s1);
        stlsoft_message_assert("char_traits<X>::compare_max called with NULL string", 0 == cch || NULL != s2);

        for(size_type n = 0; n < cch; ++n, ++s1, ++s2)
        {
            if(!eq(*s1, *s2))
            {
                return lt(*s1, *s2) ? -1 : +1;
            }
            else if(eq(*s1, char_type(0)))
            {
                break;
            }
        }

        return 0;
    }

    static int_type compare_null(char_type const *s1, char_type const *s2, size_type cch)
    {
        int_type    result;

        if(NULL == s1)
        {
            result = (NULL == s2) ? 0 : -1;
        }
        else
        {
            result = (NULL == s2) ? 1 : compare(s1, s2, cch);
        }

        return result;
    }

    static int_type compare_maxnull(char_type const *s1, char_type const *s2, size_type cch)
    {
        int_type    result;

        if(NULL == s1)
        {
            result = (NULL == s2) ? 0 : -1;
        }
        else
        {
            result = (NULL == s2) ? 1 : compare_max(s1, s2, cch);
        }

        return result;
    }

    static size_type length(char_type const *s)
    {
        size_type cch;

        stlsoft_message_assert("char_traits<X>::length called with NULL string", NULL != s);

        for(cch = 0; !eq(*s, char_type(0)); ++s)
        {
            ++cch;
        }

        return cch;
    }

    static size_type length_null(char_type const *s)
    {
        return (NULL != s) ? length(s) : 0;
    }

    static size_type length_max(char_type const *s, size_type limit)
    {
        size_type cch;

        stlsoft_message_assert("char_traits<X>::length_max called with NULL string", NULL != s);

        for(cch = 0; cch < limit && !eq(*s, char_type(0)); ++s)
        {
            ++cch;
        }

        return cch;
    }

    static size_type length_max_null(char_type const *s, size_type limit)
    {
        return (NULL != s) ? length_max(s, limit) : 0;
    }

    static char_type *copy(char_type *dest, char_type const *src, size_type cch)
    {
        char_type   *ret;

        stlsoft_message_assert("char_traits<X>::copy called with NULL destination", 0 == cch || NULL != dest);
        stlsoft_message_assert("char_traits<X>::copy called with NULL source", 0 == cch || NULL != src);

#ifdef _DEBUG
        memset(dest, 0, cch * sizeof(char_type));
#endif /* _DEBUG */

        for(ret = dest; 0 < cch; --cch, ++dest, ++src)
        {
            assign(*dest, *src);
        }

        return ret;
    }

    static char_type *move(char_type *dest, char_type const *src, size_type cch)
    {
        char_type *const ret = dest;

        stlsoft_message_assert("char_traits<X>::move called with NULL destination", 0 == cch || NULL != dest);
        stlsoft_message_assert("char_traits<X>::move called with NULL source", 0 == cch || NULL != src);

        if( src < dest &&
            dest < src + cch)
        {
            for(dest += cch, src += cch; 0 < cch; --cch)
            {
                assign(*--dest, *--src);
            }
        }
        else
        {
            for(; 0 < cch; --cch, ++dest, ++src)
            {
                assign(*dest, *src);
            }
        }

        return ret;
    }

    static char_type const *find(char_type const *s, size_type cch, char_type const &c)
    {
        stlsoft_message_assert("char_traits<X>::find called with NULL string", 0 == cch || NULL != s);

        for(; 0 < cch; --cch, ++s)
        {
            if(eq(*s, c))
            {
                break;
            }
        }

        return (0 < cch) ? s : NULL;
    }

    static char_type to_char_type(int_type const &c)
    {
        return static_cast<char_type>(c);
    }

    static int_type to_int_type(char_type const &c)
    {
#if defined(__STLSOFT_COMPILER_IS_WATCOM)
        return (int_type)(c);
#else
        return static_cast<int_type>(static_cast<ss_typename_type_k sign_traits<char_type>::unsigned_type>(c));
#endif /* __STLSOFT_COMPILER_IS_WATCOM */
    }

    static ss_bool_t eq_int_type(int_type const &lhs, int_type const &rhs)
    {
        return lhs == rhs;
    }

    static int_type eof()
    {
        return static_cast<int_type>(-1);
    }

    static int_type not_eof(int_type const &c)
    {
        return (c != eof() ? c : !eof());
    }
};

// class stlsoft_char_traits_safe
template<   ss_typename_param_k C
        >
struct stlsoft_char_traits_safe
    : private stlsoft_char_traits<C>
{
private:
    typedef stlsoft_char_traits<C>              parent_class_type;
public:
    typedef C                                   char_type;
    typedef stlsoft_char_traits_safe<C>         class_type;
    typedef ss_int_t                            int_type;
    typedef ss_size_t                           size_type;
    typedef ss_streampos_t                      pos_type;
    typedef ss_streamoff_t                      off_type;

public:
    static void assign(char_type &lhs, char_type const &rhs)
    {
        parent_class_type::assign(lhs, rhs);
    }

    static char_type *assign(char_type *dest, size_type cch, char_type const &c)
    {
        stlsoft_message_assert("char_traits_safe<X>::assign called with NULL destination", NULL != dest);

        return parent_class_type::assign(dest, cch, c);
    }

    static ss_bool_t eq(char_type const &lhs, char_type const &rhs)
    {
        return parent_class_type::eq(lhs, rhs);
    }

    static ss_bool_t lt(char_type const &lhs, char_type const &rhs)
    {
        return parent_class_type::lt(lhs, rhs);
    }

    static int_type compare(char_type const *s1, char_type const *s2, size_type cch)
    {
        return compare_null(s1, s2, cch);
    }

    static int_type compare_max(char_type const *s1, char_type const *s2, size_type cch)
    {
        return compare_maxnull(s1, s2, cch);
    }

    static int_type compare_null(char_type const *s1, char_type const *s2, size_type cch)
    {
        return parent_class_type::compare(s1, s2, cch);
    }

    static int_type compare_maxnull(char_type const *s1, char_type const *s2, size_type cch)
    {
        return parent_class_type::compare_maxnull(s1, s2, cch);
    }

    static size_type length_max_null(char_type const *s, size_type limit)
    {
        return (NULL == s) ? 0 : parent_class_type::length_max(s, limit);
    }

    static size_type length_max(char_type const *s, size_type limit)
    {
        return length_max_null(s, limit);
    }

    static size_type length_null(char_type const *s)
    {
        return (NULL == s) ? 0 : parent_class_type::length(s);
    }

    static size_type length(char_type const *s)
    {
        return length_null(s);
    }

    static char_type *copy(char_type *dest, char_type const *src, size_type cch)
    {
        stlsoft_message_assert("char_traits_safe<X>::copy called with NULL destination", NULL != dest);
        stlsoft_message_assert("char_traits_safe<X>::copy called with NULL source", NULL != src);

        return parent_class_type::copy(dest, src, cch);
    }

    static char_type *move(char_type *dest, char_type const *src, size_type cch)
    {
        stlsoft_message_assert("char_traits_safe<X>::move called with NULL destination", NULL != dest);
        stlsoft_message_assert("char_traits_safe<X>::move called with NULL source", NULL != src);

        return parent_class_type::move(dest, src, cch);
    }

    static char_type const *find(char_type const *s, size_type cch, char_type const &c)
    {
        return (NULL == s) ? NULL : parent_class_type::find(s, cch, c);
    }

    static char_type to_char_type(int_type const &c)
    {
        return parent_class_type::to_char_type(c);
    }

    static int_type to_int_type(char_type const &c)
    {
        return parent_class_type::to_int_type(c);
    }

    static ss_bool_t eq_int_type(int_type const &lhs, int_type const &rhs)
    {
        return parent_class_type::eq_int_type(lhs, rhs);
    }

    static int_type eof()
    {
        return parent_class_type::eof();
    }

    static int_type not_eof(int_type const &c)
    {
        return parent_class_type::not_eof();
    }
};

// class char_traits

/* DMC++ special handling */
#if defined(__STLSOFT_COMPILER_IS_DMC) &&   /* compiler is DMC++ */ \
    !defined(__STLSOFT_CF_std_NAMESPACE)    /* std namespace is not defined */

# if !defined(__SGI_STL_STRING_FWD_H)
#  error Unexpected
# endif /* !__SGI_STL_STRING_FWD_H */
# if !defined(__SGI_STL_CHAR_TRAITS_H)
#  error Unexpected
# endif /* !__SGI_STL_CHAR_TRAITS_H */

using ::char_traits;
#else /* ? comp/lib */

/* We only define (stlsoft::)char_traits if no std::char_traits is available, or
 * the stlsoft namespace is defined, or the std namespace is defined.
 */
 #if !defined(__STLSOFT_CF_std_char_traits_AVAILABLE) || /* std does not define char_traits */ \
     !defined(_STLSOFT_NO_NAMESPACE) ||                 /* stlsoft namespace is defined */ \
     defined(__STLSOFT_CF_std_NAMESPACE)
template<   ss_typename_param_k C
        >
struct char_traits
    : public stlsoft_char_traits<C>
{
    typedef stlsoft_char_traits<C>                          parent_class_type;
public:
    typedef char_traits<C>                                  class_type;
    typedef ss_typename_type_k parent_class_type::char_type char_type;
    typedef ss_typename_type_k parent_class_type::int_type  int_type;
    typedef ss_typename_type_k parent_class_type::size_type size_type;
    typedef ss_typename_type_k parent_class_type::pos_type  pos_type;
    typedef ss_typename_type_k parent_class_type::off_type  off_type;
};
# endif /* !::stlsoft && !::std */
#endif /* comp/lib */

// class char_traits_safe
template<   ss_typename_param_k C
        >
struct char_traits_safe
    : public stlsoft_char_traits_safe<C>
{
    typedef stlsoft_char_traits_safe<C>                     parent_class_type;
public:
    typedef char_traits_safe<C>                             class_type;
    typedef ss_typename_type_k parent_class_type::char_type char_type;
    typedef ss_typename_type_k parent_class_type::int_type  int_type;
    typedef ss_typename_type_k parent_class_type::size_type size_type;
    typedef ss_typename_type_k parent_class_type::pos_type  pos_type;
    typedef ss_typename_type_k parent_class_type::off_type  off_type;
};

/* 
 * Specialisations
 */

#ifndef __STLSOFT_DOCUMENTATION_SKIP_SECTION

#if !defined(STLSOFT_NO_CHAR_TRAITS_LIBRARY_CALLS) && \
    !defined(__STLSOFT_COMPILER_IS_DMC) && \
    (   !defined(__STLSOFT_COMPILER_IS_MSVC) || \
        _MSC_VER >= 1100) && \
    !defined(__STLSOFT_COMPILER_IS_VECTORC) && \
    !defined(__STLSOFT_COMPILER_IS_WATCOM)

/* char */

STLSOFT_TEMPLATE_SPECIALISATION
inline char *stlsoft_char_traits<char>::assign(char *dest, ss_size_t cch, char const &c)
{
    return static_cast<char*>(memset(dest, c, cch * sizeof(char)));
}

STLSOFT_TEMPLATE_SPECIALISATION
inline ss_int_t stlsoft_char_traits<char>::compare(char_type const *s1, char_type const *s2, ss_size_t cch)
{
    return memcmp(s1, s2, cch);
}

STLSOFT_TEMPLATE_SPECIALISATION
inline char const *stlsoft_char_traits<char>::find(char_type const *s, size_type cch, char_type const &c)
{
#if defined(__STLSOFT_COMPILER_IS_BORLAND) && \
    __BORLANDC__ < 0x0560
    return static_cast<char const*>(memchr(s, c, cch));
#else /* ? compiler */
    void const  *p = memchr(s, c, cch);

    return static_cast<char const*>(p);
#endif /* compiler */
}

STLSOFT_TEMPLATE_SPECIALISATION
inline char *stlsoft_char_traits<char>::copy(char *dest, char const *src, ss_size_t cch)
{
#ifdef _DEBUG
    memset(dest, 0, cch * sizeof(char));
#endif /* _DEBUG */

    return static_cast<char*>(memcpy(dest, src, cch * sizeof(char)));
}

STLSOFT_TEMPLATE_SPECIALISATION
inline ss_size_t stlsoft_char_traits<char>::length(char const *s)
{
    return strlen(s);
}

/* wchar_t */

STLSOFT_TEMPLATE_SPECIALISATION
inline ss_size_t stlsoft_char_traits<wchar_t>::length(wchar_t const *s)
{
    return wcslen(s);
}

#endif /* !STLSOFT_NO_CHAR_TRAITS_LIBRARY_CALLS && !__STLSOFT_COMPILER_IS_DMC */

#endif /* !__STLSOFT_DOCUMENTATION_SKIP_SECTION */

// Unit-testing

#ifdef STLSOFT_UNITTEST

namespace unittest
{
    ss_bool_t test_stlsoft_char_traits(unittest_reporter *r)
    {
        ss_bool_t               bSuccess    =   true;

        unittest_initialiser    init(r, "STLSoft", "char_traits", __FILE__);

#if 0
        if(<<TODO>>)
        {
            r->report("<<TODO>> failed ", __LINE__);
            bSuccess = false;
        }
#endif /* 0 */

        return bSuccess;
    }

    unittest_registrar    unittest_stlsoft_char_traits(test_stlsoft_char_traits);

} // namespace unittest

#endif /* STLSOFT_UNITTEST */

/* 

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

/* 

#endif /* !STLSOFT_INCL_H_STLSOFT_CHAR_TRAITS */

/* 

STLSoft Libraries documentation © Synesis Software Pty Ltd, 2001-2004