001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017 package org.apache.commons.io.output;
018
019 import java.io.Serializable;
020 import java.io.Writer;
021
022 /**
023 * {@link Writer} implementation that outputs to a {@link StringBuilder}.
024 * <p>
025 * <strong>NOTE:</strong> This implementation, as an alternative to
026 * <code>java.io.StringWriter</code>, provides an <i>un-synchronized</i>
027 * (i.e. for use in a single thread) implementation for better performance.
028 * For safe usage with multiple {@link Thread}s then
029 * <code>java.io.StringWriter</code> should be used.
030 *
031 * @version $Id: StringBuilderWriter.java 1304052 2012-03-22 20:55:29Z ggregory $
032 * @since 2.0
033 */
034 public class StringBuilderWriter extends Writer implements Serializable {
035
036 private final StringBuilder builder;
037
038 /**
039 * Construct a new {@link StringBuilder} instance with default capacity.
040 */
041 public StringBuilderWriter() {
042 this.builder = new StringBuilder();
043 }
044
045 /**
046 * Construct a new {@link StringBuilder} instance with the specified capacity.
047 *
048 * @param capacity The initial capacity of the underlying {@link StringBuilder}
049 */
050 public StringBuilderWriter(int capacity) {
051 this.builder = new StringBuilder(capacity);
052 }
053
054 /**
055 * Construct a new instance with the specified {@link StringBuilder}.
056 *
057 * @param builder The String builder
058 */
059 public StringBuilderWriter(StringBuilder builder) {
060 this.builder = builder != null ? builder : new StringBuilder();
061 }
062
063 /**
064 * Append a single character to this Writer.
065 *
066 * @param value The character to append
067 * @return This writer instance
068 */
069 @Override
070 public Writer append(char value) {
071 builder.append(value);
072 return this;
073 }
074
075 /**
076 * Append a character sequence to this Writer.
077 *
078 * @param value The character to append
079 * @return This writer instance
080 */
081 @Override
082 public Writer append(CharSequence value) {
083 builder.append(value);
084 return this;
085 }
086
087 /**
088 * Append a portion of a character sequence to the {@link StringBuilder}.
089 *
090 * @param value The character to append
091 * @param start The index of the first character
092 * @param end The index of the last character + 1
093 * @return This writer instance
094 */
095 @Override
096 public Writer append(CharSequence value, int start, int end) {
097 builder.append(value, start, end);
098 return this;
099 }
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(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(char[] value, int offset, 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 }