1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 package org.apache.commons.io.output; 18 19 import java.io.Serializable; 20 import java.io.Writer; 21 22 /** 23 * {@link Writer} implementation that outputs to a {@link StringBuilder}. 24 * <p> 25 * <strong>NOTE:</strong> This implementation, as an alternative to 26 * {@link java.io.StringWriter}, provides an <i>un-synchronized</i> 27 * (i.e. for use in a single thread) implementation for better performance. 28 * For safe usage with multiple {@link Thread}s then 29 * {@link java.io.StringWriter} should be used. 30 * </p> 31 * <h2>Deprecating Serialization</h2> 32 * <p> 33 * <em>Serialization is deprecated and will be removed in 3.0.</em> 34 * </p> 35 * @since 2.0 36 */ 37 public class StringBuilderWriter extends Writer implements Serializable { 38 39 private static final long serialVersionUID = -146927496096066153L; 40 41 /** The append target. */ 42 private final StringBuilder builder; 43 44 /** 45 * Constructs a new {@link StringBuilder} instance with default capacity. 46 */ 47 public StringBuilderWriter() { 48 this.builder = new StringBuilder(); 49 } 50 51 /** 52 * Constructs a new {@link StringBuilder} instance with the specified capacity. 53 * 54 * @param capacity The initial capacity of the underlying {@link StringBuilder} 55 */ 56 public StringBuilderWriter(final int capacity) { 57 this.builder = new StringBuilder(capacity); 58 } 59 60 /** 61 * Constructs a new instance with the specified {@link StringBuilder}. 62 * 63 * <p>If {@code builder} is null a new instance with default capacity will be created.</p> 64 * 65 * @param builder The String builder. May be null. 66 */ 67 public StringBuilderWriter(final StringBuilder builder) { 68 this.builder = builder != null ? builder : new StringBuilder(); 69 } 70 71 /** 72 * Appends a single character to this Writer. 73 * 74 * @param value The character to append 75 * @return This writer instance 76 */ 77 @Override 78 public Writer append(final char value) { 79 builder.append(value); 80 return this; 81 } 82 83 /** 84 * Appends a character sequence to this Writer. 85 * 86 * @param value The character to append 87 * @return This writer instance 88 */ 89 @Override 90 public Writer append(final CharSequence value) { 91 builder.append(value); 92 return this; 93 } 94 95 /** 96 * Appends a portion of a character sequence to the {@link StringBuilder}. 97 * 98 * @param value The character to append 99 * @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 }