1 // © 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 /** 72 * Constructs from a std::string. 73 * @stable ICU 4.2 74 */ StringPiece(const std::string & str)75 StringPiece(const std::string& str) 76 : ptr_(str.data()), length_(static_cast<int32_t>(str.size())) { } 77 /** 78 * Constructs from a const char * pointer and a specified length. 79 * @param offset a const char * pointer (need not be terminated) 80 * @param len the length of the string; must be non-negative 81 * @stable ICU 4.2 82 */ StringPiece(const char * offset,int32_t len)83 StringPiece(const char* offset, int32_t len) : ptr_(offset), length_(len) { } 84 /** 85 * Substring of another StringPiece. 86 * @param x the other StringPiece 87 * @param pos start position in x; must be non-negative and <= x.length(). 88 * @stable ICU 4.2 89 */ 90 StringPiece(const StringPiece& x, int32_t pos); 91 /** 92 * Substring of another StringPiece. 93 * @param x the other StringPiece 94 * @param pos start position in x; must be non-negative and <= x.length(). 95 * @param len length of the substring; 96 * must be non-negative and will be pinned to at most x.length() - pos. 97 * @stable ICU 4.2 98 */ 99 StringPiece(const StringPiece& x, int32_t pos, int32_t len); 100 101 /** 102 * Returns the string pointer. May be NULL if it is empty. 103 * 104 * data() may return a pointer to a buffer with embedded NULs, and the 105 * returned buffer may or may not be null terminated. Therefore it is 106 * typically a mistake to pass data() to a routine that expects a NUL 107 * terminated string. 108 * @return the string pointer 109 * @stable ICU 4.2 110 */ data()111 const char* data() const { return ptr_; } 112 /** 113 * Returns the string length. Same as length(). 114 * @return the string length 115 * @stable ICU 4.2 116 */ size()117 int32_t size() const { return length_; } 118 /** 119 * Returns the string length. Same as size(). 120 * @return the string length 121 * @stable ICU 4.2 122 */ length()123 int32_t length() const { return length_; } 124 /** 125 * Returns whether the string is empty. 126 * @return TRUE if the string is empty 127 * @stable ICU 4.2 128 */ empty()129 UBool empty() const { return length_ == 0; } 130 131 /** 132 * Sets to an empty string. 133 * @stable ICU 4.2 134 */ clear()135 void clear() { ptr_ = NULL; length_ = 0; } 136 137 /** 138 * Reset the stringpiece to refer to new data. 139 * @param xdata pointer the new string data. Need not be nul terminated. 140 * @param len the length of the new data 141 * @stable ICU 4.8 142 */ set(const char * xdata,int32_t len)143 void set(const char* xdata, int32_t len) { ptr_ = xdata; length_ = len; } 144 145 /** 146 * Reset the stringpiece to refer to new data. 147 * @param str a pointer to a NUL-terminated string. 148 * @stable ICU 4.8 149 */ 150 void set(const char* str); 151 152 /** 153 * Removes the first n string units. 154 * @param n prefix length, must be non-negative and <=length() 155 * @stable ICU 4.2 156 */ remove_prefix(int32_t n)157 void remove_prefix(int32_t n) { 158 if (n >= 0) { 159 if (n > length_) { 160 n = length_; 161 } 162 ptr_ += n; 163 length_ -= n; 164 } 165 } 166 167 /** 168 * Removes the last n string units. 169 * @param n suffix length, must be non-negative and <=length() 170 * @stable ICU 4.2 171 */ remove_suffix(int32_t n)172 void remove_suffix(int32_t n) { 173 if (n >= 0) { 174 if (n <= length_) { 175 length_ -= n; 176 } else { 177 length_ = 0; 178 } 179 } 180 } 181 182 /** 183 * Maximum integer, used as a default value for substring methods. 184 * @stable ICU 4.2 185 */ 186 static const int32_t npos; // = 0x7fffffff; 187 188 /** 189 * Returns a substring of this StringPiece. 190 * @param pos start position; must be non-negative and <= length(). 191 * @param len length of the substring; 192 * must be non-negative and will be pinned to at most length() - pos. 193 * @return the substring StringPiece 194 * @stable ICU 4.2 195 */ 196 StringPiece substr(int32_t pos, int32_t len = npos) const { 197 return StringPiece(*this, pos, len); 198 } 199 }; 200 201 /** 202 * Global operator == for StringPiece 203 * @param x The first StringPiece to compare. 204 * @param y The second StringPiece to compare. 205 * @return TRUE if the string data is equal 206 * @stable ICU 4.8 207 */ 208 U_EXPORT UBool U_EXPORT2 209 operator==(const StringPiece& x, const StringPiece& y); 210 211 /** 212 * Global operator != for StringPiece 213 * @param x The first StringPiece to compare. 214 * @param y The second StringPiece to compare. 215 * @return TRUE if the string data is not equal 216 * @stable ICU 4.8 217 */ 218 inline UBool operator!=(const StringPiece& x, const StringPiece& y) { 219 return !(x == y); 220 } 221 222 U_NAMESPACE_END 223 224 #endif // __STRINGPIECE_H__ 225