1 // Copyright (C) 2010, International Business Machines 2 // Corporation and others. All Rights Reserved. 3 // 4 // Copyright 2001 and onwards Google Inc. 5 // Author: Sanjay Ghemawat 6 7 // This code is a contribution of Google code, and the style used here is 8 // a compromise between the original Google code and the ICU coding guidelines. 9 // For example, data types are ICU-ified (size_t,int->int32_t), 10 // and API comments doxygen-ified, but function names and behavior are 11 // as in the original, if possible. 12 // Assertion-style error handling, not available in ICU, was changed to 13 // parameter "pinning" similar to UnicodeString. 14 // 15 // In addition, this is only a partial port of the original Google code, 16 // limited to what was needed so far. The (nearly) complete original code 17 // is in the ICU svn repository at icuhtml/trunk/design/strings/contrib 18 // (see ICU ticket 6765, r25517). 19 20 #ifndef __STRINGPIECE_H__ 21 #define __STRINGPIECE_H__ 22 23 /** 24 * \file 25 * \brief C++ API: StringPiece: Read-only byte string wrapper class. 26 */ 27 28 #include "unicode/utypes.h" 29 #include "unicode/uobject.h" 30 #include "unicode/std_string.h" 31 32 // Arghh! I wish C++ literals were "string". 33 34 U_NAMESPACE_BEGIN 35 36 /** 37 * A string-like object that points to a sized piece of memory. 38 * 39 * We provide non-explicit singleton constructors so users can pass 40 * in a "const char*" or a "string" wherever a "StringPiece" is 41 * expected. 42 * 43 * Functions or methods may use const StringPiece& parameters to accept either 44 * a "const char*" or a "string" value that will be implicitly converted to 45 * a StringPiece. 46 * 47 * Systematic usage of StringPiece is encouraged as it will reduce unnecessary 48 * conversions from "const char*" to "string" and back again. 49 * 50 * @stable ICU 4.2 51 */ 52 class U_COMMON_API StringPiece : public UMemory { 53 private: 54 const char* ptr_; 55 int32_t length_; 56 57 public: 58 /** 59 * Default constructor, creates an empty StringPiece. 60 * @stable ICU 4.2 61 */ 62 StringPiece() : ptr_(NULL), length_(0) { } 63 /** 64 * Constructs from a NUL-terminated const char * pointer. 65 * @param str a NUL-terminated const char * pointer 66 * @stable ICU 4.2 67 */ 68 StringPiece(const char* str); 69 #if U_HAVE_STD_STRING 70 /** 71 * Constructs from a std::string. 72 * @stable ICU 4.2 73 */ 74 StringPiece(const U_STD_NSQ string& str) 75 : ptr_(str.data()), length_(static_cast<int32_t>(str.size())) { } 76 #endif 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 */ 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 */ 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 */ 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 */ 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 */ 129 UBool empty() const { return length_ == 0; } 130 131 /** 132 * Sets to an empty string. 133 * @stable ICU 4.2 134 */ 135 void clear() { ptr_ = NULL; length_ = 0; } 136 137 /** 138 * Reset the stringpiece to refer to new data. 139 * @param data pointer the new string data. Need not be nul terminated. 140 * @param len the length of the new data 141 * @internal 142 */ 143 void set(const char* data, int32_t len) { ptr_ = data; length_ = len; } 144 145 /** 146 * Reset the stringpiece to refer to new data. 147 * @param str a pointer to a NUL-terminated string. 148 * @internal 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 */ 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 */ 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 * @internal 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 * @internal 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
