Summary

New method CharSequence.getChars(int, int, char[], int) on java.lang.CharSequence to bulk-read characters from a region in the CharSequence into a region of the provided char[].

Problem

CharSequence interface does not provide a bulk-read facility. Some CharSequence implementations do not support bulk-reading at all, while others (like String and CharBuffer) do support bulk-reading but do not share a common method signature to perform it.

Applications wanting to bulk-read from CharSequence must contain a (theoretically infinite) list of bulk-reading solutions, e. g. (copied from Reader.of(CharSequence) in JDK 24):

switch (cs) {
    case String s -> s.getChars(next, next + n, cbuf, off);
    case StringBuilder sb -> sb.getChars(next, next + n, cbuf, off);
    case StringBuffer sb -> sb.getChars(next, next + n, cbuf, off);
    case CharBuffer cb -> cb.get(next, cbuf, off, n);
    default -> {
        for (int i = 0; i < n; i++)
            cbuf[off + i] = cs.charAt(next + i);
    }
}

The motivation for the new method is performance as sequential reading is expensive.

Solution

Add a new method public void getChars(int, int, char[], int) to CharSequence and CharBuffer.

Specification

/**
 * Characters are copied from this sequence into the
 * destination character array {@code dst}. The first character to
 * be copied is at index {@code srcBegin}; the last character to
 * be copied is at index {@code srcEnd-1}. The total number of
 * characters to be copied is {@code srcEnd-srcBegin}. The
 * characters are copied into the subarray of {@code dst} starting
 * at index {@code dstBegin} and ending at index:
 * <pre>{@code
 * dstbegin + (srcEnd-srcBegin) - 1
 * }</pre>
 *
 * @param      srcBegin   start copying at this offset.
 * @param      srcEnd     stop copying at this offset.
 * @param      dst        the array to copy the data into.
 * @param      dstBegin   offset into {@code dst}.
 * @throws     IndexOutOfBoundsException  if any of the following is true:
 *             <ul>
 *             <li>{@code srcBegin} is negative
 *             <li>{@code dstBegin} is negative
 *             <li>the {@code srcBegin} argument is greater than
 *             the {@code srcEnd} argument.
 *             <li>{@code srcEnd} is greater than
 *             {@code this.length()}.
 *             <li>{@code dstBegin+srcEnd-srcBegin} is greater than
 *             {@code dst.length}
 *             </ul>
 *
 * @since 24
 */
public default void getChars(int srcBegin, int srcEnd, char[] dst, int dstBegin)

/**
 * {@inheritDoc}
 *
 * @apiNote This method exists solely to implement
 * {@link CharSequence#getChars(int,int,char[],int)}.
 * It has no additional benefit over {@link #get(int, char[], int, int)}.
 *
 * @implSpec This method is equivalent to
 * {@code get(srcBegin, dst, dstBegin, srcEnd - srcBegin)}.
 *
 * @implNote This method allows for superior performance over the default
 * implementation in {@code CharSequence.getChars()}. It performs a direct
 * buffer-to-array copy of the complete specified region.
 *
 * @since 24
 */
@Override
public void getChars(int srcBegin, int srcEnd, char[] dst, int dstBegin)