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  /// @name Iterators
237  /// @{
238 
239  /// The iterator type. @ref UT_StringView only provides read-only iterators.
240  typedef const char * const_iterator;
241 
242  /// Returns a constant iterator pointing to the beginning of the string.
244  const_iterator begin() const { return myStart; }
245 
246  /// Returns a constant iterator pointing to the end of the string.
248  const_iterator end() const { return myEnd; }
249  /// @}
250 
251  /// @name Manipulators
252  /// @{
253 
254  /// Clears the string. After this operation @ref isstring will return false,
255  /// and @ref isEmpty will return true.
256  void clear() { myStart = myEnd = 0; }
257 
258  /// Trim characters from the left- and right-hand side of the string.
259  /// By default this will trim the ASCII space characters.
261  UT_StringView trim(const char *c =" \t\n\r") const
262  { return trimInternal(c, true, true); }
263 
264  /// Trim characters from the left-hand side of the string.
265  /// By default this will trim the ASCII space characters.
267  UT_StringView trimLeft(const char *c =" \t\n\r") const
268  { return trimInternal(c, true, false); }
269 
270  /// Trim characters from the right-hand side of the string.
271  /// By default this will trim the ASCII space characters.
273  UT_StringView trimRight(const char *c =" \t\n\r") const
274  { return trimInternal(c, false, true); }
275 
276  /// Return the first token
278  UT_StringView firstToken(const char *sep_chars = " \t\n\r") const;
279 
280  /// Splits the string into individual tokens, separated by one or more of
281  /// the @c sep characters given.
283  UT_StringViewArray tokenize(const char *sep_chars =" \t\n\r") const;
284 
285  /// Splits the string into a list of words, using sep_str as the separator
286  /// string. Unlike tokenize, consecutive delimiters are not grouped
287  /// together and are instead taken to delimit empty strings.
288  /// If @c max_split is set, the string is split into at most @c max_sep
289  /// pieces.
291  UT_StringViewArray split(const char *sep_str = " ",
292  int max_split = INT_MAX) const;
293 
294  /// Returns a sub-string of the current string. If positive, the
295  /// @c index parameter is relative to the start. If negative, it's
296  /// relative to the end (e.g. substr(-1,1) will return the last character
297  /// of the string).
298  /// The empty string will be returned for out-of-range values.
301 
302  /// Move the start of the view forward by n characters.
303  /// If N is grreater then length() then it moves to the end.
304  void removePrefix(exint n);
305  /// Move the end of the view backwards by n characters.
306  /// If n is greater then the length() then it moves to the start.
307  void removeSuffix(exint n);
308  /// @}
309 
310  /// @name Operators
311  /// @{
312 
313  /// The @ref compare function compares this string with another, and returns
314  /// and integer less than, equal to, or greater than zero if this string
315  /// is found to be less than, equal to, or greater than the given string,
316  /// respectively. If a length is given, then the strings are compared as
317  /// if they were both of that length, or smaller.
319  int compare(const char *str, exint str_len,
320  bool case_sensitive=true) const;
322  int compare(const UT_StringView &sv,
323  bool case_sensitive=true) const;
324 
325  /// Returns true if the two strings compare as being equal.
326  /// If @c case_sensitive is set to @c false then the strings are compared
327  /// in a case-insensitive fashion.
329  bool equal(const char *str, bool case_sensitive=true) const
330  { return compare(UT_StringView(str),
331  case_sensitive) == 0; }
333  bool equal(const UT_StringView &other,
334  bool case_sensitive=true) const
335  { return compare(other, case_sensitive) == 0; }
336 
337  /// Returns true if the two strings compare as being equal.
339  bool operator==(const char *str) const
340  { return compare(UT_StringView(str)) == 0; }
342  bool operator==(const UT_StringView &other) const
343  { return compare(other) == 0; }
344 
345  /// Returns true if the two strings compare as being not equal.
347  bool operator!=(const char *str) const
348  { return compare(UT_StringView(str)) != 0; }
350  bool operator!=(const UT_StringView &other) const
351  { return compare(other) != 0; }
352 
353  /// Returns true if this string is lexicographically less than the given
354  /// string.
356  bool operator<(const char *str) const
357  { return compare(UT_StringView(str)) < 0; }
359  bool operator<(const UT_StringView &other) const
360  { return compare(other) < 0; }
361 
362  /// Find the first instance of the given character in this string.
363  const_iterator find(char c, const_iterator start) const;
365  const_iterator find(char c) const
366  { return find(c, begin()); }
367 
368  /// Find the first instance of the given substring in this string.
369  const_iterator find(const char *str, const_iterator start) const;
371  const_iterator find(const char *str) const
372  { return find(str, begin()); }
373 
374  /// Find last instance of the given character in this string, searching
375  /// backwards from 'pos'.
377  const_iterator rfind(char c, const_iterator pos) const;
379  const_iterator rfind(char c) const
380  { return rfind(c, end() - 1); }
381  /// Returns true if our string starts with the specified prefix.
383  bool startsWith(const char* prefix,
384  bool case_sensitive = true,
385  exint len = -1) const;
387  bool endsWith(const char* prefix,
388  bool case_sensitive = true,
389  exint len = -1) const;
390  /// @}
391 private:
393  UT_StringView trimInternal(const char *c, bool left, bool right) const;
394 
395  const char *myStart, *myEnd;
396 };
397 
398 UT_API std::ostream &
399 operator<<(std::ostream &os, const UT_StringView &sv);
400 
401 
402 #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