string revision 9cb0478662a7c988146fff0d868bba2839ea80f2
1/* -*- c++ -*- */ 2/* 3 * Copyright (C) 2009 The Android Open Source Project 4 * All rights reserved. 5 * 6 * Redistribution and use in source and binary forms, with or without 7 * modification, are permitted provided that the following conditions 8 * are met: 9 * * Redistributions of source code must retain the above copyright 10 * notice, this list of conditions and the following disclaimer. 11 * * Redistributions in binary form must reproduce the above copyright 12 * notice, this list of conditions and the following disclaimer in 13 * the documentation and/or other materials provided with the 14 * distribution. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 17 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 18 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 19 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 20 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 21 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 22 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS 23 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 24 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 25 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 26 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27 * SUCH DAMAGE. 28 */ 29 30#ifndef ANDROID_ASTL_STRING__ 31#define ANDROID_ASTL_STRING__ 32 33#include <cstddef> 34 35namespace std { 36 37// Simple string implementation. Its purpose is to be able to compile code that 38// uses the STL and requires std::string. 39// 40// IMPORTANT: 41// . This class it is not fully STL compliant. Some constructors/methods maybe 42// missing, they will be added on demand. 43// . We don't provide a std::basic_string template that std::string extends 44// because we use only char (wchar is not supported on Android). 45// . The memory allocation scheme uses the heap. Since Android has the concept 46// of SharedBuffer, we may, in the future, templatize this class and add an 47// allocation parameter. 48// . The implementation is not optimized in any way (no copy on write support), 49// temporary instance may be expensive. 50// . Currently there is no support for iterators. 51// 52 53class string 54{ 55 public: 56 typedef size_t size_type; 57 typedef char value_type; 58 59 static const size_type npos = static_cast<size_type>(-1); 60 61 // Constructors 62 string(); 63 64 // Construct a string from a source's substring. 65 // @param str The source string. 66 // @param pos The index of the character to start the copy at. 67 // @param n The number of characters to copy. Use string::npos for the 68 // remainder. 69 string(const string& str, size_t pos = 0, size_type n = npos); 70 71 // Construct a string from a C string. 72 // @param str The source string, must be '\0' terminated. 73 string(const value_type *str); 74 75 // Construct a string from a char array. 76 // @param str The source C string. '\0' are ignored. 77 // @param n The number of characters to copy. 78 string(const value_type *str, size_type n); 79 80 // Construct a string from a repetition of a character. 81 // @param n The number of characters. 82 // @param c The character to use. 83 string(size_t n, char c); 84 85 // Construct a string from a char array. 86 // @param begin The start of the source C string. '\0' are ignored. 87 // @param end The end of source C string. Points just pass the last 88 // character. 89 string(const value_type *begin, const value_type *end); 90 91 ~string(); 92 93 // @return The number of characters in the string, not including any 94 // null-termination. 95 size_type length() const { return mLength; } 96 size_type size() const { return mLength; } 97 98 // @return A pointer to null-terminated contents. 99 const value_type *c_str() const { return mData; } 100 const value_type *data() const { return mData; } 101 102 // Empty the string on return. Release the internal buffer. Length 103 // and capacity are both 0 on return. If you want to keep the 104 // internal buffer around for reuse, call 'erase' instead. 105 void clear(); 106 107 // @return true if the string is empty. 108 bool empty() const { return this->size() == 0; } 109 110 // Remove 'len' characters from the string starting at 'pos'. The 111 // string length is reduced by 'len'. If len is greater or equal 112 // to the number of characters in the string, it is truncated at 113 // 'pos'. If 'pos' is beyond the end of the string, 'erase' does 114 // nothing. Note, regular STL implementations throw a out_of_range 115 // exception in this case. 116 // Internally, the capacity of the buffer remains unchanged. If 117 // you wanted to recover the deleted chars' memory you should call 118 // 'reserve' explicitly (see also 'clear'). 119 // @param pos Index of the first character to remove (default to 0) 120 // @param n Number of characters to delete. (default to remainder) 121 // @return a reference to this string. 122 string& erase(size_type pos = 0, size_type n = npos); 123 124 // @param str The string to be append. 125 // @return A reference to this string. 126 string& operator+=(const string& str) { return this->append(str); } 127 128 // @param str The C string to be append. 129 // @return A reference to this string. 130 string& operator+=(const value_type *str) { return this->append(str); } 131 132 // @param c A character to be append. 133 // @return A reference to this string. 134 string& operator+=(const char c) { this->push_back(c); return *this; } 135 136 // @param c A character to be append. 137 void push_back(const char c); 138 139 // no-op if str is NULL. 140 string& append(const value_type *str); 141 // no-op if str is NULL. n must be >= 0. 142 string& append(const value_type *str, size_type n); 143 // no-op if str is NULL. pos and n must be >= 0. 144 string& append(const value_type *str, size_type pos, size_type n); 145 string& append(const string& str); 146 147 // Comparison. 148 // @return 0 if this==other, < 0 if this < other and > 0 if this > other. 149 // Don't assume the values are -1, 0, 1 150 int compare(const string& other) const; 151 int compare(const value_type *other) const; 152 153 friend bool operator==(const string& left, const string& right); 154 friend bool operator==(const string& left, const value_type *right); 155 friend bool operator==(const value_type *left, const string& right) { return right == left; } 156 friend bool operator!=(const string& left, const string& right) { return !(left == right); } 157 friend bool operator!=(const string& left, const char* right) { return !(left == right); } 158 friend bool operator!=(const value_type *left, const string& right) { return !(left == right); } 159 160 // @return Number of elements for which memory has been allocated. capacity >= size(). 161 size_type capacity() const { return mCapacity; } 162 163 // Change the capacity to new_size. No effect if new_size < size(). 164 // 0 means Shrink to fit. 165 // @param new_size number of character to be allocated. 166 void reserve(size_type new_size = 0); 167 168 // Exchange the content of this with the content of other. 169 // @param other Instance to swap this one with. 170 void swap(string& other); 171 172 // Accessors. 173 // @param pos of the char. No boundary, signed checks are done. 174 // @return a const reference to the char. 175 const char& operator[](const size_type pos) const; 176 177 // @param pos of the char. No boundary, signed checks are done. 178 // @return a reference to the char. 179 char& operator[](const size_type pos); 180 181 // Assignments. 182 string& operator=(const string& str) { return assign(str); } 183 string& operator=(const char* str) { return assign(str); } 184 string& operator=(char c); 185 186 string& assign(const string& str); 187 // Assign a substring of the original. 188 // @param str Original string. 189 // @param pos Index of the start of the copy. 190 // @param n Number of character to be copied. 191 string& assign(const string& str, size_type pos, size_type n); 192 string& assign(const value_type *str); 193 194 // Assign a non-nul terminated array of chars. 195 // @param array Of chars non-nul terminated. 196 // @param len Length of the array. 197 string& assign(const value_type *array, size_type len); 198 199 // Concat. Prefer using += or append. 200 // Uses unnamed object for return value optimization. 201 friend string operator+(const string& left, const string& right) { 202 return string(left).append(right); 203 } 204 friend string operator+(const string& left, const value_type *right) { 205 return string(left).append(right); 206 } 207 friend string operator+(const value_type *left, const string& right) { 208 return string(left).append(right); 209 } 210 friend string operator+(const string& left, char right) { 211 return string(left).operator+=(right); 212 } 213 friend string operator+(char left, const string& right) { 214 return string(&left, 1).append(right); 215 } 216 217 // Find the position of a sub-string. The empty string is always 218 // found at the requested position except when it's beyond the 219 // string's end. 220 // @param str String to locate. 221 // @param pos Index of the character to search from. Default to 0. 222 // @return Index of start of the first occurrence of the 223 // string. string::npos if no occurrence of str was found from the 224 // starting position. 225 size_type find(const string& str, size_type pos = 0) const { 226 return find(str.mData, pos); 227 } 228 229 // Find the position of a C sub-string. The empty string is always 230 // found at the requested position except when it's beyond the 231 // string's end. 232 // @param str C string to locate. 233 // @param pos Index of the character to search from. Default to 0. 234 // @return Index of start of the first occurrence of the 235 // string. string::npos if no occurrence of str was found from the 236 // starting position. 237 size_type find(const value_type *str, size_type pos = 0) const; 238 239 // @return a substring of this one. 240 string substr(size_type pos = 0, size_type n = npos) const { 241 return string(*this, pos, n); 242 } 243 244 private: 245 bool SafeMalloc(size_type n); 246 void SafeRealloc(size_type n); 247 void SafeFree(value_type *str); 248 void ResetTo(value_type *str); 249 void ConstructEmptyString(); 250 void Constructor(const value_type *str, size_type n); 251 void Constructor(const value_type *str, size_type pos, size_type n); 252 void Constructor(size_type num, char c); 253 void DeleteSafe(); 254 void Append(const value_type *str, size_type len); 255 256 value_type *mData; // pointer to the buffer 257 size_type mCapacity; // size of the buffer. 258 size_type mLength; // len of the string excl. null-terminator. 259}; 260 261} // namespace std 262 263#endif // ANDROID_ASTL_STRING__ 264