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.StringWriter; 021import java.io.Writer; 022 023/** 024 * {@link Writer} implementation that outputs to a {@link StringBuilder}. 025 * <p> 026 * <strong>NOTE:</strong> This implementation, as an alternative to 027 * {@link StringWriter}, provides an <em>un-synchronized</em> 028 * (i.e. for use in a single thread) implementation for better performance. 029 * For safe usage with multiple {@link Thread}s then 030 * {@link StringWriter} should be used. 031 * </p> 032 * <h2>Deprecating Serialization</h2> 033 * <p> 034 * <em>Serialization is deprecated and will be removed in 3.0.</em> 035 * </p> 036 * @since 2.0 037 */ 038public class StringBuilderWriter extends Writer implements Serializable { 039 040 private static final long serialVersionUID = -146927496096066153L; 041 042 /** The append target. */ 043 private final StringBuilder builder; 044 045 /** 046 * Constructs a new {@link StringBuilder} instance with default capacity. 047 */ 048 public StringBuilderWriter() { 049 this.builder = new StringBuilder(); 050 } 051 052 /** 053 * Constructs a new {@link StringBuilder} instance with the specified capacity. 054 * 055 * @param capacity The initial capacity of the underlying {@link StringBuilder} 056 */ 057 public StringBuilderWriter(final int capacity) { 058 this.builder = new StringBuilder(capacity); 059 } 060 061 /** 062 * Constructs a new instance with the specified {@link StringBuilder}. 063 * 064 * <p>If {@code builder} is null a new instance with default capacity will be created.</p> 065 * 066 * @param builder The String builder. May be null. 067 */ 068 public StringBuilderWriter(final StringBuilder builder) { 069 this.builder = builder != null ? builder : new StringBuilder(); 070 } 071 072 /** 073 * Appends a single character to this Writer. 074 * 075 * @param value The character to append 076 * @return This writer instance 077 */ 078 @Override 079 public Writer append(final char value) { 080 builder.append(value); 081 return this; 082 } 083 084 /** 085 * Appends a character sequence to this Writer. 086 * 087 * @param value The character to append 088 * @return This writer instance 089 */ 090 @Override 091 public Writer append(final CharSequence value) { 092 builder.append(value); 093 return this; 094 } 095 096 /** 097 * Appends a portion of a character sequence to the {@link StringBuilder}. 098 * 099 * @param value The character to append 100 * @param start The index of the first character 101 * @param end The index of the last character + 1 102 * @return This writer instance 103 */ 104 @Override 105 public Writer append(final CharSequence value, final int start, final int end) { 106 builder.append(value, start, end); 107 return this; 108 } 109 110 /** 111 * Closing this writer has no effect. 112 */ 113 @Override 114 public void close() { 115 // no-op 116 } 117 118 /** 119 * Flushing this writer has no effect. 120 */ 121 @Override 122 public void flush() { 123 // no-op 124 } 125 126 /** 127 * Gets the underlying builder. 128 * 129 * @return The underlying builder 130 */ 131 public StringBuilder getBuilder() { 132 return builder; 133 } 134 135 /** 136 * Returns {@link StringBuilder#toString()}. 137 * 138 * @return The contents of the String builder. 139 */ 140 @Override 141 public String toString() { 142 return builder.toString(); 143 } 144 145 /** 146 * Writes a portion of a character array to the {@link StringBuilder}. 147 * 148 * @param value The value to write 149 * @param offset The index of the first character 150 * @param length The number of characters to write 151 */ 152 @Override 153 public void write(final char[] value, final int offset, final int length) { 154 if (value != null) { 155 builder.append(value, offset, length); 156 } 157 } 158 159 /** 160 * Writes a String to the {@link StringBuilder}. 161 * 162 * @param value The value to write 163 */ 164 @Override 165 public void write(final String value) { 166 if (value != null) { 167 builder.append(value); 168 } 169 } 170}