1 /* 2 * Copyright (c) 2003, 2012, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.lang; 27 28 29 /** 30 * A mutable sequence of characters. This class provides an API compatible 31 * with {@code StringBuffer}, but with no guarantee of synchronization. 32 * This class is designed for use as a drop-in replacement for 33 * {@code StringBuffer} in places where the string buffer was being 34 * used by a single thread (as is generally the case). Where possible, 35 * it is recommended that this class be used in preference to 36 * {@code StringBuffer} as it will be faster under most implementations. 37 * 38 * <p>The principal operations on a {@code StringBuilder} are the 39 * {@code append} and {@code insert} methods, which are 40 * overloaded so as to accept data of any type. Each effectively 41 * converts a given datum to a string and then appends or inserts the 42 * characters of that string to the string builder. The 43 * {@code append} method always adds these characters at the end 44 * of the builder; the {@code insert} method adds the characters at 45 * a specified point. 46 * <p> 47 * For example, if {@code z} refers to a string builder object 48 * whose current contents are "{@code start}", then 49 * the method call {@code z.append("le")} would cause the string 50 * builder to contain "{@code startle}", whereas 51 * {@code z.insert(4, "le")} would alter the string builder to 52 * contain "{@code starlet}". 53 * <p> 54 * In general, if sb refers to an instance of a {@code StringBuilder}, 55 * then {@code sb.append(x)} has the same effect as 56 * {@code sb.insert(sb.length(), x)}. 57 * <p> 58 * Every string builder has a capacity. As long as the length of the 59 * character sequence contained in the string builder does not exceed 60 * the capacity, it is not necessary to allocate a new internal 61 * buffer. If the internal buffer overflows, it is automatically made larger. 62 * 63 * <p>Instances of {@code StringBuilder} are not safe for 64 * use by multiple threads. If such synchronization is required then it is 65 * recommended that {@link java.lang.StringBuffer} be used. 66 * 67 * <p>Unless otherwise noted, passing a {@code null} argument to a constructor 68 * or method in this class will cause a {@link NullPointerException} to be 69 * thrown. 70 * 71 * @author Michael McCloskey 72 * @see java.lang.StringBuffer 73 * @see java.lang.String 74 * @since 1.5 75 */ 76 public final class StringBuilder 77 extends AbstractStringBuilder 78 implements java.io.Serializable, CharSequence 79 { 80 81 /** use serialVersionUID for interoperability */ 82 static final long serialVersionUID = 4383685877147921099L; 83 84 /** 85 * Constructs a string builder with no characters in it and an 86 * initial capacity of 16 characters. 87 */ 88 public StringBuilder() { 89 super(16); 90 } 91 92 /** 93 * Constructs a string builder with no characters in it and an 94 * initial capacity specified by the {@code capacity} argument. 95 * 96 * @param capacity the initial capacity. 97 * @throws NegativeArraySizeException if the {@code capacity} 98 * argument is less than {@code 0}. 99 */ 100 public StringBuilder(int capacity) { 101 super(capacity); 102 } 103 104 /** 105 * Constructs a string builder initialized to the contents of the 106 * specified string. The initial capacity of the string builder is 107 * {@code 16} plus the length of the string argument. 108 * 109 * @param str the initial contents of the buffer. 110 */ 111 public StringBuilder(String str) { 112 super(str.length() + 16); 113 append(str); 114 } 115 116 /** 117 * Constructs a string builder that contains the same characters 118 * as the specified {@code CharSequence}. The initial capacity of 119 * the string builder is {@code 16} plus the length of the 120 * {@code CharSequence} argument. 121 * 122 * @param seq the sequence to copy. 123 */ 124 public StringBuilder(CharSequence seq) { 125 this(seq.length() + 16); 126 append(seq); 127 } 128 129 @Override 130 public StringBuilder append(Object obj) { 131 return append(String.valueOf(obj)); 132 } 133 134 @Override 135 public StringBuilder append(String str) { 136 super.append(str); 137 return this; 138 } 139 140 /** 141 * Appends the specified {@code StringBuffer} to this sequence. 142 * <p> 143 * The characters of the {@code StringBuffer} argument are appended, 144 * in order, to this sequence, increasing the 145 * length of this sequence by the length of the argument. 146 * If {@code sb} is {@code null}, then the four characters 147 * {@code "null"} are appended to this sequence. 148 * <p> 149 * Let <i>n</i> be the length of this character sequence just prior to 150 * execution of the {@code append} method. Then the character at index 151 * <i>k</i> in the new character sequence is equal to the character at 152 * index <i>k</i> in the old character sequence, if <i>k</i> is less than 153 * <i>n</i>; otherwise, it is equal to the character at index <i>k-n</i> 154 * in the argument {@code sb}. 155 * 156 * @param sb the {@code StringBuffer} to append. 157 * @return a reference to this object. 158 */ 159 public StringBuilder append(StringBuffer sb) { 160 super.append(sb); 161 return this; 162 } 163 164 @Override 165 public StringBuilder append(CharSequence s) { 166 super.append(s); 167 return this; 168 } 169 170 /** 171 * @throws IndexOutOfBoundsException {@inheritDoc} 172 */ 173 @Override 174 public StringBuilder append(CharSequence s, int start, int end) { 175 super.append(s, start, end); 176 return this; 177 } 178 179 @Override 180 public StringBuilder append(char[] str) { 181 super.append(str); 182 return this; 183 } 184 185 /** 186 * @throws IndexOutOfBoundsException {@inheritDoc} 187 */ 188 @Override 189 public StringBuilder append(char[] str, int offset, int len) { 190 super.append(str, offset, len); 191 return this; 192 } 193 194 @Override 195 public StringBuilder append(boolean b) { 196 super.append(b); 197 return this; 198 } 199 200 @Override 201 public StringBuilder append(char c) { 202 super.append(c); 203 return this; 204 } 205 206 @Override 207 public StringBuilder append(int i) { 208 super.append(i); 209 return this; 210 } 211 212 @Override 213 public StringBuilder append(long lng) { 214 super.append(lng); 215 return this; 216 } 217 218 @Override 219 public StringBuilder append(float f) { 220 super.append(f); 221 return this; 222 } 223 224 @Override 225 public StringBuilder append(double d) { 226 super.append(d); 227 return this; 228 } 229 230 /** 231 * @since 1.5 232 */ 233 @Override 234 public StringBuilder appendCodePoint(int codePoint) { 235 super.appendCodePoint(codePoint); 236 return this; 237 } 238 239 /** 240 * @throws StringIndexOutOfBoundsException {@inheritDoc} 241 */ 242 @Override 243 public StringBuilder delete(int start, int end) { 244 super.delete(start, end); 245 return this; 246 } 247 248 /** 249 * @throws StringIndexOutOfBoundsException {@inheritDoc} 250 */ 251 @Override 252 public StringBuilder deleteCharAt(int index) { 253 super.deleteCharAt(index); 254 return this; 255 } 256 257 /** 258 * @throws StringIndexOutOfBoundsException {@inheritDoc} 259 */ 260 @Override 261 public StringBuilder replace(int start, int end, String str) { 262 super.replace(start, end, str); 263 return this; 264 } 265 266 /** 267 * @throws StringIndexOutOfBoundsException {@inheritDoc} 268 */ 269 @Override 270 public StringBuilder insert(int index, char[] str, int offset, 271 int len) 272 { 273 super.insert(index, str, offset, len); 274 return this; 275 } 276 277 /** 278 * @throws StringIndexOutOfBoundsException {@inheritDoc} 279 */ 280 @Override 281 public StringBuilder insert(int offset, Object obj) { 282 super.insert(offset, obj); 283 return this; 284 } 285 286 /** 287 * @throws StringIndexOutOfBoundsException {@inheritDoc} 288 */ 289 @Override 290 public StringBuilder insert(int offset, String str) { 291 super.insert(offset, str); 292 return this; 293 } 294 295 /** 296 * @throws StringIndexOutOfBoundsException {@inheritDoc} 297 */ 298 @Override 299 public StringBuilder insert(int offset, char[] str) { 300 super.insert(offset, str); 301 return this; 302 } 303 304 /** 305 * @throws IndexOutOfBoundsException {@inheritDoc} 306 */ 307 @Override 308 public StringBuilder insert(int dstOffset, CharSequence s) { 309 super.insert(dstOffset, s); 310 return this; 311 } 312 313 /** 314 * @throws IndexOutOfBoundsException {@inheritDoc} 315 */ 316 @Override 317 public StringBuilder insert(int dstOffset, CharSequence s, 318 int start, int end) 319 { 320 super.insert(dstOffset, s, start, end); 321 return this; 322 } 323 324 /** 325 * @throws StringIndexOutOfBoundsException {@inheritDoc} 326 */ 327 @Override 328 public StringBuilder insert(int offset, boolean b) { 329 super.insert(offset, b); 330 return this; 331 } 332 333 /** 334 * @throws IndexOutOfBoundsException {@inheritDoc} 335 */ 336 @Override 337 public StringBuilder insert(int offset, char c) { 338 super.insert(offset, c); 339 return this; 340 } 341 342 /** 343 * @throws StringIndexOutOfBoundsException {@inheritDoc} 344 */ 345 @Override 346 public StringBuilder insert(int offset, int i) { 347 super.insert(offset, i); 348 return this; 349 } 350 351 /** 352 * @throws StringIndexOutOfBoundsException {@inheritDoc} 353 */ 354 @Override 355 public StringBuilder insert(int offset, long l) { 356 super.insert(offset, l); 357 return this; 358 } 359 360 /** 361 * @throws StringIndexOutOfBoundsException {@inheritDoc} 362 */ 363 @Override 364 public StringBuilder insert(int offset, float f) { 365 super.insert(offset, f); 366 return this; 367 } 368 369 /** 370 * @throws StringIndexOutOfBoundsException {@inheritDoc} 371 */ 372 @Override 373 public StringBuilder insert(int offset, double d) { 374 super.insert(offset, d); 375 return this; 376 } 377 378 @Override 379 public int indexOf(String str) { 380 return super.indexOf(str); 381 } 382 383 @Override 384 public int indexOf(String str, int fromIndex) { 385 return super.indexOf(str, fromIndex); 386 } 387 388 @Override 389 public int lastIndexOf(String str) { 390 return super.lastIndexOf(str); 391 } 392 393 @Override 394 public int lastIndexOf(String str, int fromIndex) { 395 return super.lastIndexOf(str, fromIndex); 396 } 397 398 @Override 399 public StringBuilder reverse() { 400 super.reverse(); 401 return this; 402 } 403 404 @Override 405 public String toString() { 406 // Create a copy, don't share the array 407 return new String(value, 0, count); 408 } 409 410 /** 411 * Save the state of the {@code StringBuilder} instance to a stream 412 * (that is, serialize it). 413 * 414 * @serialData the number of characters currently stored in the string 415 * builder ({@code int}), followed by the characters in the 416 * string builder ({@code char[]}). The length of the 417 * {@code char} array may be greater than the number of 418 * characters currently stored in the string builder, in which 419 * case extra characters are ignored. 420 */ 421 private void writeObject(java.io.ObjectOutputStream s) 422 throws java.io.IOException { 423 s.defaultWriteObject(); 424 s.writeInt(count); 425 s.writeObject(value); 426 } 427 428 /** 429 * readObject is called to restore the state of the StringBuffer from 430 * a stream. 431 */ 432 private void readObject(java.io.ObjectInputStream s) 433 throws java.io.IOException, ClassNotFoundException { 434 s.defaultReadObject(); 435 count = s.readInt(); 436 value = (char[]) s.readObject(); 437 } 438 439 }