java.lang

接口
异常
错误
注释
java.lang.Object
  继承者 java.lang.StringBuilder
所有已实现的接口:
Serializable, Appendable, CharSequence

public final class StringBuilder
     
extends Object
implements Serializable, CharSequence

一个可变的字符序列。此类提供一个与 StringBuffer 兼容的 API,但不保证同步。该类被设计用作 StringBuffer 的一个简易替换,用在字符串缓冲区被单个线程使用的时候(这种情况很普遍)。如果可能,建议优先采用该类,因为在大多数实现中,它比 StringBuffer 要快。

StringBuilder 上的主要操作是 appendinsert 方法,可重载这些方法,以接受任意类型的数据。每个方法都能有效地将给定的数据转换成字符串,然后将该字符串的字符追加或插入到字符串生成器中。append 方法始终将这些字符添加到生成器的末端;而 insert 方法则在指定的点添加字符。

例如,如果 z 引用一个当前内容为 "start" 的字符串的生成器对象,则该方法调用 z.append("le") 将使字符串生成器包含 "startle",而 z.insert(4, "le") 将更改字符串生成器,使之包含 "starlet"。

通常,如果 sb 引用 StringBuilder 的实例,则 sb.append(x)sb.insert(sb.length(), x) 具有相同的效果。每个字符串生成器都有一定的容量。只要字符串生成器所包含的字符序列的长度没有超出此容量,就无需分配新的内部缓冲区。如果内部缓冲区溢出,则此容量自动增大。

StringBuilder 的实例用于多个线程是不安全的。如果需要这样的同步,则建议使用 StringBuffer

从以下版本开始:
1.5
另请参见:
StringBuffer, String, 序列化表格

构造方法摘要
StringBuilder()
          构造一个不带任何字符的字符串生成器,其初始容量为 16 个字符。
StringBuilder(CharSequence seq)
          构造一个字符串生成器,它包含与指定的 CharSequence 相同的字符。
StringBuilder(int capacity)
          构造一个不带任何字符的字符串生成器,其初始容量由 capacity 参数指定。
StringBuilder(String str)
          构造一个字符串生成器,并初始化为指定的字符串内容。
 
方法摘要
 StringBuilder append(boolean b)
          将 boolean 参数的字符串表示形式追加到序列。
 StringBuilder append(char c)
          将 char 参数的字符串表示形式追加到此序列。
 StringBuilder append(char[] str)
          将 char 数组参数的字符串表示形式追加到此序列。
 StringBuilder append(char[] str, int offset, int len)
          将 char 数组参数的子数组的字符串表示形式追加到此序列。
 StringBuilder append(CharSequence s)
          向此 Appendable 追加到指定的字符序列。
 StringBuilder append(CharSequence s, int start, int end)
          将指定 CharSequence 的子序列追加到此序列。
 StringBuilder append(double d)
          将 double 参数的字符串表示形式追加到此序列。
 StringBuilder append(float f)
          将 float 参数的字符串表示形式追加到此序列。
 StringBuilder append(int i)
          将 int 参数的字符串表示形式追加到此序列。
 StringBuilder append(long lng)
          将 long 参数的字符串表示形式追加到此序列。
 StringBuilder append(Object obj)
          追加 Object 参数的字符串表示形式。
 StringBuilder append(String str)
          将指定的字符串追加到此字符序列。
 StringBuilder append(StringBuffer sb)
          将指定的 StringBuffer 追加到此序列。
 StringBuilder appendCodePoint(int codePoint)
          将 codePoint 参数的字符串表示形式追加到此序列。
 int capacity()
          返回当前容量。
 char charAt(int index)
          返回此序列中指定索引处的 char 值。
 int codePointAt(int index)
          返回指定索引处的字符(统一代码点)。
 int codePointBefore(int index)
          返回指定索引前的字符(统一代码点)。
 int codePointCount(int beginIndex, int endIndex)
          返回此序列指定文本范围内的统一代码点。
 StringBuilder delete(int start, int end)
          移除此序列的子字符串中的字符。
 StringBuilder deleteCharAt(int index)
          移除此序列指定位置上的 char
 void ensureCapacity(int minimumCapacity)
          确保容量至少等于指定的最小值。
 void getChars(int srcBegin, int srcEnd, char[] dst, int dstBegin)
          将字符从此序列复制到目标字符数组 dst
 int indexOf(String str)
          返回第一次出现的指定子字符串在该字符串中的索引。
 int indexOf(String str, int fromIndex)
          从指定的索引处开始,返回第一次出现的指定子字符串在该字符串中的索引。
 StringBuilder insert(int offset, boolean b)
          将 boolean 参数的字符串表示形式插入此序列中。
 StringBuilder insert(int offset, char c)
          将 char 参数的字符串表示形式插入此序列中。
 StringBuilder insert(int offset, char[] str)
          将 char 数组参数的字符串表示形式插入此序列中。
 StringBuilder insert(int index, char[] str, int offset, int len)
          将数组参数 str 子数组的字符串表示形式插入此序列中。
 StringBuilder insert(int dstOffset, CharSequence s)
          将指定 CharSequence 插入此序列中。
 StringBuilder insert(int dstOffset, CharSequence s, int start, int end)
          将指定 CharSequence 的子序列插入此序列中。
 StringBuilder insert(int offset, double d)
          将 double 参数的字符串表示形式插入此序列中。
 StringBuilder insert(int offset, float f)
          将 float 参数的字符串表示形式插入此序列中。
 StringBuilder insert(int offset, int i)
          将 int 参数的字符串表示形式插入此序列中。
 StringBuilder insert(int offset, long l)
          将 long 参数的字符串表示形式插入此序列中。
 StringBuilder insert(int offset, Object obj)
          将 Object 参数的字符串表示形式插入此字符序列中。
 StringBuilder insert(int offset, String str)
          将字符串插入此字符序列中。
 int lastIndexOf(String str)
          返回最右边出现的指定子字符串在此字符串中的索引。
 int lastIndexOf(String str, int fromIndex)
          返回最后一次出现的指定子字符串在此字符串中的索引。
 int length()
          返回长度(字符数)。
 int offsetByCodePoints(int index, int codePointOffset)
          返回此序列中的一个索引,该索引是从给定 index 偏移 codePointOffset 个代码点后得到的。
 StringBuilder replace(int start, int end, String str)
          使用给定 String 中的字符替换此序列的子字符串中的字符。
 StringBuilder reverse()
          将此字符序列用其反转形式取代。
 void setCharAt(int index, char ch)
          将给定索引处的字符设置为 ch
 void setLength(int newLength)
          设置字符序列的长度。
 CharSequence subSequence(int start, int end)
          返回一个新字符序列,该字符序列是此序列的子序列。
 String substring(int start)
          返回一个新的 String,它包含此字符序列当前所包含字符的子序列。
 String substring(int start, int end)
          返回一个新的 String,它包含此序列当前所包含字符的子序列。
 String toString()
          返回此序列中数据的字符串表示形式。
 void trimToSize()
          尝试减少用于字符序列的存储空间。
 
从类 java.lang.Object 继承的方法
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
从接口 java.lang.CharSequence 继承的方法
charAt, length, subSequence
 

构造方法详细信息

StringBuilder

public StringBuilder()
构造一个不带任何字符的字符串生成器,其初始容量为 16 个字符。


StringBuilder

public StringBuilder(int capacity)
构造一个不带任何字符的字符串生成器,其初始容量由 capacity 参数指定。

参数:
capacity - 初始容量。
抛出:
NegativeArraySizeException - 如果 capacity 参数小于 0

StringBuilder

public StringBuilder(String str)
构造一个字符串生成器,并初始化为指定的字符串内容。该字符串生成器的初始容量为 16 加上字符串参数的长度。

参数:
str - 缓冲区的初始内容。
抛出:
NullPointerException - 如果 strnull

StringBuilder

public StringBuilder(CharSequence seq)
构造一个字符串生成器,包含与指定的 CharSequence 相同的字符。该字符串生成器的初始容量为 16 加上 CharSequence 参数的长度。

参数:
seq - 要复制的序列。
抛出:
NullPointerException - 如果 seqnull
方法详细信息

append

public StringBuilder append(Object obj)
追加 Object 参数的字符串表示形式。

参数将被转换成字符串,就好象使用了 String.valueOf 方法一样。然后,将所得字符串中的字符追加到此序列。

参数:
obj - 一个 Object
返回:
此对象的一个引用。
另请参见:
String.valueOf(java.lang.Object), append(java.lang.String)

append

public StringBuilder append(String str)
将指定的字符串追加到此字符序列。

按顺序追加 String 变量中的字符,此序列将增加该变量的长度。如果 strnull,则追加 4 个字符 "null"

假设此字符序列的长度在执行 append 方法前为 n。如果 k 小于 n,则新字符序列中索引 k 处的字符等于原序列中索引 k 处的字符;否则它等于参数 str 中索引 k-n 处的字符。

参数:
str - 一个 string。
返回:
此对象的一个引用。

append

public StringBuilder append(StringBuffer sb)
将指定的 StringBuffer 追加到此序列。

按顺序追加 StringBuffer 参数中的字符,此序列将增加该参数的长度。如果 sbnull,则向该序列中追加 4 个 "null" 字符。

在执行 append 方法前,让此字符序列的长度为 n。如果 k 小于 n,则新字符序列中索引 k 处的字符等于原有序列中索引 k 处的字符;否则它等于参数 sb 中索引 k-n 处的字符。

参数:
sb - 要追加的 StringBuffer
返回:
此对象的一个引用。

append

public StringBuilder append(CharSequence s)
从接口 Appendable 复制的描述
向此 Appendable 追加指定的字符序列。

有时可能没有追加整个序列,这取决于使用哪个类来实现字符序列 csq。例如,如果 csqCharBuffer 的一个实例,则通过缓冲区的位置和限制来定义要追加的子序列。

指定者:
接口 Appendable 中的 append
参数:
s - 要追加的字符串序列。如果 csqnull,则向该 Appendable 追加 4 个字符 "null"
返回:
Appendable 的引用
抛出:
IndexOutOfBoundsException

append

public StringBuilder append(CharSequence s,
                            int start,
int end)
将指定 CharSequence 的子序列追加到此序列。

将参数 s 中从索引 start 到索引 end 的字符按顺序追加到此序列。序列的长度将增加 end - start

假设此字符序列的长度在执行 append 方法前为 n。如果 k 小于 n,则新字符序列中索引 k 处的字符等于原序列中索引 k 处的字符;否则它等于参数 s 中索引 k+start-n 处的字符。

如果 snull,则认为 s 参数包含 4 个字符 "null",并以此为根据追加字符。

指定者:
接口 Appendable 中的 append
参数:
s - 要追加的序列。
start - 要追加的子序列的起始索引。
end - 要追加的子序列的结束索引。
返回:
此对象的一个引用。
抛出:
IndexOutOfBoundsException 如果 startend 为负;或者 start 大于 end;或者 end 大于 s.length()

append

public StringBuilder append(char[] str)
char 数组参数的字符串表示形式追加到此序列。

按顺序将数组参数中的字符追加到此序列中。此字符将增加该参数的长度。

该方法的最终效果与以下操作过程的效果相同:先使用 String.valueOf(char[]) 方法将参数转换为字符串,然后将所得字符串的字符追加到此字符序列。

参数:
str - 要追加的字符。
返回:
此对象的一个引用。

append

public StringBuilder append(char[] str,
                            int offset,
                            int len)
将数组参数 char 子数组的字符串表示形式追加到此序列。

char 数组 str 中从索引 offset 开始的字符按顺序追加到此序列。此字符的长度增加 len

该方法的最终效果与以下操作过程的效果相同:先使用 String.valueOf(char[]) 方法将参数转换为字符串,然后将所得字符串的字符追加到此字符序列。

参数:
str - 要追加的字符。
offset - 要追加的第一个 char 的索引。
len - 要追加的 char 数。
返回:
此对象的一个引用。

append

public StringBuilder append(boolean b)
boolean 参数的字符串表示形式追加到序列。

参数将被转换成字符串,就好象使用了 String.valueOf 方法一样。然后,将所得字符串中的字符追加到此序列。

参数:
b - 一个 boolean 值。
返回:
此对象的一个引用。
另请参见:
String.valueOf(boolean), append(java.lang.String)

append

public StringBuilder append(char c)
char 参数的字符串表示形式追加到此序列。

参数将被追加到此序列。此序列的长度将增加 1

该方法的最终效果与以下操作过程的效果相同:先使用 String.valueOf(char[]) 方法将参数转换为字符串,然后将所得字符串的字符追加到此字符序列。

指定者:
接口 Appendable 中的 append
参数:
c - 一个 char 值。
返回:
此对象的一个引用。

append

public StringBuilder append(int i)
int 参数的字符串表示形式追加到此序列。

参数将被转换成字符串,就好象使用了 String.valueOf 方法一样。然后,将所得字符串中的字符追加到此序列。

参数:
i - 一个 int 值。
返回:
此对象的一个引用。
另请参见:
String.valueOf(int), append(java.lang.String)

append

public StringBuilder append(long lng)
long 参数的字符串表示形式追加到此序列。

参数将被转换成字符串,就好象使用了 String.valueOf 方法一样。然后,将所得字符串中的字符追加到此序列。

参数:
lng - 一个 long 值。
返回:
此对象的一个引用。
另请参见:
String.valueOf(long), append(java.lang.String)

append

public StringBuilder append(float f)
float 参数的字符串表示形式追加到此序列。

参数将被转换成字符串,就好象使用了 String.valueOf 方法一样。然后,将所得字符串中的字符追加到此字符串序列。

参数:
f - 一个 float 值。
返回:
此对象的一个引用。
另请参见:
String.valueOf(float), append(java.lang.String)

append

public StringBuilder append(double d)
double 参数的字符串表示形式追加到此序列。

参数将被转换成字符串,就好象使用了 String.valueOf 方法一样。然后,将所得字符串中的字符追加到此序列。

参数:
d - 一个 double 值。
返回:
此对象的一个引用。
另请参见:
String.valueOf(double), append(java.lang.String)

appendCodePoint

public StringBuilder appendCodePoint(int codePoint)
codePoint 参数的字符串表示形式追加到此序列。

参数将被追加到此序列。此序列的长度将增加 Character.charCount(codePoint)

该方法的最终效果与以下操作过程的效果相同:先使用 Character.toChars(int) 方法将 char 数组转换为字符串,然后将所得字符串的字符追加到此字符序列。

参数:
codePoint - 一个 Unicode 代码点
返回:
此对象的一个引用。
从以下版本开始:
1.5

delete

public StringBuilder delete(int start,
int end)
移除此序列的子字符串中的字符。该子字符串从指定的 start 处开始,一直到索引 end - 1 处的字符,如果不存在这种字符,则一直到序列尾部。如果 start 等于 end,则不发生任何更改。

参数:
start - 起始索引(包含)。
end - 结束索引(不包含)。
返回:
此对象。
抛出:
StringIndexOutOfBoundsException - 如果 start 为负、大于 length() 或大于 end

deleteCharAt

public StringBuilder deleteCharAt(int index)
移除此序列指定位置上的 char。此序列将缩短一个 char

注:如果给定索引处的字符是增补字符,则此方法将不会移除整个字符。如果需要准确处理增补字符,那么可以通过调用 Character.charCount(thisSequence.codePointAt(index))(用此序列取代 thisSequence)来确定要移除的 char 数。

参数:
index - 要移除的 char 的索引
返回:
此对象。
抛出:
StringIndexOutOfBoundsException - 如果 index 为负或大于等于 length()

replace

public StringBuilder replace(int start,
int end,
                             String str)
使用给定 String 中的字符替换此序列的子字符串中的字符。该子字符串从指定的 start 处开始,一直到索引 end - 1 处的字符,如果不存在这种字符,则一直到序列尾部。先将子字符串中的字符移除,然后将指定的 String 插入 start。(如果需要,序列将延长,以适应指定的字符串。)

参数:
start - 起始索引(包含)。
end - 结束索引(不包含)。
str - 将替换原有内容的字符串。
返回:
此对象。
抛出:
StringIndexOutOfBoundsException - 如果 start 为负、大于 length() 或大于 end

insert

public StringBuilder insert(int index,
                            char[] str,
                            int offset,
                            int len)
str 数组参数的子数组的字符串表示形式插入此序列中。子数组从指定的 offset 开始,包含 lenchar。子数组的字符将被插入 index 所指示的位置。此序列的长度将加 lenchar

参数:
index - 要插入子数组的位置。
str - 一个 char 数组。
offset - 将插入子数组中的第一个 char 的索引。
len - 将插入子数组中的 char 的数量。
返回:
此对象
抛出:
StringIndexOutOfBoundsException - 如果 index 为负或大于 length();或者 offsetlen 为负;或者 (offset+len) 大于 str.length

insert

public StringBuilder insert(int offset,
Object obj)
Object 参数的字符串表示形式插入此字符序列中。

第二个参数将被转换成字符串,就好象使用了 String.valueOf 方法一样。然后,将所得字符串中的字符追加到此序列。

offset 参数必须大于等于 0,且小于等于此序列的长度。

参数:
offset - 偏移量。
obj - 一个 Object
返回:
此对象的一个引用。
抛出:
StringIndexOutOfBoundsException - 如果 offset 参数无效。
另请参见:
String.valueOf(java.lang.Object), insert(int, java.lang.String), length()

insert

public StringBuilder insert(int offset,
                            String str)
将字符串插入此字符序列。

按顺序将 String 参数中的字符插入此序列中的指定位置,将该位置处原来的字符向后推,此序列将增加该参数的长度。如果 strnull,则向此序列中追加 4 个字符 "null"

新字符序列在索引 k 处的字符有以下几种情况:

  • 如果 k 小于 offset,则等于原字符序列中索引 k 处的字符。
  • 如果 k 不小于 offset 但小于 offset+str.length(),则等于 str 参数中索引 k-offset 中的字符。
  • 如果 k 不小于 offset+str.length(),则等于原字符序列中索引 k-str.length() 处的字符

offset 参数必须大于等于 0,且小于等于此序列的长度。

参数:
offset - 偏移量。
str - 一个 string。
返回:
此对象的一个引用。
抛出:
StringIndexOutOfBoundsException - 如果 offset 参数无效。
另请参见:
length()