libcore/luni/src/main/java/java/io/StringWriter.java

   1 /*
   2  *  Licensed to the Apache Software Foundation (ASF) under one or more
   3  *  contributor license agreements.  See the NOTICE file distributed with
   4  *  this work for additional information regarding copyright ownership.
   5  *  The ASF licenses this file to You under the Apache License, Version 2.0
   6  *  (the "License"); you may not use this file except in compliance with
   7  *  the License.  You may obtain a copy of the License at
   8  *
   9  *     http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  *  Unless required by applicable law or agreed to in writing, software
  12  *  distributed under the License is distributed on an "AS IS" BASIS,
  13  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  *  See the License for the specific language governing permissions and
  15  *  limitations under the License.
  16  */
  17
  18 package java.io;
  19
  20 /**
  21  * A specialized {@link Writer} that writes characters to a {@code StringBuffer}
  22  * in a sequential manner, appending them in the process. The result can later
  23  * be queried using the {@link #StringWriter(int)} or {@link #toString()}
  24  * methods.
  25  *
  26  * @see StringReader
  27  */
  28 public class StringWriter extends Writer {
  29
  30     private StringBuffer buf;
  31
  32     /**
  33      * Constructs a new {@code StringWriter} which has a {@link StringBuffer}
  34      * allocated with the default size of 16 characters. The {@code
  35      * StringBuffer} is also the {@code lock} used to synchronize access to this
  36      * writer.
  37      */
  38     public StringWriter() {
  39         super();
  40         buf = new StringBuffer(16);
  41         lock = buf;
  42     }
  43
  44     /**
  45      * Constructs a new {@code StringWriter} which has a {@link StringBuffer}
  46      * allocated with a size of {@code initialSize} characters. The {@code
  47      * StringBuffer} is also the {@code lock} used to synchronize access to this
  48      * writer.
  49      *
  50      * @param initialSize
  51      *            the intial size of the target string buffer.
  52      */
  53     public StringWriter(int initialSize) {
  54         if (initialSize < 0) {
  55             throw new IllegalArgumentException();
  56         }
  57         buf = new StringBuffer(initialSize);
  58         lock = buf;
  59     }
  60
  61     /**
  62      * Calling this method has no effect. In contrast to most {@code Writer} subclasses,
  63      * the other methods in {@code StringWriter} do not throw an {@code IOException} if
  64      * {@code close()} has been called.
  65      *
  66      * @throws IOException
  67      *             if an error occurs while closing this writer.
  68      */
  69     @Override
  70     public void close() throws IOException {
  71         /* empty */
  72     }
  73
  74     /**
  75      * Calling this method has no effect.
  76      */
  77     @Override
  78     public void flush() {
  79         /* empty */
  80     }
  81
  82     /**
  83      * Gets a reference to this writer's internal {@link StringBuffer}. Any
  84      * changes made to the returned buffer are reflected in this writer.
  85      *
  86      * @return a reference to this writer's internal {@code StringBuffer}.
  87      */
  88     public StringBuffer getBuffer() {
  89         return buf;
  90     }
  91
  92     /**
  93      * Gets a copy of the contents of this writer as a string.
  94      *
  95      * @return this writer's contents as a string.
  96      */
  97     @Override
  98     public String toString() {
  99         return buf.toString();
 100     }
 101
 102     /**
 103      * Writes {@code count} characters starting at {@code offset} in {@code buf}
 104      * to this writer's {@code StringBuffer}.
 105      *
 106      * @param chars
 107      *            the non-null character array to write.
 108      * @param offset
 109      *            the index of the first character in {@code chars} to write.
 110      * @param count
 111      *            the maximum number of characters to write.
 112      * @throws IndexOutOfBoundsException
 113      *             if {@code offset < 0} or {@code count < 0}, or if {@code
 114      *             offset + count} is greater than the size of {@code buf}.
 115      */
 116     @Override
 117     public void write(char[] chars, int offset, int count) {
 118         // avoid int overflow
 119         // BEGIN android-changed
 120         // Exception priorities (in case of multiple errors) differ from
 121         // RI, but are spec-compliant.
 122         // removed redundant check, added null check, used (offset | count) < 0
 123         // instead of (offset < 0) || (count < 0) to safe one operation
 124         if (chars == null) {
 125             throw new NullPointerException("chars == null");
 126         }
 127         if ((offset | count) < 0 || count > chars.length - offset) {
 128             throw new IndexOutOfBoundsException();
 129         }
 130         // END android-changed
 131         if (count == 0) {
 132             return;
 133         }
 134         buf.append(chars, offset, count);
 135     }
 136
 137     /**
 138      * Writes one character to this writer's {@code StringBuffer}. Only the two
 139      * least significant bytes of the integer {@code oneChar} are written.
 140      *
 141      * @param oneChar
 142      *            the character to write to this writer's {@code StringBuffer}.
 143      */
 144     @Override
 145     public void write(int oneChar) {
 146         buf.append((char) oneChar);
 147     }
 148
 149     /**
 150      * Writes the characters from the specified string to this writer's {@code
 151      * StringBuffer}.
 152      *
 153      * @param str
 154      *            the non-null string containing the characters to write.
 155      */
 156     @Override
 157     public void write(String str) {
 158         buf.append(str);
 159     }
 160
 161     /**
 162      * Writes {@code count} characters from {@code str} starting at {@code
 163      * offset} to this writer's {@code StringBuffer}.
 164      *
 165      * @param str
 166      *            the non-null string containing the characters to write.
 167      * @param offset
 168      *            the index of the first character in {@code str} to write.
 169      * @param count
 170      *            the number of characters from {@code str} to write.
 171      * @throws StringIndexOutOfBoundsException
 172      *             if {@code offset < 0} or {@code count < 0}, or if {@code
 173      *             offset + count} is greater than the length of {@code str}.
 174      */
 175     @Override
 176     public void write(String str, int offset, int count) {
 177         String sub = str.substring(offset, offset + count);
 178         buf.append(sub);
 179     }
 180
 181     /**
 182      * Appends the character {@code c} to this writer's {@code StringBuffer}.
 183      * This method works the same way as {@link #write(int)}.
 184      *
 185      * @param c
 186      *            the character to append to the target stream.
 187      * @return this writer.
 188      */
 189     @Override
 190     public StringWriter append(char c) {
 191         write(c);
 192         return this;
 193     }
 194
 195     /**
 196      * Appends the character sequence {@code csq} to this writer's {@code
 197      * StringBuffer}. This method works the same way as {@code
 198      * StringWriter.write(csq.toString())}. If {@code csq} is {@code null}, then
 199      * the string "null" is written to the target stream.
 200      *
 201      * @param csq
 202      *            the character sequence appended to the target.
 203      * @return this writer.
 204      */
 205     @Override
 206     public StringWriter append(CharSequence csq) {
 207         if (null == csq) {
 208             write(TOKEN_NULL);
 209         } else {
 210             write(csq.toString());
 211         }
 212         return this;
 213     }
 214
 215     /**
 216      * Appends a subsequence of the character sequence {@code csq} to this
 217      * writer's {@code StringBuffer}. This method works the same way as {@code
 218      * StringWriter.writer(csq.subsequence(start, end).toString())}. If {@code
 219      * csq} is {@code null}, then the specified subsequence of the string "null"
 220      * will be written to the target.
 221      *
 222      * @param csq
 223      *            the character sequence appended to the target.
 224      * @param start
 225      *            the index of the first char in the character sequence appended
 226      *            to the target.
 227      * @param end
 228      *            the index of the character following the last character of the
 229      *            subsequence appended to the target.
 230      * @return this writer.
 231      * @throws IndexOutOfBoundsException
 232      *             if {@code start > end}, {@code start < 0}, {@code end < 0} or
 233      *             either {@code start} or {@code end} are greater or equal than
 234      *             the length of {@code csq}.
 235      */
 236     @Override
 237     public StringWriter append(CharSequence csq, int start, int end) {
 238         if (null == csq) {
 239             csq = TOKEN_NULL;
 240         }
 241         String output = csq.subSequence(start, end).toString();
 242         write(output, 0, output.length());
 243         return this;
 244     }
 245 }