Class Chars

  • All Implemented Interfaces:
    CharSequence

    public final class Chars
    extends Object
    implements CharSequence
    View on a string which doesn't copy the array for subsequence operations. This view is immutable. Since it uses a string internally it benefits from Java 9's compacting feature, it can also be efficiently created from a StringBuilder. When confronted with an instance of this interface, please don't create substrings unnecessarily. Both subSequence(int, int) and slice(int, int) can cut out a subsequence without copying the underlying byte array. The Pattern API also works perfectly on arbitrary CharSequences, not just on strings. Lastly some methods here provided provide mediated access to the underlying string, which for many use cases is much more optimal than using this CharSequence directly, eg appendChars(StringBuilder), writeFully(Writer).
    See Also:
    Chars::wrap, the factory method
    • Field Detail

      • EMPTY

        public static final Chars EMPTY
        An empty Chars instance.
    • Method Detail

      • isEmpty

        public boolean isEmpty()
        Whether this slice is the empty string.
      • wrap

        public static Chars wrap​(CharSequence chars)
        Wraps the given char sequence into a Chars. This may call CharSequence.toString(). If the sequence is already a Chars, returns it. This is the main factory method for this class. You can eg pass a StringBuilder if you want.
      • getChars

        public void getChars​(int srcBegin,
                             char @NonNull [] cbuf,
                             int dstBegin,
                             int count)
        Copies 'count' characters from index 'srcBegin' into the given array, starting at 'dstBegin'.
        Parameters:
        srcBegin - Start offset in this CharSequence
        cbuf - Character array
        count - Number of characters to copy
        dstBegin - Start index in the array
        Throws:
        NullPointerException - If the array is null (may)
        IndexOutOfBoundsException - See String.getChars(int, int, char[], int)
      • appendChars

        public void appendChars​(StringBuilder sb)
        Append this character sequence on the given stringbuilder. This is much more efficient than calling StringBuilder.append(CharSequence) with this as the parameter, especially on Java 9+.
        Parameters:
        sb - String builder
      • getBytes

        public ByteBuffer getBytes​(Charset charset)
        Returns the characters of this charsequence encoded with the given charset.
      • startsWith

        public boolean startsWith​(char prefix,
                                  int fromIndex)
      • trimStart

        public Chars trimStart()
        Returns a subsequence which does not start with control characters (<= 32). This is consistent with String.trim().
      • trimEnd

        public Chars trimEnd()
        Returns a subsequence which does not end with control characters (<= 32). This is consistent with String.trim().
      • trimBlankLines

        public Chars trimBlankLines()
        Remove trailing and leading blank lines. The resulting string does not end with a line terminator.
      • removeSuffix

        public Chars removeSuffix​(String charSeq)
        Remove the suffix if it is present, otherwise returns this.
      • removePrefix

        public Chars removePrefix​(String charSeq)
        Remove the prefix if it is present, otherwise returns this.
      • contentEquals

        public boolean contentEquals​(CharSequence cs,
                                     boolean ignoreCase)
        Returns true if this char sequence is logically equal to the parameter. This means they're equal character-by-character. This is more general than equals(Object), which will only answer true if the parameter is a Chars.
        Parameters:
        cs - Another char sequence
        ignoreCase - Whether to ignore case
        Returns:
        True if both sequences are logically equal
      • contentEquals

        public boolean contentEquals​(CharSequence cs)
        Like contentEquals(CharSequence, boolean), considering case distinctions.
        Parameters:
        cs - A char sequence
        Returns:
        True if both sequences are logically equal, considering case
      • charAt

        public char charAt​(int index)
        Specified by:
        charAt in interface CharSequence
      • subSequence

        public Chars subSequence​(int start)
        Returns the subsequence that starts at the given offset and ends at the end of this string. Similar to String.substring(int).
      • slice

        public Chars slice​(TextRegion region)
        Slice a region of text.
        Parameters:
        region - A region
        Returns:
        A Chars instance
        Throws:
        IndexOutOfBoundsException - If the region is not a valid range
      • slice

        public Chars slice​(int off,
                           int len)
        Like subSequence(int, int) but with offset + length instead of start + end.
        Parameters:
        off - Start of the slice (0 <= off < this.length())
        len - Length of the slice (0 <= len <= this.length() - off)
        Returns:
        A Chars instance
        Throws:
        IndexOutOfBoundsException - If the parameters are not a valid range
      • substring

        public String substring​(int start,
                                int end)
        Returns the substring between the given offsets. given length.

        Note: Unlike slice or subSequence, this method will create a new String which involves copying the backing char array. Don't use it unnecessarily.

        Parameters:
        start - Start offset (0 <= start < this.length())
        end - End offset (start <= end <= this.length())
        Returns:
        A substring
        Throws:
        IndexOutOfBoundsException - If the parameters are not a valid range
        See Also:
        String.substring(int, int)
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object
      • lines

        public Iterable<Chars> lines()
        Returns an iterable over the lines of this char sequence. The lines are yielded without line separators. Like BufferedReader.readLine(), a line delimiter is CR, LF or CR+LF.
      • lineStream

        public Stream<Chars> lineStream()
        Returns a stream of lines yielded by lines().
      • toStringBuilder

        public StringBuilder toStringBuilder()
        Returns a new stringbuilder containing the whole contents of this char sequence.
      • newReader

        public Reader newReader()
        Returns a new reader for the whole contents of this char sequence.