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