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 }