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}, 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} 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 private final StringBuilder builder; 041 042 /** 043 * Constructs a new {@link StringBuilder} instance with default capacity. 044 */ 045 public StringBuilderWriter() { 046 this.builder = new StringBuilder(); 047 } 048 049 /** 050 * Constructs a new {@link StringBuilder} instance with the specified capacity. 051 * 052 * @param capacity The initial capacity of the underlying {@link StringBuilder} 053 */ 054 public StringBuilderWriter(final int capacity) { 055 this.builder = new StringBuilder(capacity); 056 } 057 058 /** 059 * Constructs a new instance with the specified {@link StringBuilder}. 060 * 061 * <p>If {@code builder} is null a new instance with default capacity will be created.</p> 062 * 063 * @param builder The String builder. May be null. 064 */ 065 public StringBuilderWriter(final StringBuilder builder) { 066 this.builder = builder != null ? builder : new StringBuilder(); 067 } 068 069 /** 070 * Appends a single character to this Writer. 071 * 072 * @param value The character to append 073 * @return This writer instance 074 */ 075 @Override 076 public Writer append(final char value) { 077 builder.append(value); 078 return this; 079 } 080 081 /** 082 * Appends a character sequence to this Writer. 083 * 084 * @param value The character to append 085 * @return This writer instance 086 */ 087 @Override 088 public Writer append(final CharSequence value) { 089 builder.append(value); 090 return this; 091 } 092 093 /** 094 * Appends a portion of a character sequence to the {@link StringBuilder}. 095 * 096 * @param value The character to append 097 * @param start The index of the first character 098 * @param end The index of the last character + 1 099 * @return This writer instance 100 */ 101 @Override 102 public Writer append(final CharSequence value, final int start, final int end) { 103 builder.append(value, start, end); 104 return this; 105 } 106 107 /** 108 * Closing this writer has no effect. 109 */ 110 @Override 111 public void close() { 112 // no-op 113 } 114 115 /** 116 * Flushing this writer has no effect. 117 */ 118 @Override 119 public void flush() { 120 // no-op 121 } 122 123 124 /** 125 * Returns 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}