c_string.h

新版本TR1的stl

/** \brief \ref group__concept__shim__string_access__c_str_ptr function
 *    for <code>wchar_t const*</code>.
 *
 * \return None-NULL, non-mutating pointer to a nul-terminated C-style
 *   string of <code>wchar_t</code>.
 */
inline ss_char_w_t const* c_str_ptr(ss_char_w_t const* s)
{
    return c_str_ptr_w(s);
}
#endif /* __cplusplus */

#ifdef __cplusplus
/* C-style ANSI string */
# ifdef _STLSOFT_STRING_ACCESS_ALLOW_NON_CONST
/** \brief \ref group__concept__shim__string_access__c_str_ptr function
 *    for <code>char const*</code>.
 *
 * \return None-NULL, non-mutating pointer to a nul-terminated C-style
 *   string of <code>char</code>.
 */
inline ss_char_a_t const* c_str_ptr_a(ss_char_a_t *s)
{
    return (NULL != s) ? s : "";
}

/** \brief \ref group__concept__shim__string_access__c_str_ptr function
 *    for <code>char const*</code>.
 *
 * \ingroup group__concept__shim__string_access
 *
 * \return None-NULL, non-mutating pointer to a nul-terminated C-style
 *   string of <code>char</code>.
 */
inline ss_char_a_t const* c_str_ptr(ss_char_a_t *s)
{
    return c_str_ptr_a(s);
}

/* C-style Unicode string */
/** \brief \ref group__concept__shim__string_access__c_str_ptr function
 *    for <code>wchar_t const*</code>.
 *
 * \ingroup group__concept__shim__string_access
 *
 * \return None-NULL, non-mutating pointer to a nul-terminated C-style
 *   string of <code>wchar_t</code>.
 */
inline ss_char_w_t const* c_str_ptr_w(ss_char_w_t *s)
{
    return (NULL != s) ? s : L"";
}

/** \brief \ref group__concept__shim__string_access__c_str_ptr function
 *    for <code>wchar_t const*</code>.
 *
 * \ingroup group__concept__shim__string_access
 *
 * \return None-NULL, non-mutating pointer to a nul-terminated C-style
 *   string of <code>wchar_t</code>.
 */
inline ss_char_w_t const* c_str_ptr(ss_char_w_t *s)
{
    return c_str_ptr_w(s);
}
# endif /* _STLSOFT_STRING_ACCESS_ALLOW_NON_CONST */
#endif /* __cplusplus */

/* /////////////////////////////////////////////////////////////////////////
 * 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 \ref group__concept__shim__string_access__c_str_ptr_null function
 *    for <code>char const*</code>.
 *
 * \ingroup group__concept__shim__string_access
 *
 * \return Possibly NULL, non-mutating pointer to a nul-terminated C-style
 *   string of <code>char</code>. If <code>s</code> is NULL, or has zero
 *   length, NULL is returned.
 */
STLSOFT_INLINE ss_char_a_t const* c_str_ptr_null_a(ss_char_a_t const* s)
{
    return (NULL == s || '\0' == *s) ? NULL : s;
}

#ifdef __cplusplus
/** \brief \ref group__concept__shim__string_access__c_str_ptr_null function
 *    for <code>char const*</code>.
 *
 * \ingroup group__concept__shim__string_access
 *
 * \return Possibly NULL, non-mutating pointer to a nul-terminated C-style
 *   string of <code>char</code>. If <code>s</code> is NULL, or has zero
 *   length, NULL is returned.
 */
inline ss_char_a_t const* c_str_ptr_null(ss_char_a_t const* s)
{
    return c_str_ptr_null_a(s);
}
#endif /* __cplusplus */

/* C-style Unicode string */
/** \brief \ref group__concept__shim__string_access__c_str_ptr_null function
 *    for <code>wchar_t const*</code>.
 *
 * \ingroup group__concept__shim__string_access
 *
 * \return Possibly NULL, non-mutating pointer to a nul-terminated C-style
 *   string of <code>wchar_t</code>. If <code>s</code> is NULL, or has zero
 *   length, NULL is returned.
 */
STLSOFT_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;
}

#ifdef __cplusplus
/** \brief \ref group__concept__shim__string_access__c_str_ptr_null function
 *    for <code>wchar_t const*</code>.
 *
 * \ingroup group__concept__shim__string_access
 *
 * \return Possibly NULL, non-mutating pointer to a nul-terminated C-style
 *   string of <code>wchar_t</code>. If <code>s</code> is NULL, or has zero
 *   length, NULL is returned.
 */
inline ss_char_w_t const* c_str_ptr_null(ss_char_w_t const* s)
{
    return c_str_ptr_null_w(s);
}
#endif /* __cplusplus */

#ifdef __cplusplus

/* C-style ANSI string */
# ifdef _STLSOFT_STRING_ACCESS_ALLOW_NON_CONST
/** \brief \ref group__concept__shim__string_access__c_str_ptr_null function
 *    for <code>char const*</code>.
 *
 * \ingroup group__concept__shim__string_access
 *
 * \return Possibly NULL, non-mutating pointer to a nul-terminated C-style
 *   string of <code>char</code>. If <code>s</code> is NULL, or has zero
 *   length, NULL is returned.
 */
inline ss_char_a_t const* c_str_ptr_null_a(ss_char_a_t *s)
{
    return (NULL == s || '\0' == *s) ? NULL : s;
}

/** \brief \ref group__concept__shim__string_access__c_str_ptr_null function
 *    for <code>char const*</code>.
 *
 * \ingroup group__concept__shim__string_access
 *
 * \return Possibly NULL, non-mutating pointer to a nul-terminated C-style
 *   string of <code>char</code>. If <code>s</code> is NULL, or has zero
 *   length, NULL is returned.
 */
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 \ref group__concept__shim__string_access__c_str_ptr_null function
 *    for <code>wchar_t const*</code>.
 *
 * \ingroup group__concept__shim__string_access
 *
 * \return Possibly NULL, non-mutating pointer to a nul-terminated C-style
 *   string of <code>wchar_t</code>. If <code>s</code> is NULL, or has zero
 *   length, NULL is returned.
 */
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 \ref group__concept__shim__string_access__c_str_ptr_null function
 *    for <code>wchar_t const*</code>.
 *
 * \ingroup group__concept__shim__string_access
 *
 * \return Possibly NULL, non-mutating pointer to a nul-terminated C-style
 *   string of <code>wchar_t</code>. If <code>s</code> is NULL, or has zero
 *   length, NULL is returned.
 */
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 */

# if 0 /* TODO: Try and make this work. Sometime. Maybe ... */
/** \brief Generic implementation of \ref group__concept__shim__string_access__c_str_ptr_null
 *    function for any type for which c_str_ptr_a is defined.
 *
 * \ingroup group__concept__shim__string_access
 *
 * \return Possibly NULL, non-mutating pointer to a nul-terminated C-style
 *   string of <code>char</code>. If <code>s</code> is NULL, or has zero
 *   length, NULL is returned.
 */
template <ss_typename_param_k S>
inline ss_char_a_t const* c_str_ptr_null_a(S const& s)
{
    return stlsoft_ns_qual(c_str_ptr_null_a)(static_cast<ss_char_a_t const*>(stlsoft_ns_qual(c_str_ptr_a)(s))));
}
/** \brief Generic implementation of \ref group__concept__shim__string_access__c_str_ptr_null
 *    function for any type for which c_str_ptr_w is defined.
 *
 * \ingroup group__concept__shim__string_access
 *
 * \return Possibly NULL, non-mutating pointer to a nul-terminated C-style
 *   string of <code>wchar_t</code>. If <code>s</code> is NULL, or has zero
 *   length, NULL is returned.
 */
template <ss_typename_param_k S>
inline ss_char_w_t const* c_str_ptr_null_w(S const& s)
{
    return stlsoft_ns_qual(c_str_ptr_null_w)(static_cast<ss_char_w_t const*>(stlsoft_ns_qual(c_str_ptr_w)(s))));
}
# endif /* 0 */

#endif /* __cplusplus */

/* /////////////////////////////////////////////////////////////////////////
 * c_str_size
 *
 * This can be applied to an expression, and the return value is the number of
 * bytes required to store the character string in the expression, NOT including
 * the null-terminating character.
 */

/* C-style ANSI string */
/** \brief \ref group__concept__shim__string_access__c_str_size function
 *    for <code>char const*</code>.
 *
 * \ingroup group__concept__shim__string_access
 *
 * \return The number of bytes required to represent the contents of the
 *   character string pointed to by <code>s</code>, excluding a
 *   nul-terminating character.
 */
STLSOFT_INLINE ss_size_t c_str_size_a(ss_char_a_t const* s)
{
    return c_str_len_a(s) * sizeof(ss_char_a_t);
}

#ifdef __cplusplus
/** \brief \ref group__concept__shim__string_access__c_str_size function
 *    for <code>char const*</code>.
 *
 * \ingroup group__concept__shim__string_access
 *
 * \return The number of bytes required to represent the contents of the
 *   character string pointed to by <code>s</code>, excluding a
 *   nul-terminating character.
 */
inline ss_size_t c_str_size(ss_char_a_t const* s)
{
    return c_str_size_a(s);
}
#endif /* __cplusplus */

/* C-style Unicode string */
/** \brief \ref group__concept__shim__string_access__c_str_size function
 *    for <code>wchar_t const*</code>.
 *
 * \ingroup group__concept__shim__string_access
 *
 * \return The number of bytes required to represent the contents of the
 *   character string pointed to by <code>s</code>, excluding a
 *   nul-terminating character.
 */
STLSOFT_INLINE ss_size_t c_str_size_w(ss_char_w_t const* s)
{
    return c_str_len_w(s) * sizeof(ss_char_w_t);
}

#ifdef __cplusplus
/** \brief \ref group__concept__shim__string_access__c_str_size function
 *    for <code>wchar_t const*</code>.
 *
 * \ingroup group__concept__shim__string_access
 *
 * \return The number of bytes required to represent the contents of the
 *   character string pointed to by <code>s</code>, excluding a
 *   nul-terminating character.
 */
inline ss_size_t c_str_size(ss_char_w_t const* s)
{
    return c_str_size_w(s);
}
#endif /* __cplusplus */

#ifdef __cplusplus

/* C-style ANSI string */
# ifdef _STLSOFT_STRING_ACCESS_ALLOW_NON_CONST
/** \brief \ref group__concept__shim__string_access__c_str_size function
 *    for <code>char const*</code>.
 *
 * \ingroup group__concept__shim__string_access
 *
 * \return The number of bytes required to represent the contents of the
 *   character string pointed to by <code>s</code>, excluding a
 *   nul-terminating character.
 */
inline ss_size_t c_str_size_a(ss_char_a_t *s)
{
    return c_str_len(s) * sizeof(ss_char_a_t);
}

/** \brief \ref group__concept__shim__string_access__c_str_size function
 *    for <code>char const*</code>.
 *
 * \ingroup group__concept__shim__string_access
 *
 * \return The number of bytes required to represent the contents of the
 *   character string pointed to by <code>s</code>, excluding a
 *   nul-terminating character.
 */
inline ss_size_t c_str_size(ss_char_a_t *s)
{
    return c_str_size_a(s);
}

/* C-style Unicode string */
/** \brief \ref group__concept__shim__string_access__c_str_size function
 *    for <code>wchar_t const*</code>.
 *
 * \ingroup group__concept__shim__string_access
 *
 * \return The number of bytes required to represent the contents of the
 *   character string pointed to by <code>s</code>, excluding a
 *   nul-terminating character.
 */
inline ss_size_t c_str_size_w(ss_char_w_t *s)
{
    return c_str_len(s) * sizeof(ss_char_w_t);
}

/** \brief \ref group__concept__shim__string_access__c_str_size function
 *    for <code>wchar_t const*</code>.
 *
 * \ingroup group__concept__shim__string_access
 *
 * \return The number of bytes required to represent the contents of the
 *   character string pointed to by <code>s</code>, excluding a
 *   nul-terminating character.
 */
inline ss_size_t c_str_size(ss_char_w_t *s)
{
    return c_str_size_w(s);
}
# endif /* _STLSOFT_STRING_ACCESS_ALLOW_NON_CONST */

/** \brief Generic implementation of \ref group__concept__shim__string_access__c_str_size
 *    function for any type for which c_str_len_a is defined.
 *
 * \ingroup group__concept__shim__string_access
 *
 * \return The number of bytes required to represent the contents of the
 *   character string pointed to by <code>s</code>, excluding a
 *   nul-terminating character.
 */
template <ss_typename_param_k S>
inline ss_size_t c_str_size_a(S const& s)
{
    return sizeof(ss_char_a_t) * c_str_len_a(s);
}

/** \brief Generic implementation of \ref group__concept__shim__string_access__c_str_size
 *    function for any type for which c_str_len_w is defined.
 *
 * \ingroup group__concept__shim__string_access
 *
 * \return The number of bytes required to represent the contents of the
 *   character string pointed to by <code>s</code>, excluding a
 *   nul-terminating character.
 */
template <ss_typename_param_k S>
inline ss_size_t c_str_size_w(S const& s)
{
    return sizeof(ss_char_w_t) * c_str_len_w(s);
}

/** \brief Generic implementation of \ref group__concept__shim__string_access__c_str_size
 *    function for any type for which c_str_len is defined.
 *
 * \ingroup group__concept__shim__string_access
 *
 * \return The number of bytes required to represent the contents of the
 *   character string pointed to by <code>s</code>, excluding a
 *   nul-terminating character.
 */
template <ss_typename_param_k S>
inline ss_size_t c_str_size(S const& s)
{
    return sizeof(*c_str_ptr(s)) * c_str_len(s);
}

/** \brief Implementation of \ref group__concept__shim__string_access__c_str_size
 *    for trapping use of literal <code>0</code> or <code>NULL</code>.
 *
 * \ingroup group__concept__shim__string_access
 *
 * \return The return type is <code>cannot_use_untyped_0_or_NULL_with_shims</code>,
 *   which serves to remind users, via compilation error message, that
 *   they're attempting something disallowed.
 */
inline cannot_use_untyped_0_or_NULL_with_shims c_str_size(int deny_literal_NULL);

#endif /* __cplusplus */

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

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

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

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

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

#endif /* !STLSOFT_INCL_STLSOFT_SHIMS_ACCESS_STRING_STD_H_C_STRING */

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