1/* 2 * Copyright (c) 1996, 2004, 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 26package java.io; 27 28 29/** 30 * A character stream that collects its output in a string buffer, which can 31 * then be used to construct a string. 32 * <p> 33 * Closing a <tt>StringWriter</tt> has no effect. The methods in this class 34 * can be called after the stream has been closed without generating an 35 * <tt>IOException</tt>. 36 * 37 * @author Mark Reinhold 38 * @since JDK1.1 39 */ 40 41public class StringWriter extends Writer { 42 43 private StringBuffer buf; 44 45 /** 46 * Create a new string writer using the default initial string-buffer 47 * size. 48 */ 49 public StringWriter() { 50 buf = new StringBuffer(); 51 lock = buf; 52 } 53 54 /** 55 * Create a new string writer using the specified initial string-buffer 56 * size. 57 * 58 * @param initialSize 59 * The number of <tt>char</tt> values that will fit into this buffer 60 * before it is automatically expanded 61 * 62 * @throws IllegalArgumentException 63 * If <tt>initialSize</tt> is negative 64 */ 65 public StringWriter(int initialSize) { 66 if (initialSize < 0) { 67 throw new IllegalArgumentException("Negative buffer size"); 68 } 69 buf = new StringBuffer(initialSize); 70 lock = buf; 71 } 72 73 /** 74 * Write a single character. 75 */ 76 public void write(int c) { 77 buf.append((char) c); 78 } 79 80 /** 81 * Write a portion of an array of characters. 82 * 83 * @param cbuf Array of characters 84 * @param off Offset from which to start writing characters 85 * @param len Number of characters to write 86 */ 87 public void write(char cbuf[], int off, int len) { 88 if ((off < 0) || (off > cbuf.length) || (len < 0) || 89 ((off + len) > cbuf.length) || ((off + len) < 0)) { 90 throw new IndexOutOfBoundsException(); 91 } else if (len == 0) { 92 return; 93 } 94 buf.append(cbuf, off, len); 95 } 96 97 /** 98 * Write a string. 99 */ 100 public void write(String str) { 101 buf.append(str); 102 } 103 104 /** 105 * Write a portion of a string. 106 * 107 * @param str String to be written 108 * @param off Offset from which to start writing characters 109 * @param len Number of characters to write 110 */ 111 public void write(String str, int off, int len) { 112 buf.append(str.substring(off, off + len)); 113 } 114 115 /** 116 * Appends the specified character sequence to this writer. 117 * 118 * <p> An invocation of this method of the form <tt>out.append(csq)</tt> 119 * behaves in exactly the same way as the invocation 120 * 121 * <pre> 122 * out.write(csq.toString()) </pre> 123 * 124 * <p> Depending on the specification of <tt>toString</tt> for the 125 * character sequence <tt>csq</tt>, the entire sequence may not be 126 * appended. For instance, invoking the <tt>toString</tt> method of a 127 * character buffer will return a subsequence whose content depends upon 128 * the buffer's position and limit. 129 * 130 * @param csq 131 * The character sequence to append. If <tt>csq</tt> is 132 * <tt>null</tt>, then the four characters <tt>"null"</tt> are 133 * appended to this writer. 134 * 135 * @return This writer 136 * 137 * @since 1.5 138 */ 139 public StringWriter append(CharSequence csq) { 140 if (csq == null) 141 write("null"); 142 else 143 write(csq.toString()); 144 return this; 145 } 146 147 /** 148 * Appends a subsequence of the specified character sequence to this writer. 149 * 150 * <p> An invocation of this method of the form <tt>out.append(csq, start, 151 * end)</tt> when <tt>csq</tt> is not <tt>null</tt>, behaves in 152 * exactly the same way as the invocation 153 * 154 * <pre> 155 * out.write(csq.subSequence(start, end).toString()) </pre> 156 * 157 * @param csq 158 * The character sequence from which a subsequence will be 159 * appended. If <tt>csq</tt> is <tt>null</tt>, then characters 160 * will be appended as if <tt>csq</tt> contained the four 161 * characters <tt>"null"</tt>. 162 * 163 * @param start 164 * The index of the first character in the subsequence 165 * 166 * @param end 167 * The index of the character following the last character in the 168 * subsequence 169 * 170 * @return This writer 171 * 172 * @throws IndexOutOfBoundsException 173 * If <tt>start</tt> or <tt>end</tt> are negative, <tt>start</tt> 174 * is greater than <tt>end</tt>, or <tt>end</tt> is greater than 175 * <tt>csq.length()</tt> 176 * 177 * @since 1.5 178 */ 179 public StringWriter append(CharSequence csq, int start, int end) { 180 CharSequence cs = (csq == null ? "null" : csq); 181 write(cs.subSequence(start, end).toString()); 182 return this; 183 } 184 185 /** 186 * Appends the specified character to this writer. 187 * 188 * <p> An invocation of this method of the form <tt>out.append(c)</tt> 189 * behaves in exactly the same way as the invocation 190 * 191 * <pre> 192 * out.write(c) </pre> 193 * 194 * @param c 195 * The 16-bit character to append 196 * 197 * @return This writer 198 * 199 * @since 1.5 200 */ 201 public StringWriter append(char c) { 202 write(c); 203 return this; 204 } 205 206 /** 207 * Return the buffer's current value as a string. 208 */ 209 public String toString() { 210 return buf.toString(); 211 } 212 213 /** 214 * Return the string buffer itself. 215 * 216 * @return StringBuffer holding the current buffer value. 217 */ 218 public StringBuffer getBuffer() { 219 return buf; 220 } 221 222 /** 223 * Flush the stream. 224 */ 225 public void flush() { 226 } 227 228 /** 229 * Closing a <tt>StringWriter</tt> has no effect. The methods in this 230 * class can be called after the stream has been closed without generating 231 * an <tt>IOException</tt>. 232 */ 233 public void close() throws IOException { 234 } 235 236} 237