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   * @since 2.0
32   */
33  public class StringBuilderWriter extends Writer implements Serializable {
34  
35      private static final long serialVersionUID = -146927496096066153L;
36      private final StringBuilder builder;
37  
38      /**
39       * Constructs a new {@link StringBuilder} instance with default capacity.
40       */
41      public StringBuilderWriter() {
42          this.builder = new StringBuilder();
43      }
44  
45      /**
46       * Constructs 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       * Constructs a new instance with the specified {@link StringBuilder}.
56       * 
57       * <p>If {@code builder} is null a new instance with default capacity will be created.</p>
58       *
59       * @param builder The String builder. May be null.
60       */
61      public StringBuilderWriter(final StringBuilder builder) {
62          this.builder = builder != null ? builder : new StringBuilder();
63      }
64  
65      /**
66       * Appends a single character to this Writer.
67       *
68       * @param value The character to append
69       * @return This writer instance
70       */
71      @Override
72      public Writer append(final char value) {
73          builder.append(value);
74          return this;
75      }
76  
77      /**
78       * Appends a character sequence to this Writer.
79       *
80       * @param value The character to append
81       * @return This writer instance
82       */
83      @Override
84      public Writer append(final CharSequence value) {
85          builder.append(value);
86          return this;
87      }
88  
89      /**
90       * Appends a portion of a character sequence to the {@link StringBuilder}.
91       *
92       * @param value The character to append
93       * @param start The index of the first character
94       * @param end The index of the last character + 1
95       * @return This writer instance
96       */
97      @Override
98      public Writer append(final CharSequence value, final int start, final int end) {
99          builder.append(value, start, end);
100         return this;
101     }
102 
103     /**
104      * Closing this writer has no effect. 
105      */
106     @Override
107     public void close() {
108         // no-op
109     }
110 
111     /**
112      * Flushing this writer has no effect. 
113      */
114     @Override
115     public void flush() {
116         // no-op
117     }
118 
119 
120     /**
121      * Writes a String to the {@link StringBuilder}.
122      * 
123      * @param value The value to write
124      */
125     @Override
126     public void write(final String value) {
127         if (value != null) {
128             builder.append(value);
129         }
130     }
131 
132     /**
133      * Writes a portion of a character array to the {@link StringBuilder}.
134      *
135      * @param value The value to write
136      * @param offset The index of the first character
137      * @param length The number of characters to write
138      */
139     @Override
140     public void write(final char[] value, final int offset, final int length) {
141         if (value != null) {
142             builder.append(value, offset, length);
143         }
144     }
145 
146     /**
147      * Returns the underlying builder.
148      *
149      * @return The underlying builder
150      */
151     public StringBuilder getBuilder() {
152         return builder;
153     }
154 
155     /**
156      * Returns {@link StringBuilder#toString()}.
157      *
158      * @return The contents of the String builder.
159      */
160     @Override
161     public String toString() {
162         return builder.toString();
163     }
164 }