1 // Copyright (C) 2016 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 // Copyright (C) 2009-2013, International Business Machines 4 // Corporation and others. All Rights Reserved. 5 // 6 // Copyright 2001 and onwards Google Inc. 7 // Author: Sanjay Ghemawat 8 9 // This code is a contribution of Google code, and the style used here is 10 // a compromise between the original Google code and the ICU coding guidelines. 11 // For example, data types are ICU-ified (size_t,int->int32_t), 12 // and API comments doxygen-ified, but function names and behavior are 13 // as in the original, if possible. 14 // Assertion-style error handling, not available in ICU, was changed to 15 // parameter "pinning" similar to UnicodeString. 16 // 17 // In addition, this is only a partial port of the original Google code, 18 // limited to what was needed so far. The (nearly) complete original code 19 // is in the ICU svn repository at icuhtml/trunk/design/strings/contrib 20 // (see ICU ticket 6765, r25517). 21 22 #ifndef __STRINGPIECE_H__ 23 #define __STRINGPIECE_H__ 24 25 /** 26 * \file 27 * \brief C++ API: StringPiece: Read-only byte string wrapper class. 28 */ 29 30 #include "unicode/utypes.h" 31 #include "unicode/uobject.h" 32 #include "unicode/std_string.h" 33 34 // Arghh! I wish C++ literals were "string". 35 36 U_NAMESPACE_BEGIN 37 38 /** 39 * A string-like object that points to a sized piece of memory. 40 * 41 * We provide non-explicit singleton constructors so users can pass 42 * in a "const char*" or a "string" wherever a "StringPiece" is 43 * expected. 44 * 45 * Functions or methods may use StringPiece parameters to accept either a 46 * "const char*" or a "string" value that will be implicitly converted to a 47 * StringPiece. 48 * 49 * Systematic usage of StringPiece is encouraged as it will reduce unnecessary 50 * conversions from "const char*" to "string" and back again. 51 * 52 * @stable ICU 4.2 53 */ 54 class U_COMMON_API StringPiece : public UMemory { 55 private: 56 const char* ptr_; 57 int32_t length_; 58 59 public: 60 /** 61 * Default constructor, creates an empty StringPiece. 62 * @stable ICU 4.2 63 */ StringPiece()64 StringPiece() : ptr_(NULL), length_(0) { } 65 /** 66 * Constructs from a NUL-terminated const char * pointer. 67 * @param str a NUL-terminated const char * pointer 68 * @stable ICU 4.2 69 */ 70 StringPiece(const char* str); 71 #if U_HAVE_STD_STRING 72 /** 73 * Constructs from a std::string. 74 * @stable ICU 4.2 75 */ StringPiece(const std::string & str)76 StringPiece(const std::string& str) 77 : ptr_(str.data()), length_(static_cast<int32_t>(str.size())) { } 78 #endif 79 /** 80 * Constructs from a const char * pointer and a specified length. 81 * @param offset a const char * pointer (need not be terminated) 82 * @param len the length of the string; must be non-negative 83 * @stable ICU 4.2 84 */ StringPiece(const char * offset,int32_t len)85 StringPiece(const char* offset, int32_t len) : ptr_(offset), length_(len) { } 86 /** 87 * Substring of another StringPiece. 88 * @param x the other StringPiece 89 * @param pos start position in x; must be non-negative and <= x.length(). 90 * @stable ICU 4.2 91 */ 92 StringPiece(const StringPiece& x, int32_t pos); 93 /** 94 * Substring of another StringPiece. 95 * @param x the other StringPiece 96 * @param pos start position in x; must be non-negative and <= x.length(). 97 * @param len length of the substring; 98 * must be non-negative and will be pinned to at most x.length() - pos. 99 * @stable ICU 4.2 100 */ 101 StringPiece(const StringPiece& x, int32_t pos, int32_t len); 102 103 /** 104 * Returns the string pointer. May be NULL if it is empty. 105 * 106 * data() may return a pointer to a buffer with embedded NULs, and the 107 * returned buffer may or may not be null terminated. Therefore it is 108 * typically a mistake to pass data() to a routine that expects a NUL 109 * terminated string. 110 * @return the string pointer 111 * @stable ICU 4.2 112 */ data()113 const char* data() const { return ptr_; } 114 /** 115 * Returns the string length. Same as length(). 116 * @return the string length 117 * @stable ICU 4.2 118 */ size()119 int32_t size() const { return length_; } 120 /** 121 * Returns the string length. Same as size(). 122 * @return the string length 123 * @stable ICU 4.2 124 */ length()125 int32_t length() const { return length_; } 126 /** 127 * Returns whether the string is empty. 128 * @return TRUE if the string is empty 129 * @stable ICU 4.2 130 */ empty()131 UBool empty() const { return length_ == 0; } 132 133 /** 134 * Sets to an empty string. 135 * @stable ICU 4.2 136 */ clear()137 void clear() { ptr_ = NULL; length_ = 0; } 138 139 /** 140 * Reset the stringpiece to refer to new data. 141 * @param xdata pointer the new string data. Need not be nul terminated. 142 * @param len the length of the new data 143 * @stable ICU 4.8 144 */ set(const char * xdata,int32_t len)145 void set(const char* xdata, int32_t len) { ptr_ = xdata; length_ = len; } 146 147 /** 148 * Reset the stringpiece to refer to new data. 149 * @param str a pointer to a NUL-terminated string. 150 * @stable ICU 4.8 151 */ 152 void set(const char* str); 153 154 /** 155 * Removes the first n string units. 156 * @param n prefix length, must be non-negative and <=length() 157 * @stable ICU 4.2 158 */ remove_prefix(int32_t n)159 void remove_prefix(int32_t n) { 160 if (n >= 0) { 161 if (n > length_) { 162 n = length_; 163 } 164 ptr_ += n; 165 length_ -= n; 166 } 167 } 168 169 /** 170 * Removes the last n string units. 171 * @param n suffix length, must be non-negative and <=length() 172 * @stable ICU 4.2 173 */ remove_suffix(int32_t n)174 void remove_suffix(int32_t n) { 175 if (n >= 0) { 176 if (n <= length_) { 177 length_ -= n; 178 } else { 179 length_ = 0; 180 } 181 } 182 } 183 184 /** 185 * Maximum integer, used as a default value for substring methods. 186 * @stable ICU 4.2 187 */ 188 static const int32_t npos; // = 0x7fffffff; 189 190 /** 191 * Returns a substring of this StringPiece. 192 * @param pos start position; must be non-negative and <= length(). 193 * @param len length of the substring; 194 * must be non-negative and will be pinned to at most length() - pos. 195 * @return the substring StringPiece 196 * @stable ICU 4.2 197 */ 198 StringPiece substr(int32_t pos, int32_t len = npos) const { 199 return StringPiece(*this, pos, len); 200 } 201 }; 202 203 /** 204 * Global operator == for StringPiece 205 * @param x The first StringPiece to compare. 206 * @param y The second StringPiece to compare. 207 * @return TRUE if the string data is equal 208 * @stable ICU 4.8 209 */ 210 U_EXPORT UBool U_EXPORT2 211 operator==(const StringPiece& x, const StringPiece& y); 212 213 /** 214 * Global operator != for StringPiece 215 * @param x The first StringPiece to compare. 216 * @param y The second StringPiece to compare. 217 * @return TRUE if the string data is not equal 218 * @stable ICU 4.8 219 */ 220 inline UBool operator!=(const StringPiece& x, const StringPiece& y) { 221 return !(x == y); 222 } 223 224 U_NAMESPACE_END 225 226 #endif // __STRINGPIECE_H__ 227