xsstring.h

Go to the documentation of this file.

/* +------------------------------------------------------------------------+
   |                     Mobile Robot Programming Toolkit (MRPT)            |
   |                          https://www.mrpt.org/                         |
   |                                                                        |
   | Copyright (c) 2005-2019, Individual contributors, see AUTHORS file     |
   | See: https://www.mrpt.org/Authors - All rights reserved.               |
   | Released under BSD License. See: https://www.mrpt.org/License          |
   +------------------------------------------------------------------------+ */
#ifndef XSSTRING_H
#define XSSTRING_H

#include "xsarray.h"
#include "xstypesconfig.h"
#ifndef XSENS_NO_WCHAR
#include <wchar.h>
#if !defined(XSENS_NO_STL) && defined(__cplusplus) && defined(WIN32)
#include <Windows.h>  // required for MultiByteToWideChar
#endif
#endif  // XSENS_NO_WCHAR
#include <string.h>

#ifdef __cplusplus
#include <stdio.h>
#include <stdlib.h>
#include <string>
extern "C"
{
#endif

    extern XsArrayDescriptor const XSTYPES_DLL_API g_xsStringDescriptor;

#ifndef __cplusplus
#define XsString_INITIALIZER XSARRAY_INITIALIZER(&g_xsStringDescriptor)
    XSARRAY_STRUCT(XsString, char);
    typedef struct XsString XsString;
// obsolete:
#define XSSTRING_INITIALIZER XsString_INITIALIZER
#else
struct XsString;
#endif

    XSTYPES_DLL_API void XsString_construct(XsString* thisPtr);
    XSTYPES_DLL_API void XsString_destruct(XsString* thisPtr);
    XSTYPES_DLL_API void XsString_assign(
        XsString* thisPtr, XsSize count, const char* src);
    XSTYPES_DLL_API void XsString_assignCharArray(
        XsString* thisPtr, const char* src);
#ifndef XSENS_NO_WCHAR
    XSTYPES_DLL_API void XsString_assignWCharArray(
        XsString* thisPtr, const wchar_t* src);
#endif  // XSENS_NO_WCHAR
    XSTYPES_DLL_API XsSize XsString_copyToWCharArray(
        const XsString* thisPtr, wchar_t* dest, XsSize size);
    // XSTYPES_DLL_API void XsString_assignWString(XsString* thisPtr, XsWString
    // const* src);
    XSTYPES_DLL_API void XsString_resize(XsString* thisPtr, XsSize count);
    XSTYPES_DLL_API void XsString_append(
        XsString* thisPtr, XsString const* other);
    XSTYPES_DLL_API void XsString_erase(
        XsString* thisPtr, XsSize index, XsSize count);

#ifndef __cplusplus
// obsolete:
#define XsString_copy(thisPtr, copy) XsArray_copy(copy, thisPtr)
#define XsString_swap(a, b) XsArray_swap(a, b)
#else
}  // extern "C"
#endif

#ifdef __cplusplus
    /* We need some special template implementations for strings to keep them
     * 0-terminated
     */
    // this typedef is not _always_ interpreted correctly by doxygen, hence the
    // occasional function where we're NOT using it.
    // template <typename T, XsArrayDescriptor const& D, typename I>
    // typedef XsArrayImpl<char, g_xsStringDescriptor, XsString> XsStringType;
    // // MRPT: Converted into a struct to fix building with GCC 4.9+
    struct XsStringType
        : public XsArrayImpl<char, g_xsStringDescriptor, XsString>
    {
        inline XsStringType() : XsArrayImpl() {}
        inline explicit XsStringType(char* ref, XsSize sz, XsDataFlags flags)
            : XsArrayImpl(ref, sz, flags)
        {
        }

        /*! \brief Returns the number of items currently in the array, excluding
           the terminating 0 \returns The number of items currently in the array
            \sa reserved \sa setSize \sa resize
        */
        inline XsSize size() const { return m_size ? m_size - 1 : 0; }
        //! \copydoc XsArray_reserve
        inline void reserve(XsSize count) { XsArray_reserve(this, count + 1); }
        //! \brief Returns the reserved space in number of items
        inline XsSize reserved() const
        {
            return m_reserved ? m_reserved - 1 : 0;
        }
        /*! \brief indexed data access operator */
        inline char& operator[](XsSize index)
        {
            assert(index < size());
            return *ptrAt(m_data, index);
        }

        /*! \brief Removes \a count items from the array starting at \a index.
         * \param index The index of the first item to remove. \param count The
         * number of items to remove. */
        inline void erase(XsSize index, XsSize count)
        {
            XsString_erase((XsString*)this, index, count);
        }

        /*! \brief Insert \a count \a items at \a index in the string
            \param items The items to insert, may not be 0 unless count is 0
            \param index The index to use for inserting. Anything beyond the end
           of the string (ie. -1) will append to the actual end of the string.
            \param count The number of items to insert
        */
        inline void insert(char const* items, XsSize index, XsSize count)
        {
            if (size())
            {
                if (index >= size()) index = size();
                XsArray_insert(this, index, count, items);
            }
            else
                XsString_assign((XsString*)this, count, items);
        }

        /*! \brief Assign the characters in \a src to the string
            \details This function is resizes the string to fit \a count
           characters and copies those from \a src. \param count The number of
           characters in src. If this value is 0 and \a scr is not 0, the value
           is determined automatically by looking through src until a
           terminating 0 is found.
            \param src The source string to copy from. If this is 0 and \a count
           is not 0, the string will be filled with spaces instead. \sa
           XsString_assign
        */
        inline void assign(XsSize count, char const* src)
        {
            XsString_assign((XsString*)this, count, src);
        }

        /*! \brief This function resizes the contained string to the desired
           size, while retaining its contents \param count The desired size of
           the string. This excludes the terminating 0 character. \sa
           XsString_resize
        */
        inline void resize(XsSize count)
        {
            XsString_resize((XsString*)this, count);
        }

        /*! \brief Set the size of the array to \a count.
            \details The contents of the array after this operation are
           undefined. \param count The desired new size fo the array. \sa
           XsArray_assign \sa reserve \sa resize
        */
        inline void setSize(XsSize count)
        {
            if (count != size()) XsString_assign((XsString*)this, count, 0);
        }

        /*! \copydoc XsArray_append \sa XsArray_append */
        inline void append(const XsStringType& other)
        {
            XsString_append((XsString*)this, (XsString const*)&other);
        }
    };  // end of struct XsStringType (MRPT)

    struct XsString : public XsStringType
    {
        //! \brief Constructs an XsString
        inline explicit XsString(XsSize sz = 0, char const* src = 0)
            : XsStringType()
        {
            if (sz || src) XsString_assign(this, sz, src);
        }

        //! \brief Constructs an XsString as a copy of \a other
        inline XsString(const XsStringType& other) : XsStringType(other) {}
        //! \brief Constructs an XsInt64Array that references the data supplied
        //! in \a ref
        inline explicit XsString(
            char* ref, XsSize sz, XsDataFlags flags = XSDF_None)
            : XsStringType(ref, sz + 1, flags)
        {
        }
#ifndef XSENS_NOITERATOR
        //! \brief Constructs an XsString with the list bound by the supplied
        //! iterators \a beginIt and \a endIt
        template <typename Iterator>
        inline XsString(Iterator const& beginIt, Iterator const& endIt)
            : XsStringType(beginIt, endIt)
        {
        }
#endif

        //! \brief Construct an XsString from a 0-terminated character array
        inline XsString(char const* src) : XsStringType()
        {
            if (src && src[0]) XsString_assignCharArray(this, src);
        }

#ifndef XSENS_NO_WCHAR
        //! \brief Construct an XsString from a 0-terminated character array
        inline XsString(wchar_t const* src) : XsStringType()
        {
            if (src && src[0]) XsString_assignWCharArray(this, src);
        }
#endif

#ifndef XSENS_NO_STL
        //! \brief Construct an XsString from a std::string
        inline XsString(std::string const& src) : XsStringType()
        {
            if (!src.empty())
                XsString_assign(this, src.size() + 1, src.c_str());
        }

        //! \brief Construct an XsString from a std::wstring
        inline XsString(std::wstring const& src) : XsStringType()
        {
            if (!src.empty()) XsString_assignWCharArray(this, src.c_str());
        }
#endif  // XSENS_NO_STL

        //! \brief Return the internal 0-terminated C-style string
        inline char* c_str()
        {
            static const char nullChar = 0;
            if (empty()) return (char*)&nullChar;
            return begin().operator->();
        }

        //! \brief Return the internal 0-terminated C-style string
        inline char const* c_str() const
        {
            static const char nullChar = 0;
            if (empty()) return &nullChar;
            return begin().operator->();
        }

#ifndef XSENS_NO_STL
        //! \brief Return the string as a std::string
        std::string toStdString() const
        {
            if (empty()) return std::string();
            return std::string((char const*)begin().operator->());
        }
#endif  // XSENS_NO_STL

        //! \brief Return \a other appended to this, without modifying this
        XsString operator+(XsString const& other) const
        {
            XsString tmp;
            tmp.reserve(size() + other.size());
            tmp.append(*this);
            tmp.append(other);
            return tmp;
        }

#ifndef XSENS_NO_STL
        //! \brief Return the string as a std::wstring
        std::wstring toStdWString() const
        {
            if (empty()) return std::wstring();
            size_t s = XsString_copyToWCharArray(this, nullptr, 0);
            std::wstring w;
            w.resize(s - 1);
            s = XsString_copyToWCharArray(this, &w[0], s);
            return w;
        }
#endif  // XSENS_NO_STL

        /*! \cond NODOXYGEN */
        using XsStringType::operator==;
        using XsStringType::operator!=;
#ifndef XSENS_NOITERATOR
        using XsStringType::operator<<;
#endif
        /*! \endcond */

        //! \brief Return true if the contents of \a str are identical to this
        //! string
        bool operator==(char const* str) const
        {
            if (!str) return empty();
            return !strcmp(c_str(), str);
        }

        //! \brief Return true if the contents of \a str differ from this string
        inline bool operator!=(char const* str) const
        {
            return !(*this == str);
        }
        //! \brief Append a character array to the string in a stream-like way
        inline XsString& operator<<(char const* str)
        {
            if (str && str[0])
            {
                XsString const ref(
                    const_cast<char*>(str), strlen(str), XSDF_None);
                append(ref);
            }
            return *this;
        }

        //! \brief Append an integer to the string in a stream-like way
        inline XsString& operator<<(int i)
        {
            char buffer[32];
            append(XsString(buffer, sprintf(buffer, "%d", i), XSDF_None));
            return *this;
        }

        //! \brief Append another string to the string in a stream-like way
        inline XsString& operator<<(XsString const& s)
        {
            append(s);
            return *this;
        }
    };

#ifndef XSENS_NO_STL
    namespace std
    {
    template <typename _CharT, typename _Traits>
    basic_ostream<_CharT, _Traits>& operator<<(
        basic_ostream<_CharT, _Traits>& o, XsString const& xs)
    {
        return (o << xs.toStdString());
    }
    }  // namespace std
#endif

#endif

#endif  // file guard