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.StringWriter; 21 import java.io.Writer; 22 23 /** 24 * {@link Writer} implementation that outputs to a {@link StringBuilder}. 25 * <p> 26 * <strong>NOTE:</strong> This implementation, as an alternative to {@link StringWriter}, provides an <em>un-synchronized</em> implementation for better 27 * performance for use in a single thread. For safe usage with multiple {@link Thread}s, a {@link StringWriter} should be used. 28 * </p> 29 * <h2>Deprecating Serialization</h2> 30 * <p> 31 * <em>Serialization is deprecated and will be removed in 3.0.</em> 32 * </p> 33 * 34 * @since 2.0 35 */ 36 public class StringBuilderWriter extends Writer implements Serializable { 37 38 private static final long serialVersionUID = -146927496096066153L; 39 40 /** The append target. */ 41 private final StringBuilder builder; 42 43 /** 44 * Constructs a new {@link StringBuilder} instance with default capacity. 45 */ 46 public StringBuilderWriter() { 47 this.builder = new StringBuilder(); 48 } 49 50 /** 51 * Constructs a new {@link StringBuilder} instance with the specified capacity. 52 * 53 * @param capacity The initial capacity of the underlying {@link StringBuilder} 54 */ 55 public StringBuilderWriter(final int capacity) { 56 this.builder = new StringBuilder(capacity); 57 } 58 59 /** 60 * Constructs a new instance with the specified {@link StringBuilder}. 61 * 62 * <p>If {@code builder} is null a new instance with default capacity will be created.</p> 63 * 64 * @param builder The String builder. May be null. 65 */ 66 public StringBuilderWriter(final StringBuilder builder) { 67 this.builder = builder != null ? builder : new StringBuilder(); 68 } 69 70 /** 71 * Appends a single character to this Writer. 72 * 73 * @param value The character to append 74 * @return This writer instance 75 */ 76 @Override 77 public Writer append(final char value) { 78 builder.append(value); 79 return this; 80 } 81 82 /** 83 * Appends a character sequence to this Writer. 84 * 85 * @param value The character to append 86 * @return This writer instance 87 */ 88 @Override 89 public Writer append(final CharSequence value) { 90 builder.append(value); 91 return this; 92 } 93 94 /** 95 * Appends a portion of a character sequence to the {@link StringBuilder}. 96 * 97 * @param value The character to append 98 * @param start The index of the first character 99 * @param end The index of the last character + 1 100 * @return This writer instance 101 */ 102 @Override 103 public Writer append(final CharSequence value, final int start, final int end) { 104 builder.append(value, start, end); 105 return this; 106 } 107 108 /** 109 * Closing this writer has no effect. 110 */ 111 @Override 112 public void close() { 113 // no-op 114 } 115 116 /** 117 * Flushing this writer has no effect. 118 */ 119 @Override 120 public void flush() { 121 // no-op 122 } 123 124 /** 125 * Gets 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 }