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 */
017package org.apache.commons.io.output;
018
019import java.io.Serializable;
020import 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 * {@link java.io.StringWriter}, 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 * {@link java.io.StringWriter} should be used.
030 * </p>
031 * <h2>Deprecating Serialization</h2>
032 * <p>
033 * <em>Serialization is deprecated and will be removed in 3.0.</em>
034 * </p>
035 * @since 2.0
036 */
037public class StringBuilderWriter extends Writer implements Serializable {
038
039    private static final long serialVersionUID = -146927496096066153L;
040
041    /** The append target. */
042    private final StringBuilder builder;
043
044    /**
045     * Constructs a new {@link StringBuilder} instance with default capacity.
046     */
047    public StringBuilderWriter() {
048        this.builder = new StringBuilder();
049    }
050
051    /**
052     * Constructs a new {@link StringBuilder} instance with the specified capacity.
053     *
054     * @param capacity The initial capacity of the underlying {@link StringBuilder}
055     */
056    public StringBuilderWriter(final int capacity) {
057        this.builder = new StringBuilder(capacity);
058    }
059
060    /**
061     * Constructs a new instance with the specified {@link StringBuilder}.
062     *
063     * <p>If {@code builder} is null a new instance with default capacity will be created.</p>
064     *
065     * @param builder The String builder. May be null.
066     */
067    public StringBuilderWriter(final StringBuilder builder) {
068        this.builder = builder != null ? builder : new StringBuilder();
069    }
070
071    /**
072     * Appends a single character to this Writer.
073     *
074     * @param value The character to append
075     * @return This writer instance
076     */
077    @Override
078    public Writer append(final char value) {
079        builder.append(value);
080        return this;
081    }
082
083    /**
084     * Appends a character sequence to this Writer.
085     *
086     * @param value The character to append
087     * @return This writer instance
088     */
089    @Override
090    public Writer append(final CharSequence value) {
091        builder.append(value);
092        return this;
093    }
094
095    /**
096     * Appends a portion of a character sequence to the {@link StringBuilder}.
097     *
098     * @param value The character to append
099     * @param start The index of the first character
100     * @param end The index of the last character + 1
101     * @return This writer instance
102     */
103    @Override
104    public Writer append(final CharSequence value, final int start, final int end) {
105        builder.append(value, start, end);
106        return this;
107    }
108
109    /**
110     * Closing this writer has no effect.
111     */
112    @Override
113    public void close() {
114        // no-op
115    }
116
117    /**
118     * Flushing this writer has no effect.
119     */
120    @Override
121    public void flush() {
122        // no-op
123    }
124
125    /**
126     * Gets the underlying builder.
127     *
128     * @return The underlying builder
129     */
130    public StringBuilder getBuilder() {
131        return builder;
132    }
133
134    /**
135     * Returns {@link StringBuilder#toString()}.
136     *
137     * @return The contents of the String builder.
138     */
139    @Override
140    public String toString() {
141        return builder.toString();
142    }
143
144    /**
145     * Writes a portion of a character array to the {@link StringBuilder}.
146     *
147     * @param value The value to write
148     * @param offset The index of the first character
149     * @param length The number of characters to write
150     */
151    @Override
152    public void write(final char[] value, final int offset, final int length) {
153        if (value != null) {
154            builder.append(value, offset, length);
155        }
156    }
157
158    /**
159     * Writes a String to the {@link StringBuilder}.
160     *
161     * @param value The value to write
162     */
163    @Override
164    public void write(final String value) {
165        if (value != null) {
166            builder.append(value);
167        }
168    }
169}