    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 $Revision: 1003647 $ $Date: 2010-10-01 21:53:59 +0100 (Fri, 01 Oct 2010) $
    032     * @since Commons IO 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    }