Find Usages Diff Raw Download HTML Widget
Start line:  
End line:  

Snippet Preview

Snippet HTML Code

Stack Overflow Questions 
1
  /*
2
   * Copyright (c) 2003, 2008, 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;


A mutable sequence of characters. This class provides an API compatible with StringBuffer, but with no guarantee of synchronization. This class is designed for use as a drop-in replacement for StringBuffer in places where the string buffer was being used by a single thread (as is generally the case). Where possible, it is recommended that this class be used in preference to StringBuffer as it will be faster under most implementations.

The principal operations on a StringBuilder are the append and insert methods, which are overloaded so as to accept data of any type. Each effectively converts a given datum to a string and then appends or inserts the characters of that string to the string builder. The append method always adds these characters at the end of the builder; the insert method adds the characters at a specified point.

For example, if z refers to a string builder object whose current contents are "start", then the method call z.append("le") would cause the string builder to contain "startle", whereas z.insert(4, "le") would alter the string builder to contain "starlet".

In general, if sb refers to an instance of a StringBuilder, then sb.append(x) has the same effect as sb.insert(sb.length(), x). Every string builder has a capacity. As long as the length of the character sequence contained in the string builder does not exceed the capacity, it is not necessary to allocate a new internal buffer. If the internal buffer overflows, it is automatically made larger.

Instances of StringBuilder are not safe for use by multiple threads. If such synchronization is required then it is recommended that StringBuffer be used.

Author(s):
Michael McCloskey
Since:
1.5
See also:
StringBuffer
String
71
 
72
 public final class StringBuilder
73
     extends AbstractStringBuilder
74
     implements java.io.Serializable, CharSequence
75
 {

    
use serialVersionUID for interoperability
77
 
78
     static final long serialVersionUID = 4383685877147921099L;

    
Constructs a string builder with no characters in it and an initial capacity of 16 characters. 
83
 
84
     public StringBuilder() {
85
         super(16);
86
     }

    
Constructs a string builder with no characters in it and an initial capacity specified by the capacity argument.

Parameters:
capacity the initial capacity.
Throws:
NegativeArraySizeException if the capacity argument is less than 0.
95
 
96
     public StringBuilder(int capacity) {
97
         super(capacity);
98
     }

    
Constructs a string builder initialized to the contents of the specified string. The initial capacity of the string builder is 16 plus the length of the string argument.

Parameters:
str the initial contents of the buffer.
Throws:
NullPointerException if str is null
108
    public StringBuilder(String str) {
109
        super(str.length() + 16);
110
        append(str);
111
    }

    
Constructs a string builder that contains the same characters as the specified CharSequence. The initial capacity of the string builder is 16 plus the length of the CharSequence argument.

Parameters:
seq the sequence to copy.
Throws:
NullPointerException if seq is null
122
    public StringBuilder(CharSequence seq) {
123
        this(seq.length() + 16);
124
        append(seq);
125
    }
127
    public StringBuilder append(Object obj) {
128
        return append(String.valueOf(obj));
129
    }
131
    public StringBuilder append(String str) {
132
        super.append(str);
133
        return this;
134
    }
136
    // Appends the specified string builder to this sequence.
137
    private StringBuilder append(StringBuilder sb) {
138
        if (sb == null)
139
            return append("null");
140
        int len = sb.length();
141
        int newcount =  + len;
142
        if (newcount > .)
143
            expandCapacity(newcount);
144
        sb.getChars(0, len, , );
145
         = newcount;
146
        return this;
147
    }

    
Appends the specified StringBuffer to this sequence.

The characters of the StringBuffer argument are appended, in order, to this sequence, increasing the length of this sequence by the length of the argument. If sb is null, then the four characters "null" are appended to this sequence.

Let n be the length of this character sequence just prior to execution of the append method. Then the character at index k in the new character sequence is equal to the character at index k in the old character sequence, if k is less than n; otherwise, it is equal to the character at index k-n in the argument sb.

Parameters:
sb the StringBuffer to append.
Returns:
a reference to this object.
168
    public StringBuilder append(StringBuffer sb) {
169
        super.append(sb);
170
        return this;
171
    }

    
175
    public StringBuilder append(CharSequence s) {
176
        if (s == null)
177
            s = "null";
178
        if (s instanceof String)
179
            return this.append((String)s);
180
        if (s instanceof StringBuffer)
181
            return this.append((StringBuffer)s);
182
        if (s instanceof StringBuilder)
183
            return this.append((StringBuilder)s);
184
        return this.append(s, 0, s.length());
185
    }

    

Throws:
IndexOutOfBoundsException
190
    public StringBuilder append(CharSequence s, int start, int end) {
191
        super.append(s, start, end);
192
        return this;
193
    }
195
    public StringBuilder append(char[] str) {
196
        super.append(str);
197
        return this;
198
    }

    

Throws:
IndexOutOfBoundsException
203
    public StringBuilder append(char[] str, int offset, int len) {
204
        super.append(str, offset, len);
205
        return this;
206
    }
208
    public StringBuilder append(boolean b) {
209
        super.append(b);
210
        return this;
211
    }
213
    public StringBuilder append(char c) {
214
        super.append(c);
215
        return this;
216
    }
218
    public StringBuilder append(int i) {
219
        super.append(i);
220
        return this;
221
    }
223
    public StringBuilder append(long lng) {
224
        super.append(lng);
225
        return this;
226
    }
228
    public StringBuilder append(float f) {
229
        super.append(f);
230
        return this;
231
    }
233
    public StringBuilder append(double d) {
234
        super.append(d);
235
        return this;
236
    }

    

Since:
1.5
241
    public StringBuilder appendCodePoint(int codePoint) {
242
        super.appendCodePoint(codePoint);
243
        return this;
244
    }

    

Throws:
StringIndexOutOfBoundsException
249
    public StringBuilder delete(int start, int end) {
250
        super.delete(start, end);
251
        return this;
252
    }

    

Throws:
StringIndexOutOfBoundsException
257
    public StringBuilder deleteCharAt(int index) {
258
        super.deleteCharAt(index);
259
        return this;
260
    }

    

Throws:
StringIndexOutOfBoundsException
265
    public StringBuilder replace(int start, int end, String str) {
266
        super.replace(start, end, str);
267
        return this;
268
    }

    

Throws:
StringIndexOutOfBoundsException
273
    public StringBuilder insert(int index, char[] str, int offset,
274
                                int len)
275
    {
276
        super.insert(index, str, offset, len);
277
        return this;
278
    }

    

Throws:
StringIndexOutOfBoundsException
283
    public StringBuilder insert(int offset, Object obj) {
284
        return insert(offset, String.valueOf(obj));
285
    }

    

Throws:
StringIndexOutOfBoundsException
290
    public StringBuilder insert(int offset, String str) {
291
        super.insert(offset, str);
292
        return this;
293
    }

    

Throws:
StringIndexOutOfBoundsException
298
    public StringBuilder insert(int offset, char[] str) {
299
        super.insert(offset, str);
300
        return this;
301
    }

    

Throws:
IndexOutOfBoundsException
306
    public StringBuilder insert(int dstOffset, CharSequence s) {
307
        if (s == null)
308
            s = "null";
309
        if (s instanceof String)
310
            return this.insert(dstOffset, (String)s);
311
        return this.insert(dstOffset, s, 0, s.length());
312
    }

    

Throws:
IndexOutOfBoundsException
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
    }

    

Throws:
StringIndexOutOfBoundsException
327
    public StringBuilder insert(int offset, boolean b) {
328
        super.insert(offset, b);
329
        return this;
330
    }

    

Throws:
IndexOutOfBoundsException
335
    public StringBuilder insert(int offset, char c) {
336
        super.insert(offset, c);
337
        return this;
338
    }

    

Throws:
StringIndexOutOfBoundsException
343
    public StringBuilder insert(int offset, int i) {
344
        return insert(offset, String.valueOf(i));
345
    }

    

Throws:
StringIndexOutOfBoundsException
350
    public StringBuilder insert(int offset, long l) {
351
        return insert(offset, String.valueOf(l));
352
    }

    

Throws:
StringIndexOutOfBoundsException
357
    public StringBuilder insert(int offset, float f) {
358
        return insert(offset, String.valueOf(f));
359
    }

    

Throws:
StringIndexOutOfBoundsException
364
    public StringBuilder insert(int offset, double d) {
365
        return insert(offset, String.valueOf(d));
366
    }

    

Throws:
NullPointerException
371
    public int indexOf(String str) {
372
        return indexOf(str, 0);
373
    }

    

Throws:
NullPointerException
378
    public int indexOf(String str, int fromIndex) {
379
        return String.indexOf(, 0, ,
380
                              str.toCharArray(), 0, str.length(), fromIndex);
381
    }

    

Throws:
NullPointerException
386
    public int lastIndexOf(String str) {
387
        return lastIndexOf(str, );
388
    }

    

Throws:
NullPointerException
393
    public int lastIndexOf(String str, int fromIndex) {
394
        return String.lastIndexOf(, 0, ,
395
                              str.toCharArray(), 0, str.length(), fromIndex);
396
    }
398
    public StringBuilder reverse() {
399
        super.reverse();
400
        return this;
401
    }
403
    public String toString() {
404
        // Create a copy, don't share the array
405
        return new String(, 0, );
406
    }

    
Save the state of the StringBuilder instance to a stream (that is, serialize it).

SerialData:
the number of characters currently stored in the string builder (int), followed by the characters in the string builder (char[]). The length of the char array may be greater than the number of characters currently stored in the string builder, in which case extra characters are ignored.
419
    private void writeObject(java.io.ObjectOutputStream s)
420
        throws java.io.IOException {
421
        s.defaultWriteObject();
422
        s.writeInt();
423
        s.writeObject();
424
    }

    
readObject is called to restore the state of the StringBuffer from a stream. 
430
    private void readObject(java.io.ObjectInputStream s)
431
        throws java.io.IOException, ClassNotFoundException {
432
        s.defaultReadObject();
433
         = s.readInt();
434
         = (char[]) s.readObject();
435
    }
New to GrepCode? Check out our FAQ X