java StringBuilder insert()插入字符串

一、方法定义

public StringBuilder insert(int offset, Object obj)
public StringBuilder insert(int offset, String str)
public StringBuilder insert(int offset, char c)
public StringBuilder insert(int offset, boolean b)
public StringBuilder insert(int offset, int i)
public StringBuilder insert(int offset, long l)
public StringBuilder insert(int offset, float f)
public StringBuilder insert(int offset, double d)
public StringBuilder insert(int offset, char[] str)
public StringBuilder insert(int index, char[] str, int offset, int len)
public StringBuilder insert(int offset, CharSequence s)
public StringBuilder insert(int dstOffset, CharSequence s, int start, int end)

参数说明：

• offset / index / dstOffset：插入位置的索引（从0开始）
• obj：任意对象（调用其 toString() 方法插入）
• str：要插入的字符串
• c：要插入的字符
• b：布尔值
• i, l, f, d：基本数据类型
• char[] str：字符数组
• len：从字符数组中插入的字符数量
• s：实现 CharSequence 接口的对象（如 String、StringBuilder、StringBuffer 等）
• start, end：在 CharSequence 中要插入的子序列范围

返回值：

• 返回当前 StringBuilder 对象本身（支持链式调用）

---

二、功能说明

insert() 方法用于在 StringBuilder 对象的指定位置插入数据。插入后，原位置及其后的字符会向后移动。

核心功能：

• 在任意位置插入字符串、字符、基本类型、字符数组或字符序列
• 支持多种数据类型重载
• 原地修改，不创建新对象
• 返回 this，支持链式调用

---

三、示例代码

1. 基本使用示例

StringBuilder sb = new StringBuilder("Hello World");
sb.insert(5, " Beautiful"); // 在索引5处插入
System.out.println(sb); // 输出: Hello Beautiful World

sb.insert(0, "["); // 在开头插入
sb.insert(sb.length(), "]"); // 在末尾插入
System.out.println(sb); // 输出: [Hello Beautiful World]

2. 插入不同类型数据

StringBuilder sb = new StringBuilder("Score: ");

// 插入整数
sb.insert(7, 95);

// 插入布尔值
sb.insert(sb.length(), " Passed: ");
sb.insert(sb.length(), true);

// 插入字符
sb.insert(0, '['); // 开头插入
sb.append(']'); // 末尾追加

System.out.println(sb); // 输出: [Score: 95 Passed: true]

3. 插入字符数组

StringBuilder sb = new StringBuilder("Java");
char[] chars = {'S', 'c', 'r', 'i', 'p', 't'};
sb.insert(4, chars); // 插入整个字符数组
System.out.println(sb); // 输出: JavaScript

// 插入部分字符数组
char[] fullName = {'A', 'l', 'i', 'b', 'a', 'b', 'a'};
StringBuilder name = new StringBuilder("Hello ");
name.insert(6, fullName, 0, 3); // 插入前3个字符 "Ali"
System.out.println(name); // 输出: Hello Ali

4. 链式调用

StringBuilder sb = new StringBuilder();
sb.insert(0, "Year: ")
  .insert(6, 2025)
  .insert(sb.length(), " Month: ")
  .insert(sb.length(), "August");
System.out.println(sb); // 输出: Year: 2025 Month: August

---

四、使用技巧

1. 在开头插入：insert(0, data)

适用于构建逆序字符串或添加前缀。

// 逆序构建字符串
StringBuilder sb = new StringBuilder();
for (char c : "hello".toCharArray()) {
    sb.insert(0, c); // 从后往前插入
}
System.out.println(sb); // 输出: olleh

2. 在末尾插入：insert(length(), data) ≈ append(data)

虽然 append() 更高效，但在链式调用中可统一使用 insert。

3. 格式化插入：结合 String.format()

StringBuilder sb = new StringBuilder("User: ");
sb.insert(sb.length(), String.format("%s (ID: %04d)", "Alice", 123));
// 输出: User: Alice (ID: 0123)

4. 动态插入：根据条件插入内容

StringBuilder sb = new StringBuilder("Result: ");
if (score >= 60) {
    sb.insert(sb.length(), "Pass");
} else {
    sb.insert(sb.length(), "Fail");
}

---

五、常见错误

1. 索引越界异常

StringBuilder sb = new StringBuilder("Hi");
// 错误：索引为负数
// sb.insert(-1, "Hello"); // 抛出 StringIndexOutOfBoundsException

// 错误：索引超过长度
// sb.insert(3, "There"); // 长度为2，索引3越界

2. 空指针异常（较少见）

StringBuilder sb = new StringBuilder();
CharSequence nullSeq = null;
// sb.insert(0, nullSeq); // 插入 null 会变成字符串 "null"，不会抛异常
// 但如果在自定义 CharSequence 中未处理 null，可能出错

✅ 注意：insert() 插入 null 会将其转换为字符串 "null"，不会抛出 NullPointerException。

3. 混淆索引位置

StringBuilder sb = new StringBuilder("abc");
sb.insert(1, "X"); // 正确：在 'a' 和 'b' 之间插入 → "aXbc"
// 错误理解：以为在索引1的字符'b'处替换

---

六、注意事项

1. 索引范围：offset 必须满足 0 <= offset <= length()，否则抛出 StringIndexOutOfBoundsException。
2. null 值处理：插入 null 会变为字符串 "null"，而非空值。
3. 线程安全：StringBuilder 非线程安全，多线程环境下应使用 StringBuffer。
4. 原地修改：insert() 直接修改原对象，不返回新对象。
5. 性能考虑：频繁在中间插入会导致大量字符移动，影响性能。

---

七、最佳实践与性能优化

✅ 最佳实践

1. 优先使用 append()：若在末尾追加，使用 append() 比 insert(length(), data) 更清晰、高效。
2. 预估容量：使用 new StringBuilder(initialCapacity) 避免频繁扩容。
3. 链式调用：充分利用返回 this 的特性，提升代码可读性。
4. 避免在循环中频繁中间插入：尽量在末尾追加或重构逻辑。

⚠️ 性能优化建议

场景	推荐做法	原因
在末尾添加	使用 append()	更高效，语义清晰
在开头添加	谨慎使用 insert(0, ...)	每次插入需移动所有字符，O(n) 复杂度
大量中间插入	考虑逆序构建后反转	减少移动次数
已知最终长度	设置初始容量	避免内部数组扩容

示例：优化频繁开头插入

// ❌ 低效：每次插入都移动已有字符
StringBuilder bad = new StringBuilder();
for (int i = 0; i < 1000; i++) {
    bad.insert(0, i + " ");
}

// ✅ 高效：在末尾追加，最后反转
StringBuilder good = new StringBuilder();
for (int i = 0; i < 1000; i++) {
    good.append(i).append(" ");
}
good.reverse();

---

八、总结

StringBuilder.insert() 是一个强大且灵活的字符串操作方法，适用于在任意位置插入数据。掌握其使用要点，能显著提升字符串处理效率。

核心要点回顾：

项目	说明
功能	在指定位置插入字符串、字符、基本类型等
索引范围	0 <= offset <= length()
null 处理	插入 null 变为 "null" 字符串
返回值	返回 this，支持链式调用
性能	中间插入为 O(n)，避免频繁在开头插入
替代方案	末尾追加优先使用 append()

使用口诀：

开头插入要谨慎，末尾追加用 append；
索引越界会报错，null 变 "null" 要记牢；
链式调用很优雅，容量预设更高效。

通过合理使用 insert() 方法，结合 append() 和容量管理，可以高效构建复杂字符串，是 Java 字符串处理的必备技能。