java.lang
类 StringBuilder

java.lang.Object
  java.lang.StringBuilder

所有已实现的接口：

Serializable, Appendable, CharSequence

public final class StringBuilder
     

      extends 
      Object
     
     

      implements 
      Serializable, 
      CharSequence
     

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

在 StringBuilder 上的主要操作是 append 和 insert 方法，可重载这些方法，以接受任意类型的数据。每个方法都能有效地将给定的数据转换成字符串，然后将该字符串的字符追加或插入到字符串生成器中。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

public StringBuilder()

构造一个不带任何字符的字符串生成器，其初始容量为 16 个字符。

StringBuilder

public StringBuilder(int capacity)

构造一个不带任何字符的字符串生成器，其初始容量由 capacity 参数指定。

参数：

capacity - 初始容量。

抛出：

NegativeArraySizeException - 如果 capacity 参数小于 0。

StringBuilder

public StringBuilder(String str)

构造一个字符串生成器，并初始化为指定的字符串内容。该字符串生成器的初始容量为 16 加上字符串参数的长度。

参数：

str - 缓冲区的初始内容。

抛出：

NullPointerException - 如果 str 为 null

StringBuilder

public StringBuilder(CharSequence seq)

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

参数：

seq - 要复制的序列。

抛出：

NullPointerException - 如果 seq 为 null

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 变量中的字符，此序列将增加该变量的长度。如果 str 为 null，则追加 4 个字符 "null"。

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

参数：

str - 一个 string。

返回：

此对象的一个引用。

append

public StringBuilder append(StringBuffer sb)

将指定的 StringBuffer 追加到此序列。

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

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

参数：

sb - 要追加的 StringBuffer。

返回：

此对象的一个引用。

append

public StringBuilder append(CharSequence s)

从接口 Appendable 复制的描述

向此 Appendable 追加指定的字符序列。

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

指定者：

接口 Appendable 中的 append

参数：

s - 要追加的字符串序列。如果 csq 为 null，则向该 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 处的字符。

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

指定者：

接口 Appendable 中的 append

参数：

s - 要追加的序列。

start - 要追加的子序列的起始索引。

end - 要追加的子序列的结束索引。

返回：

此对象的一个引用。

抛出：

IndexOutOfBoundsException 如果 start 或 end 为负；或者 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 开始，包含 len 个 char。子数组的字符将被插入 index 所指示的位置。此序列的长度将加 len 个 char。

参数：

index - 要插入子数组的位置。

str - 一个 char 数组。

offset - 将插入子数组中的第一个 char 的索引。

len - 将插入子数组中的 char 的数量。

返回：

此对象

抛出：

StringIndexOutOfBoundsException - 如果 index 为负或大于 length()；或者 offset 或 len 为负；或者 (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 参数中的字符插入此序列中的指定位置，将该位置处原来的字符向后推，此序列将增加该参数的长度。如果 str 为 null，则向此序列中追加 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()