java.lang
类 StringBuffer

java.lang.Object
  java.lang.StringBuffer

所有已实现的接口：

Serializable, Appendable, CharSequence

public final class StringBuffer
     

      extends 
      Object
     
     

      implements 
      Serializable, 
      CharSequence
     

线程安全的可变字符序列。一个类似于 String 的字符串缓冲区，但不能修改。虽然在任意时间点上它都包含某种特定的字符序列，但通过某些方法调用可以改变该序列的长度和内容。

可将字符串缓冲区安全地用于多个线程。可以在必要时对这些方法进行同步，因此任意特定实例上的所有操作就好像是以串行顺序发生的，该顺序与所涉及的每个线程进行的方法调用顺序一致。

StringBuffer 上的主要操作是 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) 具有相同的效果。

当发生与源序列有关的操作（如源序列中的追加或插入操作）时，该类只在执行此操作的字符串缓冲区上而不是在源上实现同步。

每个字符串缓冲区都有一定的容量。只要字符串缓冲区所包含的字符序列的长度没有超出此容量，就无需分配新的内部缓冲区数组。如果内部缓冲区溢出，则此容量自动增大。从 JDK 5 开始，为该类补充了一个单个线程使用的等价类，即 StringBuilder。与该类相比，通常应该优先使用 StringBuilder 类，因为它支持所有相同的操作，但由于它不执行同步，所以速度更快。

从以下版本开始：

JDK1.0

另请参见：

StringBuilder, String, 序列化表格

StringBuffer

public StringBuffer()

构造一个其中不带字符的字符串缓冲区，其初始容量为 16 个字符。

StringBuffer

public StringBuffer(int capacity)

构造一个不带字符，但具有指定初始容量的字符串缓冲区。

参数：

capacity - 初始容量。

抛出：

NegativeArraySizeException - 如果 capacity 参数小于 0。

StringBuffer

public StringBuffer(String str)

构造一个字符串缓冲区，并将其内容初始化为指定的字符串内容。该字符串的初始容量为 16 加上字符串参数的长度。

参数：

str - 缓冲区的初始内容。

抛出：

NullPointerException - 如果 str 为 null

StringBuffer

public StringBuffer(CharSequence seq)

public java.lang.StringBuilder(CharSequence seq) 构造一个字符串缓冲区，它包含与指定的 CharSequence 相同的字符。该字符串缓冲区的初始容量为 16 加上 CharSequence 参数的长度。

如果指定的 CharSequence 的长度小于或等于 0，则返回容量为 16 的空缓冲区。

参数：

seq - 要复制的序列。

抛出：

NullPointerException - 如果 seq 为 null

从以下版本开始：

1.5

length

public int length()

返回长度（字符数）。

指定者：

接口 CharSequence 中的 length

返回：

此对象表示的当前字符序列的长度。

capacity

public int capacity()

返回当前容量。容量指可用于最新插入的字符的存储量，超过这一容量就需要再次进行分配。

返回：

当前容量。

ensureCapacity

public void ensureCapacity(int minimumCapacity)

确保容量至少等于指定的最小值。如果当前容量小于 minimumCapacity 参数，则可分配一个具有更大容量的新的内部数组。新容量的大小应大于：

• minimumCapacity 参数。
• 旧容量的两倍加 2。

如果 minimumCapacity 参数为非正数，则此方法不执行任何操作并返回。

参数：

minimumCapacity - 所需的最小容量。

trimToSize

public void trimToSize()

尝试减少用于字符序列的存储空间。如果缓冲区大于保存当前字符序列所需的存储空间，则将重新调整其大小，以便更好地利用存储空间。调用此方法可能会影响后续调用 capacity() 方法时返回的值（但不要求如此）。

从以下版本开始：

1.5

setLength

public void setLength(int newLength)

设置字符序列的长度。序列将被更改为一个新的字符序列，新序列的长度由参数指定。对于每个小于 newLength 参数的非负索引 k，如果 k 小于原字符序列的长度，则新字符序列索引 k 处的字符与原字符序列索引 k 处的字符相同；否则，新字符序列索引 k 处的字符将是 null 字符 '\u0000'。换句话说，如果 newLength 参数小于当前长度，则长度将更改为指定的长度。

如果 newLength 参数大于或等于当前长度，则将追加有效的 null 字符 ('\u0000')，使长度满足 newLength 参数。

newLength 参数必须大于或等于 0。

参数：

newLength - 新长度

抛出：

IndexOutOfBoundsException - 如果 newLength 参数为负。

另请参见：

length()

charAt

public char charAt(int index)

返回此序列中指定索引处的 char 值。第一个 char 值在索引 0 处，第二个在索引 1 处，依此类推，这类似于数组索引。

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

如果索引处指定的 char 值是一个代理项，则返回该代理项的值。

指定者：

接口 CharSequence 中的 charAt

参数：

index - 所需 char 值的索引。

返回：

指定索引处的 char 值。

抛出：

IndexOutOfBoundsException - 如果 index 为负或大于等于 length()。

另请参见：

length()

codePointAt

public int codePointAt(int index)

返回指定索引处的字符（统一代码点）。该索引引用 char 值（Unicode 代码单元），其范围是从 0 到 length() - 1。

如果给定索引指定的 char 值属于高代理项范围，则后续索引小于此序列的长度；如果后续索引处的 char 值属于低代理项范围，则返回此代理项对 (surrogate pair) 对应的增补代码点。否则，返回给定索引处的 char 值。

参数：

index - char 值的索引。

返回：

index 处字符的代码点值。

从以下版本开始：

1.5

codePointBefore

public int codePointBefore(int index)

返回指定索引前的字符（统一代码点）。该索引引用 char 值（Unicode 代码单元），其范围是从 1 到 length()。

如果 (index - 1) 处的 char 值属于低代理项范围，则 (index - 2) 为非负；如果(index - 2) 处的 char 值属于高代理项范围，则返回该代理项对的增补代码点值。如果 index - 1 处的 char 值是未配对的低（高）代理项，则返回代理项值。

参数：

index - 应该返回的代码点之后的索引。

返回：

给定索引之前的 Unicode 代码点值。

从以下版本开始：

1.5

codePointCount

public int codePointCount(int beginIndex,
                          int endIndex)

返回此序列指定文本范围内的统一代码点。文本范围始于指定的 beginIndex，并扩展到索引 endIndex - 1 上的 char。因此文本范围的长度（ char 形式）为 endIndex-beginIndex。该序列中每个未配对的代理项都被作为一个代码点进行计数。

参数：

beginIndex - 文本范围的第一个 char 的索引。

endIndex - 文本范围的最后一个 char 之后的索引。

返回：

指定文本范围内的 Unicode 代码点的数量。

从以下版本开始：

1.5

offsetByCodePoints

public int offsetByCodePoints(int index,
                              int codePointOffset)

返回此序列中的索引，该索引是从给定 index 偏移 codePointOffset 个代码点后得到的。 index 和 codePointOffset 给出的文本范围内的不成对代理项是按一个代码点算作一个项进行计数的。

参数：

index - 将进行偏移的索引

codePointOffset - 用代码点计算的偏移量

返回：

此序列中的索引

从以下版本开始：

1.5

getChars

public void getChars(int srcBegin,
                     int srcEnd,
                     char[] dst,
                     int dstBegin)

将字符从此序列复制到目标字符数组 dst。要复制的第一个字符在索引 srcBegin 处；要复制的最后一个字符在索引 srcEnd-1 处。要复制的字符总数为 srcEnd-srcBegin。要复制到 dst 子数组的字符从索引 dstBegin 处开始，结束于以下索引：

 dstbegin + (srcEnd-srcBegin) - 1
 

参数：

srcBegin - 从此偏移量处开始复制。

srcEnd - 在此偏移量处停止复制。

dst - 用来保存复制数据的数组。

dstBegin - dst 中的偏移量。

抛出：

NullPointerException - 如果 dst 为 null。

IndexOutOfBoundsException - 如果以下任意一项为 true：

• srcBegin 为负
• dstBegin 为负
• srcBegin 参数大于 srcEnd 参数。
• srcEnd 大于 this.length()。
• dstBegin+srcEnd-srcBegin 大于 dst.length

setCharAt

public void setCharAt(int index,
                      char ch)

将给定索引处的字符设置为 ch。此序列将被转换，以表示等同于原字符序列的新字符序列，唯一的不同在于新序列在 index 处包含 ch。

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

参数：

index - 要修改的字符的索引。

ch - 新字符。

抛出：

IndexOutOfBoundsException - 如果 index 为负或大于等于 length()。

另请参见：

length()

append

public StringBuffer append(Object obj)

追加 Object 参数的字符串表示形式。

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

参数：

obj - 一个 Object。

返回：

此对象的一个引用。

另请参见：

String.valueOf(java.lang.Object), append(java.lang.String)

append

public StringBuffer append(String str)

将指定的字符串追加到此字符序列。

按顺序追加 String 变量中的字符，使此序列增加该变量的长度。如果 str 为 null，则追加 4 个字符 "null"。

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

参数：

str - 一个 string。

返回：

此对象的一个引用。

append

public StringBuffer append(StringBuffer sb)

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

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

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

该方法在 this（目标）对象上实现同步，但不在源（sb）上实现同步。

参数：

sb - 要追加的 StringBuffer。

返回：

该对象的一个引用。

从以下版本开始：

1.4

append

public StringBuffer append(CharSequence s)

将指定的 CharSequence 追加到该序列。

按顺序将 CharSequence 参数中的字符追加到该序列中，使该序列增加该参数的长度。

该方法的结果与调用 this.append(s, 0, s.length()) 的结果完全相同；

该方法在 this（目标）对象上实现同步，但不在源（s）上实现同步。

如果 s 为 null，则追加 4 个 "null" 字符。

指定者：

接口 Appendable 中的 append

参数：

s - 要追加的 CharSequence。

返回：

此对象的一个引用。

从以下版本开始：

1.5

append

public StringBuffer 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()

从以下版本开始：

1.5

append

public StringBuffer append(char[] str)

将 char 数组参数的字符串表示形式追加到此序列。

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

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

参数：

str - 要追加的字符。

返回：

此对象的一个引用。

append

public StringBuffer append(char[] str,
                           int offset,
                           int len)

将 char 数组参数的子数组的字符串表示形式追加到此序列。

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

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

参数：

str - 要追加的字符。

offset - 要追加的第一个 char 的索引。

len - 要追加的 char 的数量。

返回：

此对象的一个引用。

append

public StringBuffer append(boolean b)

将 boolean 参数的字符串表示形式追加到序列。

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

参数：

b - 一个 boolean 值。

返回：

此对象的一个引用。

另请参见：

String.valueOf(boolean), append(java.lang.String)

append

public StringBuffer append(char c)

将 char 参数的字符串表示形式追加到此序列。

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

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

指定者：

接口 Appendable 中的 append

参数：

c - 一个 char 值。

返回：

此对象的一个引用。

append

public StringBuffer append(int i)

将 int 参数的字符串表示形式追加到此序列。

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

参数：

i - 一个 int 值。

返回：

此对象的一个引用。

另请参见：

String.valueOf(int), append(java.lang.String)

appendCodePoint

public StringBuffer appendCodePoint(int codePoint)

将 codeP