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