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 * <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 * @since 2.0
032 */
033public class StringBuilderWriter extends Writer implements Serializable {
034
035    private static final long serialVersionUID = -146927496096066153L;
036    private final StringBuilder builder;
037
038    /**
039     * Constructs a new {@link StringBuilder} instance with default capacity.
040     */
041    public StringBuilderWriter() {
042        this.builder = new StringBuilder();
043    }
044
045    /**
046     * Constructs 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(final int capacity) {
051        this.builder = new StringBuilder(capacity);
052    }
053
054    /**
055     * Constructs a new instance with the specified {@link StringBuilder}.
056     *
057     * <p>If {@code builder} is null a new instance with default capacity will be created.</p>
058     *
059     * @param builder The String builder. May be null.
060     */
061    public StringBuilderWriter(final StringBuilder builder) {
062        this.builder = builder != null ? builder : new StringBuilder();
063    }
064
065    /**
066     * Appends a single character to this Writer.
067     *
068     * @param value The character to append
069     * @return This writer instance
070     */
071    @Override
072    public Writer append(final char value) {
073        builder.append(value);
074        return this;
075    }
076
077    /**
078     * Appends a character sequence to this Writer.
079     *
080     * @param value The character to append
081     * @return This writer instance
082     */
083    @Override
084    public Writer append(final CharSequence value) {
085        builder.append(value);
086        return this;
087    }
088
089    /**
090     * Appends a portion of a character sequence to the {@link StringBuilder}.
091     *
092     * @param value The character to append
093     * @param start The index of the first character
094     * @param end The index of the last character + 1
095     * @return This writer instance
096     */
097    @Override
098    public Writer append(final CharSequence value, final int start, final int end) {
099        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}