StringBufferClass.java

package Phase2_MethodsArraysStrings.Strings;

/**
 * StringBuffer - Mutable, Thread-Safe Character Sequence
 * ------------------------------------------------------
 * StringBuffer (since Java 1.0) is a MUTABLE counterpart to String. You can
 * append, insert, delete, or modify characters in place without creating
 * new objects.
 * <p>
 *
 *      StringBuffer sb = new StringBuffer("Hello");
 *      sb.append(", World").append("!");
 *      // sb now contains "Hello, World!"
 * <p>
 *
 * Key Properties
 * --------------
 *  - MUTABLE        - methods modify the buffer in place and return `this`
 *                     for chaining.
 *  - THREAD-SAFE    - every public method is `synchronized` - safe to use
 *                     from multiple threads without external locking.
 *  - SLOWER than    - the synchronisation has a cost; if you only use the
 *    StringBuilder    buffer from one thread, prefer StringBuilder.
 *  - GROWS AUTOMATIC- has an internal char[] that doubles in size when full.
 * <p>
 *
 * When To Use It
 * --------------
 *  - You are mutating a shared buffer from MULTIPLE THREADS.
 *  - You need a method signature returning AbstractStringBuilder semantics.
 *  - Otherwise (the common case), use StringBuilder.
 * <p>
 *
 * Common Methods - Quick Catalogue
 * --------------------------------
 *      Constructors
 *          new StringBuffer()                empty, capacity 16
 *          new StringBuffer(int cap)         empty, custom capacity
 *          new StringBuffer(String s)        seeded with s, capacity = s.length()+16
 *          new StringBuffer(CharSequence)    seeded with any CharSequence
 * <p>
 *
 *      Length & capacity
 *          length()                          number of characters
 *          capacity()                        size of the internal array
 *          ensureCapacity(int min)           grow if necessary
 *          trimToSize()                      shrink the internal array
 *          setLength(int n)                  truncate or pad with ''
 * <p>
 *
 *      Append (overloaded for almost every type)
 *          append(String|char[]|char|int|long|float|double|boolean|Object|CharSequence)
 * <p>
 *
 *      Insert (always at a given index)
 *          insert(int offset, anyType)
 * <p>
 *
 *      Replace / delete
 *          replace(int start, int end, String s)
 *          delete(int start, int end)
 *          deleteCharAt(int index)
 * <p>
 *
 *      Reverse / read / set
 *          reverse()
 *          charAt(int) / codePointAt(int) / getChars(...)
 *          setCharAt(int index, char c)
 * <p>
 *
 *      Search
 *          indexOf(String) / indexOf(String, fromIndex)
 *          lastIndexOf(String) / lastIndexOf(String, fromIndex)
 * <p>
 *
 *      Sub-sequences and output
 *          substring(int start) / substring(int start, int end)
 *          subSequence(int start, int end)
 *          toString()
 * <p>
 *
 *      Java 21
 *          chars() / codePoints()                  - IntStream views
 *          compareTo(StringBuffer)                 - lexicographic compare
 *          isEmpty()                               - convenience added in 15
 * <p>
 *
 * Each method appears below with a tiny worked example.
 */

public class StringBufferClass {

    public static void main(String[] args) {

        section("Constructors & basics");
        StringBuffer empty = new StringBuffer();              // capacity 16
        StringBuffer sized = new StringBuffer(64);            // capacity 64
        StringBuffer fromS = new StringBuffer("Hello");       // seeded
        System.out.println("empty.length()     = " + empty.length());
        System.out.println("empty.capacity()   = " + empty.capacity());
        System.out.println("sized.capacity()   = " + sized.capacity());
        System.out.println("fromS              = " + fromS);
        System.out.println("fromS.capacity()   = " + fromS.capacity());   // 5 + 16 = 21

        section("append() - overloaded for every type");
        StringBuffer a = new StringBuffer();
        a.append("Hello")
         .append(' ')
         .append("world ")
         .append(123)
         .append(' ')
         .append(true)
         .append(' ')
         .append(3.14);
        System.out.println("after append chain  = " + a);

        section("insert() at an index");
        StringBuffer b = new StringBuffer("Hello World");
        b.insert(5, ",");
        b.insert(0, ">> ");
        System.out.println("after insert        = " + b);

        section("replace() / delete() / deleteCharAt()");
        StringBuffer c = new StringBuffer("Hello, World!");
        c.replace(7, 12, "Java");
        System.out.println("after replace       = " + c);     // Hello, Java!
        c.delete(5, 7);
        System.out.println("after delete        = " + c);     // HelloJava!
        c.deleteCharAt(c.length() - 1);
        System.out.println("after deleteCharAt  = " + c);     // HelloJava

        section("reverse()");
        StringBuffer r = new StringBuffer("abcdef");
        r.reverse();
        System.out.println("after reverse       = " + r);     // fedcba

        section("setCharAt() / charAt()");
        StringBuffer m = new StringBuffer("Java");
        m.setCharAt(0, 'L');
        System.out.println("after setCharAt(0,L)= " + m);     // Lava
        System.out.println("charAt(2)           = " + m.charAt(2));

        section("indexOf() / lastIndexOf()");
        StringBuffer i = new StringBuffer("abracadabra");
        System.out.println("indexOf('a')        = " + i.indexOf("a"));        // 0
        System.out.println("indexOf('a', 1)     = " + i.indexOf("a", 1));     // 3
        System.out.println("lastIndexOf('a')    = " + i.lastIndexOf("a"));    // 10
        System.out.println("indexOf('xyz')      = " + i.indexOf("xyz"));      // -1

        section("substring() / subSequence()");
        StringBuffer s = new StringBuffer("Hello, World");
        System.out.println("substring(7)        = " + s.substring(7));        // World
        System.out.println("substring(7,12)     = " + s.substring(7, 12));    // World
        System.out.println("subSequence(7,12)   = " + s.subSequence(7, 12));  // World

        section("length() / capacity() / ensureCapacity() / trimToSize() / setLength()");
        StringBuffer cap = new StringBuffer();
        System.out.println("initial capacity    = " + cap.capacity());     // 16
        cap.append("0123456789ABCDEF").append("!");
        System.out.println("after 17 chars cap  = " + cap.capacity());     // grew
        cap.ensureCapacity(200);
        System.out.println("after ensureCapacity= " + cap.capacity());
        cap.trimToSize();
        System.out.println("after trimToSize    = " + cap.capacity());
        cap.setLength(4);
        System.out.println("after setLength(4)  = '" + cap + "' (length=" + cap.length() + ")");

        section("toString() - hand off to immutable String");
        StringBuffer t = new StringBuffer("compose").append(" me");
        String built = t.toString();
        System.out.println("String built        = " + built);

        section("chars() / codePoints() - Java 9 streams");
        new StringBuffer("hi!").chars().forEach(ch -> System.out.print(ch + " "));
        System.out.println();

        section("compareTo() / isEmpty() - Java 11+ / 15+");
        StringBuffer p = new StringBuffer("apple");
        StringBuffer q = new StringBuffer("banana");
        System.out.println("p.compareTo(q)      = " + p.compareTo(q));     // negative
        System.out.println("empty.isEmpty()     = " + empty.isEmpty());

        section("THREAD-SAFE - many threads, one buffer");
        StringBuffer shared = new StringBuffer();
        Runnable task = () -> {
            for (int k = 0; k < 1000; k++) shared.append('x');
        };
        Thread t1 = new Thread(task);
        Thread t2 = new Thread(task);
        t1.start(); t2.start();
        try { t1.join(); t2.join(); } catch (InterruptedException ignored) {}
        System.out.println("shared length after 2 threads x 1000 appends = " + shared.length()); // 2000

        // OUTPUT (representative - line for line matches the inline comments)
    }

    private static void section(String title) {
        System.out.println("\n====== " + title + " ======");
    }
}