HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
UT_StringView.h
Go to the documentation of this file.
1 /*
2  * PROPRIETARY INFORMATION. This software is proprietary to
3  * Side Effects Software Inc., and is not to be reproduced,
4  * transmitted, or disclosed in any way without written permission.
5  *
6  * NAME: UT_StringView.h ( UT Library, C++)
7  *
8  * COMMENTS:
9  */
10 
11 #ifndef __UT_StringView__
12 #define __UT_StringView__
13 
14 #include "UT_API.h"
15 
16 #include "UT_Array.h"
17 
18 #include <SYS/SYS_Inline.h>
19 #include <SYS/SYS_String.h>
20 #include <string.h>
21 #include <iosfwd>
22 
25 
26 /// @brief A utility class to do read-only operations on a subset of an
27 /// existing string.
28 /// @note This object does not take ownership over the data being looked at,
29 /// so care must be taken that the owning object doesn't not go out of scope
30 /// before the view object.
32 {
33 public:
34  /// Default constructor. Constructs an empty non-string.
37  : myStart(nullptr), myEnd(nullptr)
38  { /**/ }
39 
40  /// Construct a string view from the entirety of a null-terminated string.
42  UT_StringView(const char *str)
43  : myStart(str), myEnd(nullptr)
44  {
45  if (myStart)
46  myEnd = myStart + ::strlen(str);
47  }
48 
49  /// Construct a string view on a string of a given length.
51  explicit UT_StringView(const char *str, exint len)
52  : myStart(str), myEnd(nullptr)
53  {
54  UT_ASSERT(len >= 0 && "String View length should not be negative");
55  if (myStart)
56  myEnd = myStart + len;
57  }
58 
59  /// Construct a string view on a given string range. The @c end pointer
60  /// should point to one past the end of the string (i.e. in the case of
61  /// null terminated strings, it should point at the null character).
63  explicit UT_StringView(const char *start, const char *end)
64  : myStart(start), myEnd(end)
65  {
66  UT_ASSERT((!myStart && !myEnd) || myStart <= myEnd);
67  }
68 
69  /// Copy constructor.
71  UT_StringView(const UT_StringView &o) = default;
72 
73  /// @name Query functions
74  /// @{
75 
76  /// Returns the length of the string in bytes.
78  exint length() const { return exint(myEnd - myStart); }
79 
80  /// Returns @c true if the string is empty.
82  bool isEmpty() const { return myStart == myEnd; }
83 
84  /// Returns @c true if the view points to a valid string, even an empty one
86  bool isstring() const { return myStart; }
87 
88  /// Test whether the string is not an empty string (or nullptr)
90  SYS_SAFE_BOOL operator bool() const { return !isEmpty(); }
91 
92  /// Returns the memory, in bytes, used by this object.
93  int64 getMemoryUsage(bool inclusive) const
94  { return inclusive ? sizeof(*this) : 0; }
95 
96  /// Returns the character at index @c i. No bounds checking is performed.
98  char operator[](exint i) const { return myStart[i]; }
99 
100  /// @}
101 
102  /// @name Iterators
103  /// @{
104 
105  /// The iterator type. @ref UT_StringView only provides read-only iterators.
106  typedef const char * const_iterator;
107 
108  /// Returns a constant iterator pointing to the beginning of the string.
110  const_iterator begin() const { return myStart; }
111 
112  /// Returns a constant iterator pointing to the end of the string.
114  const_iterator end() const { return myEnd; }
115  /// @}
116 
117  /// @name Manipulators
118  /// @{
119 
120  /// Clears the string. After this operation @ref isstring will return false,
121  /// and @ref isEmpty will return true.
122  void clear() { myStart = myEnd = 0; }
123 
124  /// Trim characters from the left- and right-hand side of the string.
125  /// By default this will trim the ASCII space characters.
127  UT_StringView trim(const char *c =" \t\n\r") const
128  { return trimInternal(c, true, true); }
129 
130  /// Trim characters from the left-hand side of the string.
131  /// By default this will trim the ASCII space characters.
133  UT_StringView trimLeft(const char *c =" \t\n\r") const
134  { return trimInternal(c, true, false); }
135 
136  /// Trim characters from the right-hand side of the string.
137  /// By default this will trim the ASCII space characters.
139  UT_StringView trimRight(const char *c =" \t\n\r") const
140  { return trimInternal(c, false, true); }
141 
142  /// Return the first token
143  UT_StringView firstToken(const char *sep_chars = " \t\n\r") const;
144 
145  /// Splits the string into individual tokens, separated by one or more of
146  /// the @c sep characters given.
147  UT_StringViewArray tokenize(const char *sep_chars =" \t\n\r") const;
148 
149  /// Splits the string into a list of words, using sep_str as the separator
150  /// string. Unlike tokenize, consecutive delimiters are not grouped
151  /// together and are instead taken to delimit empty strings.
152  /// If @c max_split is set, the string is split into at most @c max_sep
153  /// pieces.
154  UT_StringViewArray split(const char *sep_str = " ",
155  int max_split = INT_MAX) const;
156 
157  /// Returns a sub-string of the current string. If positive, the
158  /// @c index parameter is relative to the start. If negative, it's
159  /// relative to the end (e.g. substr(-1,1) will return the last character
160  /// of the string).
161  /// The empty string will be returned for out-of-range values.
163 
164  /// @}
165 
166  /// @name Operators
167  /// @{
168 
169  /// The @ref compare function compares this string with another, and returns
170  /// and integer less than, equal to, or greater than zero if this string
171  /// is found to be less than, equal to, or greater than the given string,
172  /// respectively. If a length is given, then the strings are compared as
173  /// if they were both of that length, or smaller.
174  int compare(const char *str, exint str_len,
175  bool case_sensitive=true) const;
176  int compare(const UT_StringView &sv,
177  bool case_sensitive=true) const;
178 
179  /// Returns true if the two strings compare as being equal.
180  /// If @c case_sensitive is set to @c false then the strings are compared
181  /// in a case-insensitive fashion.
183  bool equal(const char *str, bool case_sensitive=true) const
184  { return compare(UT_StringView(str),
185  case_sensitive) == 0; }
187  bool equal(const UT_StringView &other,
188  bool case_sensitive=true) const
189  { return compare(other, case_sensitive) == 0; }
190 
191  /// Returns true if the two strings compare as being equal.
193  bool operator==(const char *str) const
194  { return compare(UT_StringView(str)) == 0; }
196  bool operator==(const UT_StringView &other) const
197  { return compare(other) == 0; }
198 
199  /// Returns true if the two strings compare as being not equal.
201  bool operator!=(const char *str) const
202  { return compare(UT_StringView(str)) != 0; }
204  bool operator!=(const UT_StringView &other) const
205  { return compare(other) != 0; }
206 
207  /// Returns true if this string is lexicographically less than the given
208  /// string.
210  bool operator<(const char *str) const
211  { return compare(UT_StringView(str)) < 0; }
213  bool operator<(const UT_StringView &other) const
214  { return compare(other) < 0; }
215 
216  /// Find the first instance of the given character in this string.
217  const_iterator find(char c, const_iterator start) const;
219  const_iterator find(char c) const
220  { return find(c, begin()); }
221 
222  /// Find the first instance of the given substring in this string.
223  const_iterator find(const char *str, const_iterator start) const;
225  const_iterator find(const char *str) const
226  { return find(str, begin()); }
227 
228  /// Find last instance of the given character in this string, searching
229  /// backwards from 'pos'.
230  const_iterator rfind(char c, const_iterator pos) const;
232  const_iterator rfind(char c) const
233  { return rfind(c, end() - 1); }
234 
235  /// @}
236 private:
237  UT_StringView trimInternal(const char *c, bool left, bool right) const;
238 
239  const char *myStart, *myEnd;
240 };
241 
242 UT_API std::ostream &
243 operator<<(std::ostream &os, const UT_StringView &sv);
244 
245 
246 #endif // __UT_StringView__
UT_API std::ostream & operator<<(std::ostream &os, const UT_StringView &sv)
SYS_FORCE_INLINE bool isEmpty() const
Returns true if the string is empty.
Definition: UT_StringView.h:82
SYS_FORCE_INLINE exint length() const
Returns the length of the string in bytes.
Definition: UT_StringView.h:78
GLint left
Definition: glcorearb.h:2004
GLuint start
Definition: glcorearb.h:474
#define UT_API
Definition: UT_API.h:13
#define SYS_EXINT_MAX
Definition: SYS_Types.h:172
SYS_FORCE_INLINE const_iterator begin() const
Returns a constant iterator pointing to the beginning of the string.
png_uint_32 i
Definition: png.h:2877
SYS_FORCE_INLINE const_iterator rfind(char c) const
const char * const_iterator
The iterator type. UT_StringView only provides read-only iterators.
long long int64
Definition: SYS_Types.h:107
A utility class to do read-only operations on a subset of an existing string.
Definition: UT_StringView.h:31
SYS_FORCE_INLINE UT_StringView trimRight(const char *c=" \t\n\r") const
SYS_FORCE_INLINE UT_StringView()
Default constructor. Constructs an empty non-string.
Definition: UT_StringView.h:36
SYS_FORCE_INLINE bool equal(const UT_StringView &other, bool case_sensitive=true) const
#define SYS_SAFE_BOOL
Definition: SYS_Compiler.h:62
SYS_FORCE_INLINE bool operator!=(const char *str) const
Returns true if the two strings compare as being not equal.
int64 exint
Definition: SYS_Types.h:116
SYS_FORCE_INLINE UT_StringView(const char *str)
Construct a string view from the entirety of a null-terminated string.
Definition: UT_StringView.h:42
GLuint GLuint end
Definition: glcorearb.h:474
#define SYS_FORCE_INLINE
Definition: SYS_Inline.h:45
SYS_FORCE_INLINE bool operator<(const char *str) const
SYS_FORCE_INLINE bool isstring() const
Returns true if the view points to a valid string, even an empty one.
Definition: UT_StringView.h:86
SYS_FORCE_INLINE bool operator==(const UT_StringView &other) const
SYS_FORCE_INLINE bool operator<(const UT_StringView &other) const
SYS_FORCE_INLINE const_iterator find(const char *str) const
SYS_FORCE_INLINE UT_StringView trimLeft(const char *c=" \t\n\r") const
GLuint index
Definition: glcorearb.h:785
SYS_FORCE_INLINE UT_StringView(const char *str, exint len)
Construct a string view on a string of a given length.
Definition: UT_StringView.h:51
SYS_FORCE_INLINE bool equal(const char *str, bool case_sensitive=true) const
SYS_FORCE_INLINE UT_StringView(const char *start, const char *end)
Definition: UT_StringView.h:63
#define UT_ASSERT(ZZ)
Definition: UT_Assert.h:126
SYS_FORCE_INLINE UT_StringView trim(const char *c=" \t\n\r") const
SYS_FORCE_INLINE const_iterator find(char c) const
UT_Array< UT_StringView > UT_StringViewArray
Definition: UT_StringView.h:23
SYS_FORCE_INLINE const_iterator end() const
Returns a constant iterator pointing to the end of the string.
SYS_FORCE_INLINE bool operator!=(const UT_StringView &other) const
int64 getMemoryUsage(bool inclusive) const
Returns the memory, in bytes, used by this object.
Definition: UT_StringView.h:93
SYS_FORCE_INLINE char operator[](exint i) const
Returns the character at index i. No bounds checking is performed.
Definition: UT_StringView.h:98
SYS_FORCE_INLINE bool operator==(const char *str) const
Returns true if the two strings compare as being equal.
GLuint GLsizei GLsizei * length
Definition: glcorearb.h:794