1 /*
   2  * Copyright (c) 1996, 2016, 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.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 {@code StringWriter} has no effect. The methods in this class
  34  * can be called after the stream has been closed without generating an
  35  * {@code IOException}.
  36  *
  37  * @author      Mark Reinhold
  38  * @since       1.1
  39  */
  40 
  41 public 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 {@code char} values that will fit into this buffer
  60      *        before it is automatically expanded
  61      *
  62      * @throws IllegalArgumentException
  63      *         If {@code initialSize} 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      * @throws  IndexOutOfBoundsException
  88      *          If {@code off} is negative, or {@code len} is negative,
  89      *          or {@code off + len} is negative or greater than the length
  90      *          of the given array
  91      */
  92     public void write(char cbuf[], int off, int len) {
  93         if ((off < 0) || (off > cbuf.length) || (len < 0) ||
  94             ((off + len) > cbuf.length) || ((off + len) < 0)) {
  95             throw new IndexOutOfBoundsException();
  96         } else if (len == 0) {
  97             return;
  98         }
  99         buf.append(cbuf, off, len);
 100     }
 101 
 102     /**
 103      * Write a string.
 104      */
 105     public void write(String str) {
 106         buf.append(str);
 107     }
 108 
 109     /**
 110      * Write a portion of a string.
 111      *
 112      * @param  str  String to be written
 113      * @param  off  Offset from which to start writing characters
 114      * @param  len  Number of characters to write
 115      *
 116      * @throws  IndexOutOfBoundsException
 117      *          If {@code off} is negative, or {@code len} is negative,
 118      *          or {@code off + len} is negative or greater than the length
 119      *          of the given string
 120      */
 121     public void write(String str, int off, int len)  {
 122         buf.append(str, off, off + len);
 123     }
 124 
 125     /**
 126      * Appends the specified character sequence to this writer.
 127      *
 128      * <p> An invocation of this method of the form {@code out.append(csq)}
 129      * behaves in exactly the same way as the invocation
 130      *
 131      * <pre>
 132      *     out.write(csq.toString()) </pre>
 133      *
 134      * <p> Depending on the specification of {@code toString} for the
 135      * character sequence {@code csq}, the entire sequence may not be
 136      * appended. For instance, invoking the {@code toString} method of a
 137      * character buffer will return a subsequence whose content depends upon
 138      * the buffer's position and limit.
 139      *
 140      * @param  csq
 141      *         The character sequence to append.  If {@code csq} is
 142      *         {@code null}, then the four characters "{@code null}" are
 143      *         appended to this writer.
 144      *
 145      * @return  This writer
 146      *
 147      * @since  1.5
 148      */
 149     public StringWriter append(CharSequence csq) {
 150         if (csq == null)
 151             write("null");
 152         else
 153             write(csq.toString());
 154         return this;
 155     }
 156 
 157     /**
 158      * Appends a subsequence of the specified character sequence to this writer.
 159      *
 160      * <p> An invocation of this method of the form
 161      * {@code out.append(csq, start, end)} when {@code csq}
 162      * is not {@code null}, behaves in
 163      * exactly the same way as the invocation
 164      *
 165      * <pre>{@code
 166      *     out.write(csq.subSequence(start, end).toString())
 167      * }</pre>
 168      *
 169      * @param  csq
 170      *         The character sequence from which a subsequence will be
 171      *         appended.  If {@code csq} is {@code null}, then characters
 172      *         will be appended as if {@code csq} contained the four
 173      *         characters "{@code null}".
 174      *
 175      * @param  start
 176      *         The index of the first character in the subsequence
 177      *
 178      * @param  end
 179      *         The index of the character following the last character in the
 180      *         subsequence
 181      *
 182      * @return  This writer
 183      *
 184      * @throws  IndexOutOfBoundsException
 185      *          If {@code start} or {@code end} are negative, {@code start}
 186      *          is greater than {@code end}, or {@code end} is greater than
 187      *          {@code csq.length()}
 188      *
 189      * @since  1.5
 190      */
 191     public StringWriter append(CharSequence csq, int start, int end) {
 192         CharSequence cs = (csq == null ? "null" : csq);
 193         write(cs.subSequence(start, end).toString());
 194         return this;
 195     }
 196 
 197     /**
 198      * Appends the specified character to this writer.
 199      *
 200      * <p> An invocation of this method of the form {@code out.append(c)}
 201      * behaves in exactly the same way as the invocation
 202      *
 203      * <pre>
 204      *     out.write(c) </pre>
 205      *
 206      * @param  c
 207      *         The 16-bit character to append
 208      *
 209      * @return  This writer
 210      *
 211      * @since 1.5
 212      */
 213     public StringWriter append(char c) {
 214         write(c);
 215         return this;
 216     }
 217 
 218     /**
 219      * Return the buffer's current value as a string.
 220      */
 221     public String toString() {
 222         return buf.toString();
 223     }
 224 
 225     /**
 226      * Return the string buffer itself.
 227      *
 228      * @return StringBuffer holding the current buffer value.
 229      */
 230     public StringBuffer getBuffer() {
 231         return buf;
 232     }
 233 
 234     /**
 235      * Flush the stream.
 236      */
 237     public void flush() {
 238     }
 239 
 240     /**
 241      * Closing a {@code StringWriter} has no effect. The methods in this
 242      * class can be called after the stream has been closed without generating
 243      * an {@code IOException}.
 244      */
 245     public void close() throws IOException {
 246     }
 247 
 248 }