java.lang.StringBuilder

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