KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > lang > StringBuilder


1 /*
2  * @(#)StringBuilder.java 1.9 04/07/16
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7
8 package java.lang;
9
10 import sun.misc.FloatingDecimal;
11
12 /**
13  * A mutable sequence of characters. This class provides an API compatible
14  * with <code>StringBuffer</code>, but with no guarantee of synchronization.
15  * This class is designed for use as a drop-in replacement for
16  * <code>StringBuffer</code> in places where the string buffer was being
17  * used by a single thread (as is generally the case). Where possible,
18  * it is recommended that this class be used in preference to
19  * <code>StringBuffer</code> as it will be faster under most implementations.
20  *
21  * <p>The principal operations on a <code>StringBuilder</code> are the
22  * <code>append</code> and <code>insert</code> methods, which are
23  * overloaded so as to accept data of any type. Each effectively
24  * converts a given datum to a string and then appends or inserts the
25  * characters of that string to the string builder. The
26  * <code>append</code> method always adds these characters at the end
27  * of the builder; the <code>insert</code> method adds the characters at
28  * a specified point.
29  * <p>
30  * For example, if <code>z</code> refers to a string builder object
31  * whose current contents are "<code>start</code>", then
32  * the method call <code>z.append("le")</code> would cause the string
33  * builder to contain "<code>startle</code>", whereas
34  * <code>z.insert(4, "le")</code> would alter the string builder to
35  * contain "<code>starlet</code>".
36  * <p>
37  * In general, if sb refers to an instance of a <code>StringBuilder</code>,
38  * then <code>sb.append(x)</code> has the same effect as
39  * <code>sb.insert(sb.length(),&nbsp;x)</code>.
40  *
41  * Every string builder has a capacity. As long as the length of the
42  * character sequence contained in the string builder does not exceed
43  * the capacity, it is not necessary to allocate a new internal
44  * buffer. If the internal buffer overflows, it is automatically made larger.
45  *
46  * <p>Instances of <code>StringBuilder</code> are not safe for
47  * use by multiple threads. If such synchronization is required then it is
48  * recommended that {@link java.lang.StringBuffer} be used.
49  *
50  * @author Michael McCloskey
51  * @version 1.9, 07/16/04
52  * @see java.lang.StringBuffer
53  * @see java.lang.String
54  * @since 1.5
55  */

56 public final class StringBuilder
57     extends AbstractStringBuilder JavaDoc
58     implements java.io.Serializable JavaDoc, CharSequence JavaDoc
59 {
60
61     /** use serialVersionUID for interoperability */
62     static final long serialVersionUID = 4383685877147921099L;
63
64     /**
65      * Constructs a string builder with no characters in it and an
66      * initial capacity of 16 characters.
67      */

68     public StringBuilder() {
69     super(16);
70     }
71
72     /**
73      * Constructs a string builder with no characters in it and an
74      * initial capacity specified by the <code>capacity</code> argument.
75      *
76      * @param capacity the initial capacity.
77      * @throws NegativeArraySizeException if the <code>capacity</code>
78      * argument is less than <code>0</code>.
79      */

80     public StringBuilder(int capacity) {
81     super(capacity);
82     }
83
84     /**
85      * Constructs a string builder initialized to the contents of the
86      * specified string. The initial capacity of the string builder is
87      * <code>16</code> plus the length of the string argument.
88      *
89      * @param str the initial contents of the buffer.
90      * @throws NullPointerException if <code>str</code> is <code>null</code>
91      */

92     public StringBuilder(String JavaDoc str) {
93     super(str.length() + 16);
94     append(str);
95     }
96
97     /**
98      * Constructs a string builder that contains the same characters
99      * as the specified <code>CharSequence</code>. The initial capacity of
100      * the string builder is <code>16</code> plus the length of the
101      * <code>CharSequence</code> argument.
102      *
103      * @param seq the sequence to copy.
104      * @throws NullPointerException if <code>seq</code> is <code>null</code>
105      */

106     public StringBuilder(CharSequence JavaDoc seq) {
107         this(seq.length() + 16);
108         append(seq);
109     }
110
111     /**
112      * @see java.lang.String#valueOf(java.lang.Object)
113      * @see #append(java.lang.String)
114      */

115     public StringBuilder JavaDoc append(Object JavaDoc obj) {
116     return append(String.valueOf(obj));
117     }
118
119     public StringBuilder JavaDoc append(String JavaDoc str) {
120     super.append(str);
121         return this;
122     }
123
124     // Appends the specified string builder to this sequence.
125
private StringBuilder JavaDoc append(StringBuilder JavaDoc sb) {
126     if (sb == null)
127             return append("null");
128     int len = sb.length();
129     int newcount = count + len;
130     if (newcount > value.length)
131         expandCapacity(newcount);
132     sb.getChars(0, len, value, count);
133     count = newcount;
134         return this;
135     }
136
137     /**
138      * Appends the specified <tt>StringBuffer</tt> to this sequence.
139      * <p>
140      * The characters of the <tt>StringBuffer</tt> argument are appended,
141      * in order, to this sequence, increasing the
142      * length of this sequence by the length of the argument.
143      * If <tt>sb</tt> is <tt>null</tt>, then the four characters
144      * <tt>"null"</tt> are appended to this sequence.
145      * <p>
146      * Let <i>n</i> be the length of this character sequence just prior to
147      * execution of the <tt>append</tt> method. Then the character at index
148      * <i>k</i> in the new character sequence is equal to the character at
149      * index <i>k</i> in the old character sequence, if <i>k</i> is less than
150      * <i>n</i>; otherwise, it is equal to the character at index <i>k-n</i>
151      * in the argument <code>sb</code>.
152      *
153      * @param sb the <tt>StringBuffer</tt> to append.
154      * @return a reference to this object.
155      */

156     public StringBuilder JavaDoc append(StringBuffer JavaDoc sb) {
157         super.append(sb);
158         return this;
159     }
160
161     /**
162      * @throws IndexOutOfBoundsException {@inheritDoc}
163      */

164     public StringBuilder JavaDoc append(CharSequence JavaDoc s) {
165         if (s == null)
166             s = "null";
167         if (s instanceof String JavaDoc)
168             return this.append((String JavaDoc)s);
169         if (s instanceof StringBuffer JavaDoc)
170             return this.append((StringBuffer JavaDoc)s);
171         if (s instanceof StringBuilder JavaDoc)
172             return this.append((StringBuilder JavaDoc)s);
173         return this.append(s, 0, s.length());
174     }
175
176     /**
177      * @throws IndexOutOfBoundsException {@inheritDoc}
178      */

179     public StringBuilder JavaDoc append(CharSequence JavaDoc s, int start, int end) {
180         super.append(s, start, end);
181         return this;
182     }
183
184     public StringBuilder JavaDoc append(char str[]) {
185     super.append(str);
186         return this;
187     }
188
189     public StringBuilder JavaDoc append(char str[], int offset, int len) {
190         super.append(str, offset, len);
191         return this;
192     }
193
194     /**
195      * @see java.lang.String#valueOf(boolean)
196      * @see #append(java.lang.String)
197      */

198     public StringBuilder JavaDoc append(boolean b) {
199         super.append(b);
200         return this;
201     }
202
203     public StringBuilder JavaDoc append(char c) {
204         super.append(c);
205         return this;
206     }
207
208     /**
209      * @see java.lang.String#valueOf(int)
210      * @see #append(java.lang.String)
211      */

212     public StringBuilder JavaDoc append(int i) {
213     super.append(i);
214         return this;
215     }
216
217     /**
218      * @see java.lang.String#valueOf(long)
219      * @see #append(java.lang.String)
220      */

221     public StringBuilder JavaDoc append(long lng) {
222         super.append(lng);
223         return this;
224     }
225
226     /**
227      * @see java.lang.String#valueOf(float)
228      * @see #append(java.lang.String)
229      */

230     public StringBuilder JavaDoc append(float f) {
231     super.append(f);
232         return this;
233     }
234
235     /**
236      * @see java.lang.String#valueOf(double)
237      * @see #append(java.lang.String)
238      */

239     public StringBuilder JavaDoc append(double d) {
240     super.append(d);
241         return this;
242     }
243
244     /**
245      * @since 1.5
246      */

247     public StringBuilder JavaDoc appendCodePoint(int codePoint) {
248     super.appendCodePoint(codePoint);
249     return this;
250     }
251
252     /**
253      * @throws StringIndexOutOfBoundsException {@inheritDoc}
254      */

255     public StringBuilder JavaDoc delete(int start, int end) {
256     super.delete(start, end);
257         return this;
258     }
259
260     /**
261      * @throws StringIndexOutOfBoundsException {@inheritDoc}
262      */

263     public StringBuilder JavaDoc deleteCharAt(int index) {
264         super.deleteCharAt(index);
265         return this;
266     }
267
268     /**
269      * @throws StringIndexOutOfBoundsException {@inheritDoc}
270      */

271     public StringBuilder JavaDoc replace(int start, int end, String JavaDoc str) {
272         super.replace(start, end, str);
273         return this;
274     }
275
276     /**
277      * @throws StringIndexOutOfBoundsException {@inheritDoc}
278      */

279     public StringBuilder JavaDoc insert(int index, char str[], int offset,
280                                 int len)
281     {
282         super.insert(index, str, offset, len);
283     return this;
284     }
285
286     /**
287      * @throws StringIndexOutOfBoundsException {@inheritDoc}
288      * @see java.lang.String#valueOf(java.lang.Object)
289      * @see #insert(int, java.lang.String)
290      * @see #length()
291      */

292     public StringBuilder JavaDoc insert(int offset, Object JavaDoc obj) {
293     return insert(offset, String.valueOf(obj));
294     }
295
296     /**
297      * @throws StringIndexOutOfBoundsException {@inheritDoc}
298      * @see #length()
299      */

300     public StringBuilder JavaDoc insert(int offset, String JavaDoc str) {
301     super.insert(offset, str);
302         return this;
303     }
304
305     /**
306      * @throws StringIndexOutOfBoundsException {@inheritDoc}
307      */

308     public StringBuilder JavaDoc insert(int offset, char str[]) {
309     super.insert(offset, str);
310         return this;
311     }
312
313     /**
314      * @throws IndexOutOfBoundsException {@inheritDoc}
315      */

316     public StringBuilder JavaDoc insert(int dstOffset, CharSequence JavaDoc s) {
317         if (s == null)
318             s = "null";
319         if (s instanceof String JavaDoc)
320             return this.insert(dstOffset, (String JavaDoc)s);
321         return this.insert(dstOffset, s, 0, s.length());
322     }
323
324     /**
325      * @throws IndexOutOfBoundsException {@inheritDoc}
326      */

327     public StringBuilder JavaDoc insert(int dstOffset, CharSequence JavaDoc s,
328                 int start, int end)
329     {
330         super.insert(dstOffset, s, start, end);
331         return this;
332     }
333
334     /**
335      * @throws StringIndexOutOfBoundsException {@inheritDoc}
336      * @see java.lang.String#valueOf(boolean)
337      * @see #insert(int, java.lang.String)
338      * @see #length()
339      */

340     public StringBuilder JavaDoc insert(int offset, boolean b) {
341     super.insert(offset, b);
342         return this;
343     }
344
345     /**
346      * @throws IndexOutOfBoundsException {@inheritDoc}
347      * @see #length()
348      */

349     public StringBuilder JavaDoc insert(int offset, char c) {
350         super.insert(offset, c);
351     return this;
352     }
353
354     /**
355      * @throws StringIndexOutOfBoundsException {@inheritDoc}
356      * @see java.lang.String#valueOf(int)
357      * @see #insert(int, java.lang.String)
358      * @see #length()
359      */

360     public StringBuilder JavaDoc insert(int offset, int i) {
361     return insert(offset, String.valueOf(i));
362     }
363
364     /**
365      * @throws StringIndexOutOfBoundsException {@inheritDoc}
366      * @see java.lang.String#valueOf(long)
367      * @see #insert(int, java.lang.String)
368      * @see #length()
369      */

370     public StringBuilder JavaDoc insert(int offset, long l) {
371     return insert(offset, String.valueOf(l));
372     }
373
374     /**
375      * @throws StringIndexOutOfBoundsException {@inheritDoc}
376      * @see java.lang.String#valueOf(float)
377      * @see #insert(int, java.lang.String)
378      * @see #length()
379      */

380     public StringBuilder JavaDoc insert(int offset, float f) {
381     return insert(offset, String.valueOf(f));
382     }
383
384     /**
385      * @throws StringIndexOutOfBoundsException {@inheritDoc}
386      * @see java.lang.String#valueOf(double)
387      * @see #insert(int, java.lang.String)
388      * @see #length()
389      */

390     public StringBuilder JavaDoc insert(int offset, double d) {
391     return insert(offset, String.valueOf(d));
392     }
393
394     /**
395      * @throws NullPointerException {@inheritDoc}
396      */

397     public int indexOf(String JavaDoc str) {
398     return indexOf(str, 0);
399     }
400
401     /**
402      * @throws NullPointerException {@inheritDoc}
403      */

404     public int indexOf(String JavaDoc str, int fromIndex) {
405         return String.indexOf(value, 0, count,
406                               str.toCharArray(), 0, str.length(), fromIndex);
407     }
408
409     /**
410      * @throws NullPointerException {@inheritDoc}
411      */

412     public int lastIndexOf(String JavaDoc str) {
413         return lastIndexOf(str, count);
414     }
415
416     /**
417      * @throws NullPointerException {@inheritDoc}
418      */

419     public int lastIndexOf(String JavaDoc str, int fromIndex) {
420         return String.lastIndexOf(value, 0, count,
421                               str.toCharArray(), 0, str.length(), fromIndex);
422     }
423
424     public StringBuilder JavaDoc reverse() {
425     super.reverse();
426     return this;
427     }
428
429     public String JavaDoc toString() {
430         // Create a copy, don't share the array
431
return new String JavaDoc(value, 0, count);
432     }
433
434     /**
435      * Save the state of the <tt>StringBuilder</tt> instance to a stream
436      * (that is, serialize it).
437      *
438      * @serialData the number of characters currently stored in the string
439      * builder (<tt>int</tt>), followed by the characters in the
440      * string builder (<tt>char[]</tt>). The length of the
441      * <tt>char</tt> array may be greater than the number of
442      * characters currently stored in the string builder, in which
443      * case extra characters are ignored.
444      */

445     private void writeObject(java.io.ObjectOutputStream JavaDoc s)
446         throws java.io.IOException JavaDoc {
447         s.defaultWriteObject();
448         s.writeInt(count);
449         s.writeObject(value);
450     }
451
452     /**
453      * readObject is called to restore the state of the StringBuffer from
454      * a stream.
455      */

456     private void readObject(java.io.ObjectInputStream JavaDoc s)
457         throws java.io.IOException JavaDoc, ClassNotFoundException JavaDoc {
458         s.defaultReadObject();
459         count = s.readInt();
460         value = (char[]) s.readObject();
461     }
462
463 }
464
Popular Tags