StringBuilder

java.lang.Object

|---java.lang.StringBuilder

public final class StringBuilder
extends Object
implements Appendable, CharSequence, Serializable

可变的字符序列。此类提供与 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。

除非另有说明，否则将 null 参数传递给此类中的构造函数或方法将导致抛出 NullPointerException。

构造函数摘要

构造函数	描述
StringBuilder()	构造一个其中没有字符且初始容量为 16 个字符的字符串构建器。
StringBuilder(int capacity)	构造一个字符串构建器，其中没有字符，初始容量由容量参数指定。
StringBuilder(CharSequence seq)	构造一个字符串构建器，该构建器包含与指定 CharSequence 相同的字符。
StringBuilder(String str)	构造一个初始化为指定字符串内容的字符串构建器。

方法总结

修饰符和类型	方法	描述
StringBuilder	append(boolean b)
StringBuilder	append(char c)	将指定的字符附加到此 Appendable。
StringBuilder	append(char[] str)
StringBuilder	append(char[] str, int offset, int len)
StringBuilder	append(double d)
StringBuilder	append(float f)
StringBuilder	append(int i)
StringBuilder	append(long lng)
StringBuilder	append(CharSequence s)	将指定的字符序列附加到此 Appendable。
StringBuilder	append(CharSequence s, int start, int end)	将指定字符序列的子序列附加到此 Appendable。
StringBuilder	append(Object obj)
StringBuilder	append(String str)
StringBuilder	append(StringBuffer sb)	将指定的 StringBuffer 附加到此序列。
StringBuilder	appendCodePoint(int codePoint)
int	capacity()	返回当前容量。
char	charAt(int index)	返回此序列中指定索引处的 char 值。
int	codePointAt(int index)	返回指定索引处的字符（Unicode 代码点）。
int	codePointBefore(int index)	返回指定索引之前的字符（Unicode 代码点）。
int	codePointCount(int beginIndex, int endIndex)	返回此序列的指定文本范围内的 Unicode 代码点数。
StringBuilder	delete(int start, int end)
StringBuilder	deleteCharAt(int index)
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)
StringBuilder	insert(int offset, char c)
StringBuilder	insert(int offset, char[] str)
StringBuilder	insert(int index, char[] str, int offset, int len)
StringBuilder	insert(int offset, double d)
StringBuilder	insert(int offset, float f)
StringBuilder	insert(int offset, int i)
StringBuilder	insert(int offset, long l)
StringBuilder	insert(int dstOffset, CharSequence s)
StringBuilder	insert(int dstOffset, CharSequence s, int start, int end)
StringBuilder	insert(int offset, Object obj)
StringBuilder	insert(int offset, String str)
int	lastIndexOf(String str)
int	lastIndexOf(String str, int fromIndex)
int	length()	返回长度（字符数）。
int	offsetByCodePoints(int index, int codePointOffset)	返回此序列中从给定索引偏移 codePointOffset 代码点的索引。
StringBuilder	replace(int start, int end, String str)
StringBuilder	reverse()
void	setCharAt(int index, char ch)	指定索引处的字符设置为 ch。
void	setLength(int newLength)	设置字符序列的长度。
CharSequence	subSequence(int start, int end)	返回一个新的字符序列，它是该序列的子序列。
String	substring(int start)	返回一个新字符串，其中包含当前包含在此字符序列中的字符子序列。
String	substring(int start, int end)	返回一个新字符串，该字符串包含当前包含在此序列中的字符子序列。
String	toString()	返回对象的字符串表示形式。
void	trimToSize()	尝试减少用于字符序列的存储空间。

从接口 java.lang.CharSequence 继承的方法
chars, codePoints

从类 java.lang.Object 继承的方法
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

构造函数详细信息

StringBuilder

public StringBuilder()

构造一个其中没有字符且初始容量为 16 个字符的字符串构建器。

StringBuilder

public StringBuilder(int capacity)

构造一个字符串构建器，其中没有字符，初始容量由容量参数指定。

参数：

参数名称	参数描述
capacity	初始容量。

Throws:

Throw名称	Throw描述
NegativeArraySizeException	如果容量参数小于 0。

StringBuilder

public StringBuilder(String str)

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

参数：

参数名称	参数描述
str	缓冲区的初始内容。

StringBuilder

public StringBuilder(CharSequence seq)

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

参数：

参数名称	参数描述
seq	要复制的序列。

方法详情

append

public StringBuilder append(Object obj)

append

public StringBuilder append(String str)

append

public StringBuilder append(StringBuffer sb)

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

StringBuffer 参数的字符按顺序附加到此序列，此序列的长度增加参数的长度。 如果 sb 为空，则将四个字符“null”附加到此序列中。

设 n 为该字符序列在执行 append 方法之前的长度。 那么如果k小于n，则新字符序列中索引k处的字符等于旧字符序列中索引k处的字符； 否则，它等于参数 sb 中索引 k-n 处的字符。

参数：

参数名称	参数描述
sb	要附加的 StringBuffer。

返回:

对该对象的引用。

append

public StringBuilder append(CharSequence s)

从接口复制的描述：可附加

将指定的字符序列附加到此 Appendable。

根据哪个类实现了字符序列 csq，可能不会附加整个序列。 例如，如果 csq 是一个 CharBuffer，那么要追加的子序列由缓冲区的位置和限制定义。

指定者：

在接口 Appendable 中追加

参数：

参数名称	参数描述
s	要追加的字符序列。 如果 csq 为 null，则将四个字符“null”附加到此 Appendable。

返回:

对本附录的引用

append

public StringBuilder append(CharSequence s, int start, int end)

从接口复制的描述：可附加

将指定字符序列的子序列附加到此 Appendable。

当 csq 不为空时，以 out.append(csq, start, end) 形式调用此方法的行为与调用完全相同

     out.append(csq.subSequence(start, end)) 

指定者：

在接口 Appendable 中追加

参数：

参数名称	参数描述
s	从中追加子序列的字符序列。 如果 csq 为 null，则将附加字符，就好像 csq 包含四个字符“null”。
start	子序列中第一个字符的索引
end	子序列中最后一个字符之后的字符的索引

返回:

对本附录的引用

Throws:

Throw名称	Throw描述
IndexOutOfBoundsException	如果 start 或 end 为负数，则 start 大于 end，或者 end 大于 csq.length()

append

public StringBuilder append(char[] str)

append

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

Throws:

Throw名称	Throw描述
IndexOutOfBoundsException

append

public StringBuilder append(boolean b)

append

public StringBuilder append(char c)

从接口复制的描述：可附加

将指定的字符附加到此 Appendable。

指定者：

在接口 Appendable 中追加

参数：

参数名称	参数描述
c	要附加的字符

返回:

对本附录的引用

append

public StringBuilder append(int i)

append

public StringBuilder append(long lng)

append

public StringBuilder append(float f)

append

public StringBuilder append(double d)

appendCodePoint

public StringBuilder appendCodePoint(int codePoint)

delete

public StringBuilder delete(int start, int end)

Throws:

Throw名称	Throw描述
StringIndexOutOfBoundsException

deleteCharAt

public StringBuilder deleteCharAt(int index)

Throws:

Throw名称	Throw描述
StringIndexOutOfBoundsException

replace

public StringBuilder replace(int start, int end, String str)

Throws:

Throw名称	Throw描述
StringIndexOutOfBoundsException

insert

public StringBuilder insert(int index, char[] str, int offset, int len)

Throws:

Throw名称	Throw描述
StringIndexOutOfBoundsException

insert

public StringBuilder insert(int offset, Object obj)

Throws:

Throw名称	Throw描述
StringIndexOutOfBoundsException

insert

public StringBuilder insert(int offset, String str)

Throws:

Throw名称	Throw描述
StringIndexOutOfBoundsException

insert

public StringBuilder insert(int offset, char[] str)

Throws:

Throw名称	Throw描述
StringIndexOutOfBoundsException

insert

public StringBuilder insert(int dstOffset, CharSequence s)

Throws:

Throw名称	Throw描述
IndexOutOfBoundsException

insert

public StringBuilder insert(int dstOffset, CharSequence s, int start, int end)

Throws:

Throw名称	Throw描述
IndexOutOfBoundsException

insert

public StringBuilder insert(int offset, boolean b)

Throws:

Throw名称	Throw描述
StringIndexOutOfBoundsException

insert

public StringBuilder insert(int offset, char c)

Throws:

Throw名称	Throw描述
IndexOutOfBoundsException

insert

public StringBuilder insert(int offset, int i)

Throws:

Throw名称	Throw描述
StringIndexOutOfBoundsException

insert

public StringBuilder insert(int offset, long l)

Throws:

Throw名称	Throw描述
StringIndexOutOfBoundsException

insert

public StringBuilder insert(int offset, float f)

Throws:

Throw名称	Throw描述
StringIndexOutOfBoundsException

insert

public StringBuilder insert(int offset, double d)

Throws:

Throw名称	Throw描述
StringIndexOutOfBoundsException

indexOf

public int indexOf(String str)

indexOf

public int indexOf(String str, int fromIndex)

lastIndexOf

public int lastIndexOf(String str)

lastIndexOf

public int lastIndexOf(String str, int fromIndex)

reverse

public StringBuilder reverse()

toString

public String toString()

从类复制的描述：对象

返回对象的字符串表示形式。 通常，toString 方法返回一个“以文本方式表示”该对象的字符串。 结果应该是一个简洁但信息丰富的表示，易于人们阅读。 建议所有子类重写此方法。

Object 类的 toString 方法返回一个字符串，该字符串由对象作为其实例的类的名称、at 符号字符“@”和对象哈希码的无符号十六进制表示形式组成。 换句话说，此方法返回一个等于以下值的字符串：

 getClass().getName() + '@' + Integer.toHexString(hashCode()) 

指定者：

接口 CharSequence 中的 toString

覆盖：

类 Object 中的 toString

返回:

对象的字符串表示形式。

trimToSize

public void trimToSize()

尝试减少用于字符序列的存储空间。 如果缓冲区大于保存其当前字符序列所需的大小，则可以调整其大小以提高空间效率。 调用此方法可能（但不是必须）影响后续调用 capacity() 方法返回的值。

codePointAt

public int codePointAt(int index)

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

如果给定索引处指定的 char 值在高代理范围内，后续索引小于此序列的长度，并且后续索引处的 char 值在低代理范围内，则补充代码点 返回对应于这个代理对。 否则，返回给定索引处的 char 值。

参数：

参数名称	参数描述
index	char 值的索引

返回:

索引处字符的代码点值

Throws:

Throw名称	Throw描述
IndexOutOfBoundsException	如果 index 参数为负数或不小于此序列的长度。

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。

Throws:

Throw名称	Throw描述
IndexOutOfBoundsException	如果以下任何一项为真：srcBegin 为负 dstBegin 为负 srcBegin 参数大于 srcEnd 参数。srcEnd 大于 this.length().dstBegin+srcEnd-srcBegin 大于 dst.length

length

public int length()

返回长度（字符数）。

指定者：

接口 CharSequence 中的长度

返回:

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

setCharAt

public void setCharAt(int index, char ch)

指定索引处的字符设置为 ch。 这个序列被改变以表示一个与旧字符序列相同的新字符序列，除了它在位置索引处包含字符 ch。

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

参数：

参数名称	参数描述
index	要修改的字符的索引。
ch	新character。

Throws:

Throw名称	Throw描述
IndexOutOfBoundsException	如果 index 为负数或大于或等于 length()。

subSequence

public CharSequence subSequence(int start, int end)

返回一个新的字符序列，它是该序列的子序列。

调用表单的这个方法

 sb.subSequence(begin, end)

行为方式与调用完全相同

 sb.substring(begin, end)

提供这个方法是为了这个类可以实现 CharSequence 接口。

指定者：

接口 CharSequence 中的子序列

参数：

参数名称	参数描述
start	起始索引，包括在内。
end	结束索引，独占。

返回:

指定的子序列。

Throws:

Throw名称	Throw描述
IndexOutOfBoundsException	如果 start 或 end 为负数，如果 end 大于 length()，或者如果 start 大于 end

substring

public String substring(int start)

返回一个新字符串，其中包含当前包含在此字符序列中的字符子序列。 子字符串从指定的索引开始并延伸到此序列的末尾。

参数：

参数名称	参数描述
start	起始索引，包括在内。

返回:

新字符串。

Throws:

Throw名称	Throw描述
StringIndexOutOfBoundsException	如果 start 小于零，或大于此对象的长度。

substring

public String substring(int start, int end)

返回一个新字符串，该字符串包含当前包含在此序列中的字符子序列。 子字符串从指定的 start 开始并延伸到索引 end - 1 处的字符。

参数：

参数名称	参数描述
start	起始索引，包括在内。
end	结束索引，独占。

返回:

新字符串。

Throws:

Throw名称	Throw描述
StringIndexOutOfBoundsException	如果 start 或 end 为负数或大于 length()，或者 start 大于 end。

capacity

public int capacity()

返回当前容量。 容量是可用于新插入字符的存储量，超出该容量将发生分配。

返回:

当前容量

setLength

public void setLength(int newLength)

设置字符序列的长度。 该序列更改为长度由参数指定的新字符序列。 对于每个小于newLength的非负索引k，如果k小于旧字符序列的长度，则新字符序列中索引k处的字符与旧序列中索引k处的字符相同； 否则，它是空字符'\u0000'。 换言之，如果 newLength 参数小于当前长度，则将长度更改为指定长度。

如果 newLength 参数大于或等于当前长度，则附加足够的空字符 ('\u0000')，以便长度成为 newLength 参数。

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

参数：

参数名称	参数描述
newLength	新长度

Throws:

Throw名称	Throw描述
IndexOutOfBoundsException	如果 newLength 参数为负数。

ensureCapacity

public void ensureCapacity(int minimumCapacity)

确保容量至少等于指定的最小值。 如果当前容量小于参数，则分配具有更大容量的新内部数组。 新容量是以下两者中的较大者：

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

如果 minimumCapacity 参数为非正数，则此方法不执行任何操作并简单地返回。 请注意，对该对象的后续操作可能会将实际容量减少到此处请求的容量以下。

参数：

参数名称	参数描述
minimumCapacity	所需的最小容量。

codePointBefore

public int codePointBefore(int index)

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

如果 (index - 1) 处的 char 值在低代理范围内，(index - 2) 不为负，并且 (index - 2) 处的 char 值在高代理范围内，则补充代码点 返回代理对的值。 如果索引 - 1 处的 char 值是未配对的低代理或高代理，则返回代理值。

参数：

参数名称	参数描述
index	应返回的代码点之后的索引

返回:

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

Throws:

Throw名称	Throw描述
IndexOutOfBoundsException	如果 index 参数小于 1 或大于此序列的长度。

charAt

public char charAt(int index)

返回此序列中指定索引处的 char 值。 第一个 char 值在索引 0 处，下一个在索引 1 处，依此类推，就像在数组索引中一样。

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

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

指定者：

接口 CharSequence 中的 charAt

参数：

参数名称	参数描述
index	所需 char 值的索引。

返回:

指定索引处的 char 值。

Throws:

Throw名称	Throw描述
IndexOutOfBoundsException	如果 index 为负数或大于或等于 length()。

codePointCount

public int codePointCount(int beginIndex, int endIndex)

返回此序列的指定文本范围内的 Unicode 代码点数。 文本范围从指定的 beginIndex 开始并扩展到索引 endIndex - 1 处的字符。因此，文本范围的长度（以字符为单位）为 endIndex-beginIndex。 此序列中的未配对代理各自计为一个代码点。

参数：

参数名称	参数描述
beginIndex	文本范围的第一个字符的索引。
endIndex	文本范围的最后一个字符之后的索引。

返回:

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

Throws:

Throw名称	Throw描述
IndexOutOfBoundsException	如果 beginIndex 为负数，或者 endIndex 大于此序列的长度，或者 beginIndex 大于 endIndex。

offsetByCodePoints

public int offsetByCodePoints(int index, int codePointOffset)

返回此序列中从给定索引偏移 codePointOffset 代码点的索引。 由 index 和 codePointOffset 给出的文本范围内的未配对代理分别计为一个代码点。

参数：

参数名称	参数描述
index	要偏移的索引
codePointOffset	代码点的偏移量

返回:

此序列中的索引

Throws:

Throw名称	Throw描述
IndexOutOfBoundsException	如果 index 为负或大于此序列的长度，或者如果 codePointOffset 为正并且以 index 开头的子序列的代码点少于 codePointOffset，或者如果 codePointOffset 为负并且 index 之前的子序列小于 codePointOffset 代码的绝对值 点。