View Javadoc
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  package org.apache.commons.io.output;
18  
19  import java.io.Serializable;
20  import java.io.Writer;
21  
22  /**
23   * {@link Writer} implementation that outputs to a {@link StringBuilder}.
24   * <p>
25   * <strong>NOTE:</strong> This implementation, as an alternative to
26   * <code>java.io.StringWriter</code>, provides an <i>un-synchronized</i>
27   * (i.e. for use in a single thread) implementation for better performance.
28   * For safe usage with multiple {@link Thread}s then
29   * <code>java.io.StringWriter</code> should be used.
30   *
31   * @version $Id: StringBuilderWriter.java 1415850 2012-11-30 20:51:39Z ggregory $
32   * @since 2.0
33   */
34  public class StringBuilderWriter extends Writer implements Serializable {
35  
36      private final StringBuilder builder;
37  
38      /**
39       * Construct a new {@link StringBuilder} instance with default capacity.
40       */
41      public StringBuilderWriter() {
42          this.builder = new StringBuilder();
43      }
44  
45      /**
46       * Construct a new {@link StringBuilder} instance with the specified capacity.
47       *
48       * @param capacity The initial capacity of the underlying {@link StringBuilder}
49       */
50      public StringBuilderWriter(final int capacity) {
51          this.builder = new StringBuilder(capacity);
52      }
53  
54      /**
55       * Construct a new instance with the specified {@link StringBuilder}.
56       *
57       * @param builder The String builder
58       */
59      public StringBuilderWriter(final StringBuilder builder) {
60          this.builder = builder != null ? builder : new StringBuilder();
61      }
62  
63      /**
64       * Append a single character to this Writer.
65       *
66       * @param value The character to append
67       * @return This writer instance
68       */
69      @Override
70      public Writer append(final char value) {
71          builder.append(value);
72          return this;
73      }
74  
75      /**
76       * Append a character sequence to this Writer.
77       *
78       * @param value The character to append
79       * @return This writer instance
80       */
81      @Override
82      public Writer append(final CharSequence value) {
83          builder.append(value);
84          return this;
85      }
86  
87      /**
88       * Append a portion of a character sequence to the {@link StringBuilder}.
89       *
90       * @param value The character to append
91       * @param start The index of the first character
92       * @param end The index of the last character + 1
93       * @return This writer instance
94       */
95      @Override
96      public Writer append(final CharSequence value, final int start, final int end) {
97          builder.append(value, start, end);
98          return this;
99      }
100 
101     /**
102      * Closing this writer has no effect. 
103      */
104     @Override
105     public void close() {
106     }
107 
108     /**
109      * Flushing this writer has no effect. 
110      */
111     @Override
112     public void flush() {
113     }
114 
115 
116     /**
117      * Write a String to the {@link StringBuilder}.
118      * 
119      * @param value The value to write
120      */
121     @Override
122     public void write(final String value) {
123         if (value != null) {
124             builder.append(value);
125         }
126     }
127 
128     /**
129      * Write a portion of a character array to the {@link StringBuilder}.
130      *
131      * @param value The value to write
132      * @param offset The index of the first character
133      * @param length The number of characters to write
134      */
135     @Override
136     public void write(final char[] value, final int offset, final int length) {
137         if (value != null) {
138             builder.append(value, offset, length);
139         }
140     }
141 
142     /**
143      * Return the underlying builder.
144      *
145      * @return The underlying builder
146      */
147     public StringBuilder getBuilder() {
148         return builder;
149     }
150 
151     /**
152      * Returns {@link StringBuilder#toString()}.
153      *
154      * @return The contents of the String builder.
155      */
156     @Override
157     public String toString() {
158         return builder.toString();
159     }
160 }