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_Assert.h"
17 #include "UT_Array.h"
18 
19 #include <SYS/SYS_Compiler.h>
20 #include <SYS/SYS_Inline.h>
21 #include <SYS/SYS_String.h>
22 
23 #include <string.h>
24 #include <memory>
25 #include <limits>
26 #include <iosfwd>
27 
28 class UT_StringLit;
29 class UT_StringRef;
30 class UT_StringHolder;
31 class UT_WorkBuffer;
34 
35 /// @brief A utility class to do read-only operations on a subset of an
36 /// existing string.
37 /// @note This object does not take ownership over the data being looked at,
38 /// so care must be taken that the owning object doesn't not go out of scope
39 /// before the view object.
41 {
42 public:
43  /// Default constructor. Constructs an empty non-string.
44  constexpr SYS_FORCE_INLINE
46  : myStart(nullptr)
47  , myEnd(nullptr)
48  { /**/ }
49 
50  /// Construct a string view from the entirety of a null-terminated string.
51  constexpr SYS_FORCE_INLINE
52  UT_StringView(const char *str)
53  : myStart(str)
54  , myEnd(nullptr)
55  {
56  if (myStart)
57  myEnd = myStart + ::strlen(str);
58  }
59 
60  /// Construct a string view on a string of a given length.
61  constexpr SYS_FORCE_INLINE
62  explicit UT_StringView(const char *str, exint len)
63  : myStart(str)
64  , myEnd(nullptr)
65  {
66  //UT_ASSERT(len >= 0 && "String View length should not be negative");
67  if (myStart)
68  myEnd = myStart + len;
69  }
70 
71  /// Construct a string view on a given string range. The @c end pointer
72  /// should point to one past the end of the string (i.e. in the case of
73  /// null terminated strings, it should point at the null character).
75  explicit UT_StringView(const char *start, const char *end)
76  : myStart(start), myEnd(end)
77  {
78  UT_ASSERT((!myStart && !myEnd) || myStart <= myEnd);
79  }
80 
81  /// Copy constructor.
83  UT_StringView(const UT_StringView &o) = default;
84 
89 
90  /// Assignment operator
92  UT_StringView & operator=(const UT_StringView &o) = default;
93 
94  /// The exact meaning depends on context, but generally used either as
95  /// end of view indicator by the functions that expect a view index or
96  /// as the error indicator by the functions that return a view index.
97  static constexpr exint npos = std::numeric_limits<exint>::max();
98 
99  /// @name Query functions
100  /// @{
101 
102  /// Returns the length of the string in bytes.
104  exint length() const { return exint(myEnd - myStart); }
105 
106  /// Returns @c true if the string is empty.
108  bool isEmpty() const { return myStart == myEnd; }
109 
110  /// Returns @c true if the view points to a valid string, even an empty one
112  bool isstring() const { return myStart; }
113 
114  /// Test whether the string is not an empty string (or nullptr)
116  SYS_SAFE_BOOL operator bool() const { return !isEmpty(); }
117 
118  /// Returns the memory, in bytes, used by this object.
120  int64 getMemoryUsage(bool inclusive) const
121  { return inclusive ? sizeof(*this) : 0; }
122 
123  /// Returns the character at index @c i. No bounds checking is performed.
125  char operator[](exint i) const { return myStart[i]; }
126  /// Returns the character at index @c i.
128  const char& at(exint pos) const
129  {
130  UT_ASSERT_P(pos < length() && pos < 0);
131 
132  return myStart[pos];
133  }
134 
135  /// Returns a pointer to the first character of a view.
137  const char* data() const noexcept { return myStart; }
138 
139  /// Returns a constant reference to the first character in the view.
140  /// Undefined behaviour if view is empty.
142  {
144  !isEmpty(),
145  "Undefined behaviour trying to get front of empty string.");
146  return myStart[0];
147  }
148  /// Returns a constant reference to the last character in the view.
149  /// Undefined behaviour if the view is empty.
151  {
153  !isEmpty(),
154  "Undefined behaviour trying to get back of empty string.");
155  return myStart[length() - 1];
156  }
157 
158  /// Find first character equal to any of the characters in the given
159  /// character sequence.
161  findFirstOf(UT_StringView view, exint pos = 0) const noexcept;
162  SYS_NO_DISCARD_RESULT exint findFirstOf(char item, exint pos = 0) const
163  noexcept
164  {
165  return findFirstOf(UT_StringView(std::addressof(item), 1), pos);
166  }
168  findFirstOf(const char *s, exint pos, exint count) const
169  {
170  return findFirstOf(UT_StringView(s, count), pos);
171  }
173  {
174  return findFirstOf(UT_StringView(s), pos);
175  }
176 
177  /// Find the last character equal to any of the characters in the viven
178  /// character sequence.
180  findLastOf(UT_StringView view, exint pos = npos) const noexcept;
181  SYS_NO_DISCARD_RESULT exint findLastOf(char item, exint pos = npos) const
182  noexcept
183  {
184  return findLastOf(UT_StringView(std::addressof(item), 1), pos);
185  }
187  findLastOf(const char *s, exint pos, exint count) const
188  {
189  return findLastOf(UT_StringView(s, count), pos);
190  }
192  findLastOf(const char *s, exint pos = npos) const
193  {
194  return findLastOf(UT_StringView(s), pos);
195  }
196 
197  /// Find the first character not equal to any of the characters in the given
198  /// character sequence.
200  findFirstNotOf(UT_StringView view, exint pos = 0) const noexcept;
201  SYS_NO_DISCARD_RESULT exint findFirstNotOf(char item, exint pos = 0) const
202  noexcept
203  {
204  return findFirstNotOf(UT_StringView(std::addressof(item), 1), pos);
205  }
207  findFirstNotOf(const char *s, exint pos, exint count) const
208  {
209  return findFirstNotOf(UT_StringView(s, count), pos);
210  }
212  {
213  return findFirstNotOf(UT_StringView(s), pos);
214  }
215 
216  /// Find the last character not equal to any of the characters in the given
217  /// character sequence.
219  findLastNotOf(UT_StringView view, exint pos = npos) const noexcept;
220  SYS_NO_DISCARD_RESULT exint findLastNotOf(char item, exint pos = npos) const
221  noexcept
222  {
223  return findLastNotOf(UT_StringView(std::addressof(item), 1), pos);
224  }
226  findLastNotOf(const char *s, exint pos, exint count) const
227  {
228  return findLastNotOf(UT_StringView(s, count), pos);
229  }
231  {
232  return findLastNotOf(UT_StringView(s), pos);
233  }
234 
235  /// @}
236 
237  /// @name Iterators
238  /// @{
239 
240  /// The iterator type. @ref UT_StringView only provides read-only iterators.
241  typedef const char * const_iterator;
242 
243  /// Returns a constant iterator pointing to the beginning of the string.
245  const_iterator begin() const { return myStart; }
246 
247  /// Returns a constant iterator pointing to the end of the string.
249  const_iterator end() const { return myEnd; }
250  /// @}
251 
252  /// @name Manipulators
253  /// @{
254 
255  /// Clears the string. After this operation @ref isstring will return false,
256  /// and @ref isEmpty will return true.
257  void clear() { myStart = myEnd = 0; }
258 
259  /// Trim characters from the left- and right-hand side of the string.
260  /// By default this will trim the ASCII space characters.
262  UT_StringView trim(const char *c =" \t\n\r") const
263  { return trimInternal(c, true, true); }
264 
265  /// Trim characters from the left-hand side of the string.
266  /// By default this will trim the ASCII space characters.
268  UT_StringView trimLeft(const char *c =" \t\n\r") const
269  { return trimInternal(c, true, false); }
270 
271  /// Trim characters from the right-hand side of the string.
272  /// By default this will trim the ASCII space characters.
274  UT_StringView trimRight(const char *c =" \t\n\r") const
275  { return trimInternal(c, false, true); }
276 
277  /// Return the first token
279  UT_StringView firstToken(const char *sep_chars = " \t\n\r") const;
280 
281  /// Splits the string into individual tokens, separated by one or more of
282  /// the @c sep characters given.
284  UT_StringViewArray tokenize(const char *sep_chars =" \t\n\r") const;
285 
286  /// Splits the string into a list of words, using sep_str as the separator
287  /// string. Unlike tokenize, consecutive delimiters are not grouped
288  /// together and are instead taken to delimit empty strings.
289  /// If @c max_split is set, the string is split into at most @c max_sep
290  /// pieces.
292  UT_StringViewArray split(const char *sep_str = " ",
293  int max_split = INT_MAX) const;
294 
295  /// Returns a sub-string of the current string. If positive, the
296  /// @c index parameter is relative to the start. If negative, it's
297  /// relative to the end (e.g. substr(-1,1) will return the last character
298  /// of the string).
299  /// The empty string will be returned for out-of-range values.
302 
303  /// Move the start of the view forward by n characters.
304  /// If N is grreater then length() then it moves to the end.
305  void removePrefix(exint n);
306  /// Move the end of the view backwards by n characters.
307  /// If n is greater then the length() then it moves to the start.
308  void removeSuffix(exint n);
309  /// @}
310 
311  /// @name Operators
312  /// @{
313 
314  /// The @ref compare function compares this string with another, and returns
315  /// and integer less than, equal to, or greater than zero if this string
316  /// is found to be less than, equal to, or greater than the given string,
317  /// respectively. If a length is given, then the strings are compared as
318  /// if they were both of that length, or smaller.
320  int compare(const char *str, exint str_len,
321  bool case_sensitive=true) const;
323  int compare(const UT_StringView &sv,
324  bool case_sensitive=true) const;
325 
326  /// Returns true if the two strings compare as being equal.
327  /// If @c case_sensitive is set to @c false then the strings are compared
328  /// in a case-insensitive fashion.
330  bool equal(const char *str, bool case_sensitive=true) const
331  { return compare(UT_StringView(str),
332  case_sensitive) == 0; }
334  bool equal(const UT_StringView &other,
335  bool case_sensitive=true) const
336  { return compare(other, case_sensitive) == 0; }
337 
338  /// Returns true if the two strings compare as being equal.
340  bool operator==(const char *str) const
341  { return compare(UT_StringView(str)) == 0; }
343  bool operator==(const UT_StringView &other) const
344  { return compare(other) == 0; }
345 
346  /// Returns true if the two strings compare as being not equal.
348  bool operator!=(const char *str) const
349  { return compare(UT_StringView(str)) != 0; }
351  bool operator!=(const UT_StringView &other) const
352  { return compare(other) != 0; }
353 
354  /// Returns true if this string is lexicographically less than the given
355  /// string.
357  bool operator<(const char *str) const
358  { return compare(UT_StringView(str)) < 0; }
360  bool operator<(const UT_StringView &other) const
361  { return compare(other) < 0; }
362 
363  /// Find the first instance of the given character in this string.
364  const_iterator find(char c, const_iterator start) const;
366  const_iterator find(char c) const
367  { return find(c, begin()); }
368 
369  /// Find the first instance of the given substring in this string.
370  const_iterator find(const char *str, const_iterator start) const;
372  const_iterator find(const char *str) const
373  { return find(str, begin()); }
374 
375  /// Find last instance of the given character in this string, searching
376  /// backwards from 'pos'.
378  const_iterator rfind(char c, const_iterator pos) const;
380  const_iterator rfind(char c) const
381  { return rfind(c, end() - 1); }
382  /// Returns true if our string starts with the specified prefix.
384  bool startsWith(const char* prefix,
385  bool case_sensitive = true,
386  exint len = -1) const;
387  /// @}
388 private:
390  UT_StringView trimInternal(const char *c, bool left, bool right) const;
391 
392  const char *myStart, *myEnd;
393 };
394 
395 UT_API std::ostream &
396 operator<<(std::ostream &os, const UT_StringView &sv);
397 
398 
399 #endif // __UT_StringView__
GLdouble s
Definition: glew.h:1390
UT_API std::ostream & operator<<(std::ostream &os, const UT_StringView &sv)
vint4 max(const vint4 &a, const vint4 &b)
Definition: simd.h:4703
SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE const_iterator find(const char *str) const
SYS_NO_DISCARD_RESULT exint findFirstNotOf(const char *s, exint pos) const
Returns the length of the string in bytes.
SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE const char & back() const
constexpr SYS_FORCE_INLINE UT_StringView(const char *str)
Construct a string view from the entirety of a null-terminated string.
Definition: UT_StringView.h:52
SYS_NO_DISCARD_RESULT exint findLastNotOf(const char *s, exint pos) const
Returns the length of the string in bytes.
FMT_CONSTEXPR auto begin(const C &c) -> decltype(c.begin())
Definition: format.h:251
GLuint index
Definition: glew.h:1814
GLint left
Definition: glew.h:8008
SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE const_iterator find(char c) const
SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE bool operator<(const UT_StringView &other) const
SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE bool operator<(const char *str) const
SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE UT_StringView trimLeft(const char *c=" \t\n\r") const
constexpr SYS_FORCE_INLINE UT_StringView()
Default constructor. Constructs an empty non-string.
Definition: UT_StringView.h:45
int64 exint
Definition: SYS_Types.h:125
SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE const_iterator end() const
Returns a constant iterator pointing to the end of the string.
#define UT_API
Definition: UT_API.h:13
#define SYS_EXINT_MAX
Definition: SYS_Types.h:181
SYS_NO_DISCARD_RESULT exint findLastOf(const char *s, exint pos, exint count) const
Returns the length of the string in bytes.
SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE bool operator==(const char *str) const
Returns true if the two strings compare as being equal.
const char * const_iterator
The iterator type. UT_StringView only provides read-only iterators.
#define UT_ASSERT_MSG(ZZ,...)
Definition: UT_Assert.h:138
SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE const char * data() const noexcept
Returns a pointer to the first character of a view.
SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE int64 getMemoryUsage(bool inclusive) const
Returns the memory, in bytes, used by this object.
CompareResults OIIO_API compare(const ImageBuf &A, const ImageBuf &B, float failthresh, float warnthresh, ROI roi={}, int nthreads=0)
A utility class to do read-only operations on a subset of an existing string.
Definition: UT_StringView.h:40
SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE bool isEmpty() const
Returns true if the string is empty.
void OIIO_API split(string_view str, std::vector< string_view > &result, string_view sep=string_view(), int maxsplit=-1)
SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE exint length() const
Returns the length of the string in bytes.
SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE bool equal(const UT_StringView &other, bool case_sensitive=true) const
SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE const_iterator rfind(char c) const
#define SYS_SAFE_BOOL
Definition: SYS_Compiler.h:55
SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE const char & at(exint pos) const
Returns the character at index i.
SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE const char & front() const
#define UT_ASSERT_P(ZZ)
Definition: UT_Assert.h:134
#define SYS_FORCE_INLINE
Definition: SYS_Inline.h:45
GLuint GLuint end
Definition: glew.h:1253
GLsizei n
Definition: glew.h:4040
const GLfloat * c
Definition: glew.h:16296
GLuint GLsizei GLsizei * length
Definition: glew.h:1825
long long int64
Definition: SYS_Types.h:116
#define SYS_NO_DISCARD_RESULT
Definition: SYS_Compiler.h:93
GLfloat right
Definition: glew.h:15186
SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE bool operator==(const UT_StringView &other) const
GLuint start
Definition: glew.h:1253
constexpr 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:62
SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE char operator[](exint i) const
Returns the character at index i. No bounds checking is performed.
SYS_NO_DISCARD_RESULT exint findFirstNotOf(const char *s, exint pos, exint count) const
Returns the length of the string in bytes.
SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE bool equal(const char *str, bool case_sensitive=true) const
SYS_NO_DISCARD_RESULT exint findFirstOf(const char *s, exint pos, exint count) const
Returns the length of the string in bytes.
SYS_NO_DISCARD_RESULT exint findLastOf(const char *s, exint pos=npos) const
Returns the length of the string in bytes.
FMT_CONSTEXPR bool find(Ptr first, Ptr last, T value, Ptr &out)
Definition: format.h:2104
GLuint GLuint GLsizei count
Definition: glew.h:1253
SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE const_iterator begin() const
Returns a constant iterator pointing to the beginning of the string.
SYS_FORCE_INLINE UT_StringView(const char *start, const char *end)
Definition: UT_StringView.h:75
SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE bool isstring() const
Returns true if the view points to a valid string, even an empty one.
SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE UT_StringView trimRight(const char *c=" \t\n\r") const
#define UT_ASSERT(ZZ)
Definition: UT_Assert.h:135
UT_Array< UT_StringView > UT_StringViewArray
Definition: UT_StringView.h:32
#define const
Definition: zconf.h:214
SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE bool operator!=(const UT_StringView &other) const
SYS_NO_DISCARD_RESULT exint findLastNotOf(const char *s, exint pos, exint count) const
Returns the length of the string in bytes.
SYS_NO_DISCARD_RESULT exint findFirstOf(const char *s, exint pos) const
Returns the length of the string in bytes.
SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE UT_StringView trim(const char *c=" \t\n\r") const
SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE bool operator!=(const char *str) const
Returns true if the two strings compare as being not equal.
GLenum GLsizei len
Definition: glew.h:7752