37 * are synchronized where necessary so that all the operations on any |
37 * are synchronized where necessary so that all the operations on any |
38 * particular instance behave as if they occur in some serial order |
38 * particular instance behave as if they occur in some serial order |
39 * that is consistent with the order of the method calls made by each of |
39 * that is consistent with the order of the method calls made by each of |
40 * the individual threads involved. |
40 * the individual threads involved. |
41 * <p> |
41 * <p> |
42 * The principal operations on a <code>StringBuffer</code> are the |
42 * The principal operations on a {@code StringBuffer} are the |
43 * <code>append</code> and <code>insert</code> methods, which are |
43 * {@code append} and {@code insert} methods, which are |
44 * overloaded so as to accept data of any type. Each effectively |
44 * overloaded so as to accept data of any type. Each effectively |
45 * converts a given datum to a string and then appends or inserts the |
45 * converts a given datum to a string and then appends or inserts the |
46 * characters of that string to the string buffer. The |
46 * characters of that string to the string buffer. The |
47 * <code>append</code> method always adds these characters at the end |
47 * {@code append} method always adds these characters at the end |
48 * of the buffer; the <code>insert</code> method adds the characters at |
48 * of the buffer; the {@code insert} method adds the characters at |
49 * a specified point. |
49 * a specified point. |
50 * <p> |
50 * <p> |
51 * For example, if <code>z</code> refers to a string buffer object |
51 * For example, if {@code z} refers to a string buffer object |
52 * whose current contents are "<code>start</code>", then |
52 * whose current contents are {@code "start"}, then |
53 * the method call <code>z.append("le")</code> would cause the string |
53 * the method call {@code z.append("le")} would cause the string |
54 * buffer to contain "<code>startle</code>", whereas |
54 * buffer to contain {@code "startle"}, whereas |
55 * <code>z.insert(4, "le")</code> would alter the string buffer to |
55 * {@code z.insert(4, "le")} would alter the string buffer to |
56 * contain "<code>starlet</code>". |
56 * contain {@code "starlet"}. |
57 * <p> |
57 * <p> |
58 * In general, if sb refers to an instance of a <code>StringBuffer</code>, |
58 * In general, if sb refers to an instance of a {@code StringBuffer}, |
59 * then <code>sb.append(x)</code> has the same effect as |
59 * then {@code sb.append(x)} has the same effect as |
60 * <code>sb.insert(sb.length(), x)</code>. |
60 * {@code sb.insert(sb.length(), x)}. |
61 * <p> |
61 * <p> |
62 * Whenever an operation occurs involving a source sequence (such as |
62 * Whenever an operation occurs involving a source sequence (such as |
63 * appending or inserting from a source sequence) this class synchronizes |
63 * appending or inserting from a source sequence), this class synchronizes |
64 * only on the string buffer performing the operation, not on the source. |
64 * only on the string buffer performing the operation, not on the source. |
|
65 * Note that while {@code StringBuffer} is designed to be safe to use |
|
66 * concurrently from multiple threads, if the constructor or the |
|
67 * {@code append} or {@code insert} operation is passed a source sequence |
|
68 * that is shared across threads, the calling code must ensure |
|
69 * that the operation has a consistent and unchanging view of the source |
|
70 * sequence for the duration of the operation. |
|
71 * This could be satisfied by the caller holding a lock during the |
|
72 * operation's call, by using an immutable source sequence, or by not |
|
73 * sharing the source sequence across threads. |
65 * <p> |
74 * <p> |
66 * Every string buffer has a capacity. As long as the length of the |
75 * Every string buffer has a capacity. As long as the length of the |
67 * character sequence contained in the string buffer does not exceed |
76 * character sequence contained in the string buffer does not exceed |
68 * the capacity, it is not necessary to allocate a new internal |
77 * the capacity, it is not necessary to allocate a new internal |
69 * buffer array. If the internal buffer overflows, it is |
78 * buffer array. If the internal buffer overflows, it is |
99 /** |
108 /** |
100 * Constructs a string buffer with no characters in it and |
109 * Constructs a string buffer with no characters in it and |
101 * the specified initial capacity. |
110 * the specified initial capacity. |
102 * |
111 * |
103 * @param capacity the initial capacity. |
112 * @param capacity the initial capacity. |
104 * @exception NegativeArraySizeException if the <code>capacity</code> |
113 * @exception NegativeArraySizeException if the {@code capacity} |
105 * argument is less than <code>0</code>. |
114 * argument is less than {@code 0}. |
106 */ |
115 */ |
107 public StringBuffer(int capacity) { |
116 public StringBuffer(int capacity) { |
108 super(capacity); |
117 super(capacity); |
109 } |
118 } |
110 |
119 |
111 /** |
120 /** |
112 * Constructs a string buffer initialized to the contents of the |
121 * Constructs a string buffer initialized to the contents of the |
113 * specified string. The initial capacity of the string buffer is |
122 * specified string. The initial capacity of the string buffer is |
114 * <code>16</code> plus the length of the string argument. |
123 * {@code 16} plus the length of the string argument. |
115 * |
124 * |
116 * @param str the initial contents of the buffer. |
125 * @param str the initial contents of the buffer. |
117 * @exception NullPointerException if <code>str</code> is <code>null</code> |
126 * @exception NullPointerException if {@code str} is {@code null} |
118 */ |
127 */ |
119 public StringBuffer(String str) { |
128 public StringBuffer(String str) { |
120 super(str.length() + 16); |
129 super(str.length() + 16); |
121 append(str); |
130 append(str); |
122 } |
131 } |
123 |
132 |
124 /** |
133 /** |
125 * Constructs a string buffer that contains the same characters |
134 * Constructs a string buffer that contains the same characters |
126 * as the specified <code>CharSequence</code>. The initial capacity of |
135 * as the specified {@code CharSequence}. The initial capacity of |
127 * the string buffer is <code>16</code> plus the length of the |
136 * the string buffer is {@code 16} plus the length of the |
128 * <code>CharSequence</code> argument. |
137 * {@code CharSequence} argument. |
129 * <p> |
138 * <p> |
130 * If the length of the specified <code>CharSequence</code> is |
139 * If the length of the specified {@code CharSequence} is |
131 * less than or equal to zero, then an empty buffer of capacity |
140 * less than or equal to zero, then an empty buffer of capacity |
132 * <code>16</code> is returned. |
141 * {@code 16} is returned. |
133 * |
142 * |
134 * @param seq the sequence to copy. |
143 * @param seq the sequence to copy. |
135 * @exception NullPointerException if <code>seq</code> is <code>null</code> |
144 * @exception NullPointerException if {@code seq} is {@code null} |
136 * @since 1.5 |
145 * @since 1.5 |
137 */ |
146 */ |
138 public StringBuffer(CharSequence seq) { |
147 public StringBuffer(CharSequence seq) { |
139 this(seq.length() + 16); |
148 this(seq.length() + 16); |
140 append(seq); |
149 append(seq); |
251 * contained in the <tt>StringBuffer</tt> just prior to execution of the |
260 * contained in the <tt>StringBuffer</tt> just prior to execution of the |
252 * <tt>append</tt> method. Then the character at index <i>k</i> in |
261 * <tt>append</tt> method. Then the character at index <i>k</i> in |
253 * the new character sequence is equal to the character at index <i>k</i> |
262 * the new character sequence is equal to the character at index <i>k</i> |
254 * in the old character sequence, if <i>k</i> is less than <i>n</i>; |
263 * in the old character sequence, if <i>k</i> is less than <i>n</i>; |
255 * otherwise, it is equal to the character at index <i>k-n</i> in the |
264 * otherwise, it is equal to the character at index <i>k-n</i> in the |
256 * argument <code>sb</code>. |
265 * argument {@code sb}. |
257 * <p> |
266 * <p> |
258 * This method synchronizes on <code>this</code> (the destination) |
267 * This method synchronizes on {@code this}, the destination |
259 * object but does not synchronize on the source (<code>sb</code>). |
268 * object, but does not synchronize on the source ({@code sb}). |
260 * |
269 * |
261 * @param sb the <tt>StringBuffer</tt> to append. |
270 * @param sb the <tt>StringBuffer</tt> to append. |
262 * @return a reference to this object. |
271 * @return a reference to this object. |
263 * @since 1.4 |
272 * @since 1.4 |
264 */ |
273 */ |
267 return this; |
276 return this; |
268 } |
277 } |
269 |
278 |
270 |
279 |
271 /** |
280 /** |
272 * Appends the specified <code>CharSequence</code> to this |
281 * Appends the specified {@code CharSequence} to this |
273 * sequence. |
282 * sequence. |
274 * <p> |
283 * <p> |
275 * The characters of the <code>CharSequence</code> argument are appended, |
284 * The characters of the {@code CharSequence} argument are appended, |
276 * in order, increasing the length of this sequence by the length of the |
285 * in order, increasing the length of this sequence by the length of the |
277 * argument. |
286 * argument. |
278 * |
287 * |
279 * <p>The result of this method is exactly the same as if it were an |
288 * <p>The result of this method is exactly the same as if it were an |
280 * invocation of this.append(s, 0, s.length()); |
289 * invocation of this.append(s, 0, s.length()); |
281 * |
290 * |
282 * <p>This method synchronizes on this (the destination) |
291 * <p>This method synchronizes on {@code this}, the destination |
283 * object but does not synchronize on the source (<code>s</code>). |
292 * object, but does not synchronize on the source ({@code s}). |
284 * |
293 * |
285 * <p>If <code>s</code> is <code>null</code>, then the four characters |
294 * <p>If {@code s} is {@code null}, then the four characters |
286 * <code>"null"</code> are appended. |
295 * {@code "null"} are appended. |
287 * |
296 * |
288 * @param s the <code>CharSequence</code> to append. |
297 * @param s the {@code CharSequence} to append. |
289 * @return a reference to this object. |
298 * @return a reference to this object. |
290 * @since 1.5 |
299 * @since 1.5 |
291 */ |
300 */ |
292 public StringBuffer append(CharSequence s) { |
301 public StringBuffer append(CharSequence s) { |
293 // Note, synchronization achieved via other invocations |
302 // Note, synchronization achieved via other invocations |