UT_StringView.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        UT_StringView.h ( UT Library, C++)
 *
 * COMMENTS:
 */

#ifndef __UT_StringView__
#define __UT_StringView__

#include "UT_API.h"
#include "UT_Assert.h"

#include <SYS/SYS_Compiler.h>
#include <SYS/SYS_Inline.h>
#include <SYS/SYS_String.h>

#include <limits.h>
#include <string.h>
#include <memory>
#include <iosfwd>

class UT_StringLit;
class UT_StringRef;
class UT_StringHolder;
class UT_WorkBuffer;
class UT_StringView;
template <typename T> class UT_Array;
typedef UT_Array<UT_StringView> UT_StringViewArray;

/// @brief A utility class to do read-only operations on a subset of an 
/// existing string.
/// @note This object does not take ownership over the data being looked at,
/// so care must be taken that the owning object doesn't not go out of scope
/// before the view object. 
class UT_API UT_StringView
{
public:
    /// Default constructor. Constructs an empty non-string.
    constexpr SYS_FORCE_INLINE
    UT_StringView()
        : myStart(nullptr)
        , myEnd(nullptr)
    { /**/ }

    /// Construct a string view from the entirety of a null-terminated string.
    constexpr SYS_FORCE_INLINE
    UT_StringView(const char *str)
        : myStart(str)
        , myEnd(nullptr)
    {
        if (myStart)
            myEnd = myStart + __builtin_strlen(myStart);
    }

    /// Construct a string view on a string of a given length.
    constexpr SYS_FORCE_INLINE
    explicit UT_StringView(const char *str, exint len)
        : myStart(str)
        , myEnd(nullptr)
    {
        //UT_ASSERT(len >= 0 && "String View length should not be negative");
        if (myStart)
            myEnd = myStart + len;
    }

    /// Construct a string view on a given string range. The @c end pointer
    /// should point to one past the end of the string (i.e. in the case of
    /// null terminated strings, it should point at the null character).
    SYS_FORCE_INLINE
    explicit UT_StringView(const char *start, const char *end)
        : myStart(start), myEnd(end)
    {
        UT_ASSERT((!myStart && !myEnd) || myStart <= myEnd); 
    }

    /// Copy constructor.
    SYS_FORCE_INLINE
    UT_StringView(const UT_StringView &o) = default;

    UT_StringView(const UT_StringLit &s);
    UT_StringView(const UT_StringRef &s);
    UT_StringView(const UT_StringHolder &s);
    UT_StringView(const UT_WorkBuffer &s);

    /// Assignment operator
    SYS_FORCE_INLINE
    UT_StringView & operator=(const UT_StringView &o) = default;
   
    /// The exact meaning depends on context, but generally used either as 
    /// end of view indicator by the functions that expect a view index or
    /// as the error indicator by the functions that return a view index.
    static constexpr exint npos = std::numeric_limits<exint>::max();

    /// @name Query functions
    /// @{
    
    /// Returns the length of the string in bytes.
    SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE 
    exint       length() const { return exint(myEnd - myStart); }
    
    /// Returns @c true if the string is empty.
    SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE 
    bool        isEmpty() const { return myStart == myEnd; }
    
    /// Returns @c true if the view points to a non-empty string
    SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE 
    bool        isstring() const { return !isEmpty(); } 
    
    /// Test whether the string is not an empty string (or nullptr)
    SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE 
    SYS_SAFE_BOOL       operator bool() const   { return !isEmpty(); }

    /// Returns the memory, in bytes, used by this object. 
    SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE 
    int64       getMemoryUsage(bool inclusive) const
                { return inclusive ? sizeof(*this) : 0; }
    
    /// Returns the character at index @c i. No bounds checking is performed.
    SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE 
    char        operator[](exint i) const { return myStart[i]; }
    /// Returns the character at index @c i.
    SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE
    const char& at(exint pos) const
    {
        UT_ASSERT_P(pos < length() && pos >= 0);

        return myStart[pos];
    }

    /// Returns a pointer to the first character of a view.
    SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE
    const char* data() const noexcept { return myStart; }

    /// Returns a constant reference to the first character in the view.
    /// Undefined behaviour if view is empty.
    SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE const char &front() const
    {
        UT_ASSERT_MSG(
                !isEmpty(),
                "Undefined behaviour trying to get front of empty string.");
        return myStart[0];
    }
    /// Returns a constant reference to the last character in the view.
    /// Undefined behaviour if the view is empty.
    SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE const char &back() const
    {
        UT_ASSERT_MSG(
                !isEmpty(),
                "Undefined behaviour trying to get back of empty string.");
        return myStart[length() - 1];
    }

    /// Find first character equal to any of the characters in the given
    /// character sequence.
    SYS_NO_DISCARD_RESULT exint
    findFirstOf(UT_StringView view, exint pos = 0) const noexcept;
    SYS_NO_DISCARD_RESULT exint findFirstOf(char item, exint pos = 0) const
            noexcept
    {
        UT_ASSERT(pos >= 0 && myStart + pos >= myStart);
        for (const char *c = myStart + pos; c < myEnd; ++c)
        {
            if (*c == item)
                return static_cast<exint>(c - myStart);
        }
        return UT_StringView::npos;
    }
    SYS_NO_DISCARD_RESULT exint
    findFirstOf(const char *s, exint pos, exint count) const
    {
        return findFirstOf(UT_StringView(s, count), pos);
    }
    SYS_NO_DISCARD_RESULT exint findFirstOf(const char *s, exint pos) const
    {
        return findFirstOf(UT_StringView(s), pos);
    }

    /// Find the last character equal to any of the characters in the viven
    /// character sequence.
    SYS_NO_DISCARD_RESULT exint
    findLastOf(UT_StringView view, exint pos = npos) const noexcept;
    SYS_NO_DISCARD_RESULT exint findLastOf(char item, exint pos = npos) const
            noexcept
    {
        return findLastOf(UT_StringView(std::addressof(item), 1), pos);
    }
    SYS_NO_DISCARD_RESULT exint
    findLastOf(const char *s, exint pos, exint count) const
    {
        return findLastOf(UT_StringView(s, count), pos);
    }
    SYS_NO_DISCARD_RESULT exint
    findLastOf(const char *s, exint pos = npos) const
    {
        return findLastOf(UT_StringView(s), pos);
    }

    /// Find the first character not equal to any of the characters in the given
    /// character sequence.
    SYS_NO_DISCARD_RESULT exint
    findFirstNotOf(UT_StringView view, exint pos = 0) const noexcept;
    SYS_NO_DISCARD_RESULT exint findFirstNotOf(char item, exint pos = 0) const
            noexcept
    {
        UT_ASSERT(pos >= 0 && myStart + pos >= myStart);
        for (const char *c = myStart + pos; c < myEnd; ++c)
        {
            if (*c != item)
                return static_cast<exint>(c - myStart);
        }

        return UT_StringView::npos;
    }
    SYS_NO_DISCARD_RESULT exint
    findFirstNotOf(const char *s, exint pos, exint count) const
    {
        return findFirstNotOf(UT_StringView(s, count), pos);
    }
    SYS_NO_DISCARD_RESULT exint findFirstNotOf(const char *s, exint pos) const
    {
        return findFirstNotOf(UT_StringView(s), pos);
    }

    /// Find the last character not equal to any of the characters in the given
    /// character sequence.
    SYS_NO_DISCARD_RESULT exint
    findLastNotOf(UT_StringView view, exint pos = npos) const noexcept;
    SYS_NO_DISCARD_RESULT exint findLastNotOf(char item, exint pos = npos) const
            noexcept
    {
        return findLastNotOf(UT_StringView(std::addressof(item), 1), pos);
    }
    SYS_NO_DISCARD_RESULT exint
    findLastNotOf(const char *s, exint pos, exint count) const
    {
        return findLastNotOf(UT_StringView(s, count), pos);
    }
    SYS_NO_DISCARD_RESULT exint findLastNotOf(const char *s, exint pos) const
    {
        return findLastNotOf(UT_StringView(s), pos);
    }
    /// @}
    
    /// @name Iterators
    /// @{
    
    /// The iterator type. @ref UT_StringView only provides read-only iterators.
    typedef const char *        const_iterator;
    
    /// Returns a constant iterator pointing to the beginning of the string.
    SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE 
    const_iterator begin() const { return myStart; }
    
    /// Returns a constant iterator pointing to the end of the string.
    SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE 
    const_iterator end() const { return myEnd; }
    /// @}
    
    /// @name Manipulators
    /// @{
    
    /// Clears the string. After this operation @ref isstring will return false,
    /// and @ref isEmpty will return true.
    void        clear() { myStart = myEnd = nullptr; }
    
    /// Trim characters from the left- and right-hand side of the string.
    /// By default this will trim the ASCII space characters.
    SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE 
    UT_StringView       trim(const char *c =" \t\n\r") const
                            { return trimInternal(c, true, true); }
    
    /// Trim characters from the left-hand side of the string.
    /// By default this will trim the ASCII space characters.
    SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE 
    UT_StringView       trimLeft(const char *c =" \t\n\r") const
                            { return trimInternal(c, true, false); }
    
    /// Trim characters from the right-hand side of the string.
    /// By default this will trim the ASCII space characters.
    SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE 
    UT_StringView       trimRight(const char *c =" \t\n\r") const
                            { return trimInternal(c, false, true); }

    /// Return the first token
    SYS_NO_DISCARD_RESULT
    UT_StringView       firstToken(const char *sep_chars = " \t\n\r") const;
    
    /// Splits the string into individual tokens, separated by one or more of 
    /// the @c sep characters given. If @c group_separators is false, the
    /// delimiters are not grouped together, e.g., ",," => ('', '', ''), which
    /// is equivalent of Python's split().
    SYS_NO_DISCARD_RESULT
    UT_StringViewArray tokenize(const char *sep_chars =" \t\n\r",
                                bool group_separators = true) const;
    
    /// Splits the string into a list of words, using sep_str as the separator
    /// string. Unlike tokenize, consecutive delimiters are not grouped 
    /// together and are instead taken to delimit empty strings.
    /// If @c max_split is set, the string is split into at most @c max_sep
    /// pieces.
    SYS_NO_DISCARD_RESULT
    UT_StringViewArray split(const char *sep_str = " ", 
                             int max_split = INT_MAX) const;
    
    /// Returns a sub-string of the current string. If positive, the 
    /// @c index parameter is relative to the start. If negative, it's
    /// relative to the end (e.g. substr(-1,1) will return the last character
    /// of the string).
    /// The empty string will be returned for out-of-range values.
    SYS_NO_DISCARD_RESULT
    UT_StringView substr(exint index, exint length=SYS_EXINT_MAX ) const;
   
    /// Move the start of the view forward by n characters.
    /// If N is grreater then length() then it moves to the end.
    void removePrefix(exint n);
    /// Move the end of the view backwards by n characters.
    /// If n is greater then the length() then it moves to the start.
    void removeSuffix(exint n);
    /// @}

    /// @name Operators
    /// @{
    
    /// The @ref compare function compares this string with another, and returns
    /// and integer less than, equal to, or greater than zero if this string
    /// is found to be less than, equal to, or greater than the given string,
    /// respectively. If a length is given, then the strings are compared as
    /// if they were both of that length, or smaller.
    SYS_NO_DISCARD_RESULT
    int         compare(const char *str, exint str_len, 
                        bool case_sensitive=true) const;
    SYS_NO_DISCARD_RESULT
    int         compare(const UT_StringView &sv,
                        bool case_sensitive=true) const;
    
    /// Returns true if the two strings compare as being equal. 
    /// If @c case_sensitive is set to @c false then the strings are compared 
    /// in a case-insensitive fashion.
    SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE 
    bool        equal(const char *str, bool case_sensitive=true) const
                { return compare(UT_StringView(str), 
                                 case_sensitive) == 0; }
    SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE 
    bool        equal(const UT_StringView &other, 
                      bool case_sensitive=true) const
                { return compare(other, case_sensitive) == 0; }
    
    /// Returns true if the two strings compare as being equal. 
    SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE 
    bool        operator==(const char *str) const
                { return compare(UT_StringView(str)) == 0; }
    SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE 
    bool        operator==(const UT_StringView &other) const
                { return compare(other) == 0; }
    
    /// Returns true if the two strings compare as being not equal. 
    SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE 
    bool        operator!=(const char *str) const
                { return compare(UT_StringView(str)) != 0; }
    SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE 
    bool        operator!=(const UT_StringView &other) const
                { return compare(other) != 0; }
    
    /// Returns true if this string is lexicographically less than the given
    /// string.
    SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE 
    bool        operator<(const char *str) const
                { return compare(UT_StringView(str)) < 0; }
    SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE 
    bool        operator<(const UT_StringView &other) const
                { return compare(other) < 0; }

    /// Find the first instance of the given character in this string.
    const_iterator find(char c, const_iterator start) const;
    SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE 
    const_iterator find(char c) const
                   { return find(c, begin()); }
    
    /// Find the first instance of the given substring in this string.
    const_iterator find(const char *str, const_iterator start) const;
    SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE 
    const_iterator find(const char *str) const
                   { return find(str, begin()); }

    /// Find last instance of the given character in this string, searching
    /// backwards from 'pos'.
    SYS_NO_DISCARD_RESULT
    const_iterator rfind(char c, const_iterator pos) const;
    SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE 
    const_iterator rfind(char c) const
                   { return rfind(c, end() - 1); }
    /// Returns true if our string starts with the specified prefix.
    SYS_NO_DISCARD_RESULT
    bool startsWith(const char* prefix,
                    bool case_sensitive = true,
                    exint len = -1) const;
    SYS_NO_DISCARD_RESULT
    bool endsWith(const char* prefix,
                    bool case_sensitive = true,
                    exint len = -1) const;
    /// @}

    /// Determine if string can be seen as a single floating point number
    SYS_NO_DISCARD_RESULT
    bool isFloat(bool skip_spaces = false,
                         bool loose = false,
                         bool allow_underscore = false) const;
    /// Determine if string can be seen as a single integer number
    SYS_NO_DISCARD_RESULT
    bool isInteger(bool skip_spaces = false) const;

    SYS_NO_DISCARD_RESULT
    unsigned hash() const
    {
        return SYSstring_hash(myStart, length(), /*allow_nulls*/true);
    }
private:
    SYS_NO_DISCARD_RESULT
    UT_StringView trimInternal(const char *c, bool left, bool right) const;
     
    const char  *myStart, *myEnd;
};

// In very specific cases it can be helpful to store string views in a standard
// container such as map. When doing so EXTREME CAUTION must be taken!!!
namespace std
{
    template <>
    struct hash<UT_StringView>
    {
        size_t operator()(const UT_StringView& s) const
        {
            return s.hash();
        }
    };
}
// Implicitly adding support for hboost::hash hash doesn't work right now
// because it leads to ambiguity with the one for UT_String, I think because
// both of them can be created implicitly from const char pointers.
#if 0
// Hash for hboost. Same warning as above to use EXTREME CAUTION!!!
SYS_FORCE_INLINE size_t
hash_value(const UT_StringView &str)
{
    return str.hash();
}
#endif

UT_API std::ostream &
operator<<(std::ostream &os, const UT_StringView &sv);


#endif // __UT_StringView__