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 * {@code 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 * {@code 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 private final StringBuilder builder; 41 42 /** 43 * Constructs a new {@link StringBuilder} instance with default capacity. 44 */ 45 public StringBuilderWriter() { 46 this.builder = new StringBuilder(); 47 } 48 49 /** 50 * Constructs a new {@link StringBuilder} instance with the specified capacity. 51 * 52 * @param capacity The initial capacity of the underlying {@link StringBuilder} 53 */ 54 public StringBuilderWriter(final int capacity) { 55 this.builder = new StringBuilder(capacity); 56 } 57 58 /** 59 * Constructs a new instance with the specified {@link StringBuilder}. 60 * 61 * <p>If {@code builder} is null a new instance with default capacity will be created.</p> 62 * 63 * @param builder The String builder. May be null. 64 */ 65 public StringBuilderWriter(final StringBuilder builder) { 66 this.builder = builder != null ? builder : new StringBuilder(); 67 } 68 69 /** 70 * Appends a single character to this Writer. 71 * 72 * @param value The character to append 73 * @return This writer instance 74 */ 75 @Override 76 public Writer append(final char value) { 77 builder.append(value); 78 return this; 79 } 80 81 /** 82 * Appends a character sequence to this Writer. 83 * 84 * @param value The character to append 85 * @return This writer instance 86 */ 87 @Override 88 public Writer append(final CharSequence value) { 89 builder.append(value); 90 return this; 91 } 92 93 /** 94 * Appends a portion of a character sequence to the {@link StringBuilder}. 95 * 96 * @param value The character to append 97 * @param start The index of the first character 98 * @param end The index of the last character + 1 99 * @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 }