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_Compiler.h>
19 #include <SYS/SYS_Inline.h>
20 #include <SYS/SYS_String.h>
21 #include <string.h>
22 #include <iosfwd>
23 
26 
27 /// @brief A utility class to do read-only operations on a subset of an
28 /// existing string.
29 /// @note This object does not take ownership over the data being looked at,
30 /// so care must be taken that the owning object doesn't not go out of scope
31 /// before the view object.
33 {
34 public:
35  /// Default constructor. Constructs an empty non-string.
38  : myStart(nullptr), myEnd(nullptr)
39  { /**/ }
40 
41  /// Construct a string view from the entirety of a null-terminated string.
43  UT_StringView(const char *str)
44  : myStart(str), myEnd(nullptr)
45  {
46  if (myStart)
47  myEnd = myStart + ::strlen(str);
48  }
49 
50  /// Construct a string view on a string of a given length.
52  explicit UT_StringView(const char *str, exint len)
53  : myStart(str), myEnd(nullptr)
54  {
55  UT_ASSERT(len >= 0 && "String View length should not be negative");
56  if (myStart)
57  myEnd = myStart + len;
58  }
59 
60  /// Construct a string view on a given string range. The @c end pointer
61  /// should point to one past the end of the string (i.e. in the case of
62  /// null terminated strings, it should point at the null character).
64  explicit UT_StringView(const char *start, const char *end)
65  : myStart(start), myEnd(end)
66  {
67  UT_ASSERT((!myStart && !myEnd) || myStart <= myEnd);
68  }
69 
70  /// Copy constructor.
72  UT_StringView(const UT_StringView &o) = default;
73 
74  /// Assignment operator
76  UT_StringView & operator=(const UT_StringView &o) = default;
77 
78  /// @name Query functions
79  /// @{
80 
81  /// Returns the length of the string in bytes.
83  exint length() const { return exint(myEnd - myStart); }
84 
85  /// Returns @c true if the string is empty.
87  bool isEmpty() const { return myStart == myEnd; }
88 
89  /// Returns @c true if the view points to a valid string, even an empty one
91  bool isstring() const { return myStart; }
92 
93  /// Test whether the string is not an empty string (or nullptr)
95  SYS_SAFE_BOOL operator bool() const { return !isEmpty(); }
96 
97  /// Returns the memory, in bytes, used by this object.
99  int64 getMemoryUsage(bool inclusive) const
100  { return inclusive ? sizeof(*this) : 0; }
101 
102  /// Returns the character at index @c i. No bounds checking is performed.
104  char operator[](exint i) const { return myStart[i]; }
105 
106  /// @}
107 
108  /// @name Iterators
109  /// @{
110 
111  /// The iterator type. @ref UT_StringView only provides read-only iterators.
112  typedef const char * const_iterator;
113 
114  /// Returns a constant iterator pointing to the beginning of the string.
116  const_iterator begin() const { return myStart; }
117 
118  /// Returns a constant iterator pointing to the end of the string.
120  const_iterator end() const { return myEnd; }
121  /// @}
122 
123  /// @name Manipulators
124  /// @{
125 
126  /// Clears the string. After this operation @ref isstring will return false,
127  /// and @ref isEmpty will return true.
128  void clear() { myStart = myEnd = 0; }
129 
130  /// Trim characters from the left- and right-hand side of the string.
131  /// By default this will trim the ASCII space characters.
133  UT_StringView trim(const char *c =" \t\n\r") const
134  { return trimInternal(c, true, true); }
135 
136  /// Trim characters from the left-hand side of the string.
137  /// By default this will trim the ASCII space characters.
139  UT_StringView trimLeft(const char *c =" \t\n\r") const
140  { return trimInternal(c, true, false); }
141 
142  /// Trim characters from the right-hand side of the string.
143  /// By default this will trim the ASCII space characters.
145  UT_StringView trimRight(const char *c =" \t\n\r") const
146  { return trimInternal(c, false, true); }
147 
148  /// Return the first token
150  UT_StringView firstToken(const char *sep_chars = " \t\n\r") const;
151 
152  /// Splits the string into individual tokens, separated by one or more of
153  /// the @c sep characters given.
155  UT_StringViewArray tokenize(const char *sep_chars =" \t\n\r") const;
156 
157  /// Splits the string into a list of words, using sep_str as the separator
158  /// string. Unlike tokenize, consecutive delimiters are not grouped
159  /// together and are instead taken to delimit empty strings.
160  /// If @c max_split is set, the string is split into at most @c max_sep
161  /// pieces.
163  UT_StringViewArray split(const char *sep_str = " ",
164  int max_split = INT_MAX) const;
165 
166  /// Returns a sub-string of the current string. If positive, the
167  /// @c index parameter is relative to the start. If negative, it's
168  /// relative to the end (e.g. substr(-1,1) will return the last character
169  /// of the string).
170  /// The empty string will be returned for out-of-range values.
173 
174  /// @}
175 
176  /// @name Operators
177  /// @{
178 
179  /// The @ref compare function compares this string with another, and returns
180  /// and integer less than, equal to, or greater than zero if this string
181  /// is found to be less than, equal to, or greater than the given string,
182  /// respectively. If a length is given, then the strings are compared as
183  /// if they were both of that length, or smaller.
185  int compare(const char *str, exint str_len,
186  bool case_sensitive=true) const;
188  int compare(const UT_StringView &sv,
189  bool case_sensitive=true) const;
190 
191  /// Returns true if the two strings compare as being equal.
192  /// If @c case_sensitive is set to @c false then the strings are compared
193  /// in a case-insensitive fashion.
195  bool equal(const char *str, bool case_sensitive=true) const
196  { return compare(UT_StringView(str),
197  case_sensitive) == 0; }
199  bool equal(const UT_StringView &other,
200  bool case_sensitive=true) const
201  { return compare(other, case_sensitive) == 0; }
202 
203  /// Returns true if the two strings compare as being equal.
205  bool operator==(const char *str) const
206  { return compare(UT_StringView(str)) == 0; }
208  bool operator==(const UT_StringView &other) const
209  { return compare(other) == 0; }
210 
211  /// Returns true if the two strings compare as being not equal.
213  bool operator!=(const char *str) const
214  { return compare(UT_StringView(str)) != 0; }
216  bool operator!=(const UT_StringView &other) const
217  { return compare(other) != 0; }
218 
219  /// Returns true if this string is lexicographically less than the given
220  /// string.
222  bool operator<(const char *str) const
223  { return compare(UT_StringView(str)) < 0; }
225  bool operator<(const UT_StringView &other) const
226  { return compare(other) < 0; }
227 
228  /// Find the first instance of the given character in this string.
229  const_iterator find(char c, const_iterator start) const;
231  const_iterator find(char c) const
232  { return find(c, begin()); }
233 
234  /// Find the first instance of the given substring in this string.
235  const_iterator find(const char *str, const_iterator start) const;
237  const_iterator find(const char *str) const
238  { return find(str, begin()); }
239 
240  /// Find last instance of the given character in this string, searching
241  /// backwards from 'pos'.
243  const_iterator rfind(char c, const_iterator pos) const;
245  const_iterator rfind(char c) const
246  { return rfind(c, end() - 1); }
247 
248  /// @}
249 private:
251  UT_StringView trimInternal(const char *c, bool left, bool right) const;
252 
253  const char *myStart, *myEnd;
254 };
255 
256 UT_API std::ostream &
257 operator<<(std::ostream &os, const UT_StringView &sv);
258 
259 
260 #endif // __UT_StringView__
UT_API std::ostream & operator<<(std::ostream &os, const UT_StringView &sv)
SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE const_iterator find(const char *str) const
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
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:176
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.
SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE int64 getMemoryUsage(bool inclusive) const
Returns the memory, in bytes, used by this object.
Definition: UT_StringView.h:99
long long int64
Definition: SYS_Types.h:111
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:32
SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE bool isEmpty() const
Returns true if the string is empty.
Definition: UT_StringView.h:87
SYS_FORCE_INLINE UT_StringView()
Default constructor. Constructs an empty non-string.
Definition: UT_StringView.h:37
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.
Definition: UT_StringView.h:83
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:62
int64 exint
Definition: SYS_Types.h:120
SYS_FORCE_INLINE UT_StringView(const char *str)
Construct a string view from the entirety of a null-terminated string.
Definition: UT_StringView.h:43
#define SYS_FORCE_INLINE
Definition: SYS_Inline.h:45
GLuint GLuint end
Definition: glew.h:1253
const GLfloat * c
Definition: glew.h:16296
GLuint GLsizei GLsizei * length
Definition: glew.h:1825
#define SYS_NO_DISCARD_RESULT
Definition: SYS_Compiler.h:100
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
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 SYS_FORCE_INLINE bool equal(const char *str, bool case_sensitive=true) const
FMT_CONSTEXPR bool find(Ptr first, Ptr last, T value, Ptr &out)
Definition: format.h:2104
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 *str, exint len)
Construct a string view on a string of a given length.
Definition: UT_StringView.h:52
SYS_FORCE_INLINE UT_StringView(const char *start, const char *end)
Definition: UT_StringView.h:64
SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE bool isstring() const
Returns true if the view points to a valid string, even an empty one.
Definition: UT_StringView.h:91
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:24
SYS_NO_DISCARD_RESULT SYS_FORCE_INLINE bool operator!=(const UT_StringView &other) const
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