StringBuilder .insert() Method Tutorial

In this tutorial I will talk about the insert() method. The insert method inserts the value of the parameter into the value of the current StringBuilder object at a specified position. There are a dozen overloaded versions of the insert() method that will allow you to pass in quite a few data types. For example, the insert(int offset, String str) method works like this:
StringBuilder sb = new StringBuilder("0123456789");
sb.insert(4, "ABC");
// 0123ABC456789
The offset parameter is the index of the character sequence of the current StringBuilder object, the insertion will take place after the character specified by the offset. In this case 4 tells the method to insert the String parameter after the character located at the forth index. If you attempt to insert something at an invalid offset, the method will throw a StringIndexOutOfBoundsException.

Notice that the insert method changed the value (state) of the StringBuilder object from "0123456789" to "0123ABC456789" without re-assigning the sb reference variable to a new object. This is because StringBuilder objects are mutable – meaning that the value of a StringBuilder object can be changed.
If you are unfamiliar with the difference between mutable and immutable objects, please watch my StringBuilder Introduction Tutorial.

The following is a list of the various overloaded versions of the insert method:

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

Open the command prompt (CMD - see the Getting Started ) and type in the following commands.

C:\Windows\System32>cd \
C:\>md Java
C:\>cd Java
C:\Java>md StringBuilderInsert
C:\Java>cd StringBuilderInsert

Copy and Paste, or type the following code into Notepad and be sure to save the file when you are done.

class StringBuilderInsert {
    public static void main(String args[]) {
        StringBuilder sb = new StringBuilder("0123456789");
        boolean b = true;
        sb.insert(3, b);
        System.out.println("insert(int offset, boolean b) = "  + sb);
        sb = new StringBuilder("0123456789");

        char c = '$';
        sb.insert(8, c);
        System.out.println("insert(int offset, char c) = "  + sb);
        sb = new StringBuilder("0123456789");

        char cArray[] = { 'H', 'E', 'L', 'L', 'O' };
        sb.insert(5, cArray);
        System.out.println("insert(int offset, char[] str) = "  + sb);
        sb = new StringBuilder("0123456789");

        sb.insert(5, cArray, 3, 2);
        System.out.println("insert(int index, char[] str, int offset, int len) = "  + sb);
        sb = new StringBuilder("0123456789");

        CharSequence cs1 = new String("java");
        sb.insert(5, cs1);
        System.out.println("insert(int dstOffset, CharSequence s) = "  + sb);
        sb = new StringBuilder("0123456789");

        CharSequence cs2 = new StringBuilder("HELLO");
        sb.insert(5, cs2, 3, 5);
        System.out.println("insert(int dstOffset, CharSequence s, int start, int end) = "  + sb);
        sb = new StringBuilder("0123456789");

        double d = 777.77;
        sb.insert(0, d);
        System.out.println("insert(int offset, double d) = "  + sb);
        sb = new StringBuilder("0123456789");

        float f = 555.55f;
        sb.insert(10, f);
        System.out.println("insert(int offset, float f) = "  + sb);
        sb = new StringBuilder("0123456789");

        int i = 432123;
        sb.insert(4, i);
        System.out.println("insert(int offset, int i) = "  + sb);
        sb = new StringBuilder("0123456789");

        long L = 8888888888888888888L;
        sb.insert(1, L);
        System.out.println("insert(int offset, long l) = "  + sb);
        sb = new StringBuilder("0123456789");

        Object o = new NullPointerException();
        sb.insert(5, o);
        System.out.println("insert(int offset, Object obj) = "  + sb);
        sb = new StringBuilder("0123456789");

        String s = new String("my string");
        sb.insert(3, s);
        System.out.println("insert(int offset, String str) = "  + sb);
        sb = new StringBuilder("0123456789");

Now switch back to the command prompt (CMD) and type in javac and press Enter.
Now type in java StringBuilderInsert and press Enter.

C:\Java\StringBuilderInsert>java StringBuilderInsert
insert(int offset, boolean b) = 012true3456789
insert(int offset, char c) = 01234567$89
insert(int offset, char[] str) = 01234HELLO56789
insert(int index, char[] str, int offset, int len) = 01234LO56789
insert(int dstOffset, CharSequence s) = 01234java56789
insert(int dstOffset, CharSequence s, int start, int end) = 01234LO56789
insert(int offset, double d) = 777.770123456789
insert(int offset, float f) = 0123456789555.55
insert(int offset, int i) = 0123432123456789
insert(int offset, long l) = 08888888888888888888123456789
insert(int offset, Object obj) = 01234java.lang.NullPointerException56789
insert(int offset, String str) = 012my string3456789

Final thoughts

There will be no String class comparisons in this tutorial because the String class does not have an equivalent insert method.