Package it.unimi.dsi.lang

Class MutableString

  • All Implemented Interfaces:
    Serializable, Appendable, CharSequence, Cloneable, Comparable<MutableString>
    public class MutableString
extends Object
implements Serializable, CharSequence, Appendable, Comparable<MutableString>, Cloneable
    Fast, compact, optimised & versatile mutable strings.

    Motivation

    The classical Java string classes, String and StringBuffer, lie at the extreme of a spectrum (immutable and mutable).

    However, large-scale text indexing requires some features that are not provided by these classes: in particular, the possibility of using a mutable string, once frozen, in the same optimised way of an immutable string.

    In a typical scenario you are dividing text into words (so you use a mutable string to accumulate characters). Once you've got your word, you would like to check whether this word is in a dictionary without creating a new object. However, equality of string builders is not defined on their content, and storing words after a conversion to String will not help either, as then you would need to convert the current mutable string into an immutable one (thus creating a new object) before deciding whether you need to store it.

    This class tries to make the best of both worlds, and thus aims at being a Better Mousetrap™.

    You can read more details about the design of MutableString in Paolo Boldi and Sebastiano Vigna, “Mutable strings in Java: Design, implementation and lightweight text-search algorithms”, Sci. Comput. Programming, 54(1):3-23, 2005.

    Features

    Mutable strings come in two flavours: compact and loose. A mutable string created by the empty constructor or the constructor specifying a capacity is loose. All other constructors create compact mutable strings. In most cases, you can completely forget whether your mutable strings are loose or compact and get good performance.
    • Mutable strings occupy little space— their only attributes are a backing character array and an integer;
    • their methods try to be as efficient as possible:for instance, if some limitation on a parameter is implied by limitation on array access, we do not check it explicitly, and Bloom filters are used to speed up multi-character substitutions;
    • they let you access directly the backing array (at your own risk);
    • they implement CharSequence, so, for instance, you can match or split a mutable string against a regular expression using the standard Java API;
    • they implement Appendable, so they can be used with Formatter and similar classes;
    • nullis not accepted as a string argument;
    • compact mutable strings have a slow growth; loose mutable strings have a fast growth;
    • hash codes of compact mutable strings are cached (for faster equality checks);
    • typical conversions such as trimming, upper/lower casing and replacements are made in place, with minimal reallocations;
    • all methods try, whenever it is possible, to return this, so you can chain methods as in s.length(0).append("foo").append("bar");
    • you can write or print a mutable string without creating a String by using write(Writer), print(PrintWriter) and println(PrintWriter); you can read it back using read(Reader,int).
    • you can write any mutable string in (length-prefixed) UTF-8 format by using writeSelfDelimUTF8(DataOutput)—you are not limited to strings whose UTF-8 encoded length fits 16 bits; notice however that surrogate pairs will not be coalesced into a single code point, so you must re-read such strings using the same method;
    • you can wrap any character array into a mutable string;
    • this class is not final: thus, you can add your own methods to specialised versions.

    Committing to use this class for such an ubiquitous data structure as strings may seem dangerous, as standard string classes are by now tested and stable. However, this class has been heavily regression (and torture) tested on all methods, and we believe it is very reliable.

    To simplify the transition to mutable strings, we have tried to make mixing string classes simpler by providing polymorphic versions of all methods accepting one or more strings—whenever you must specify a string you can usually provide a MutableString, a String, or a generic CharSequence.

    Note that usually we provide a specific method for String. This duplication may seem useless, as String implements CharSequence. However, invoking methods on an interface is slower than invoking methods on a class, and we expect constant strings to appear often in such methods.

    The Reallocation Heuristic

    Backing array reallocations use a heuristic based on looseness. Whenever an operation changes the length, compact strings are resized to fit exactly the new content, whereas the capacity of a loose string is never shortened, and enlargements maximise the new length required with the double of the current capacity.

    The effect of this policy is that loose strings will get large buffers quickly, but compact strings will occupy little space and perform very well in data structures using hash codes.

    For instance, you can easily reuse a loose mutable string calling length(0) (which does not reallocate the backing array).

    In any case, you can call compact() and loose() to force the respective condition.

    Disadvantages

    The main disadvantage of mutable strings is that their substrings cannot share their backing arrays, so if you need to generate many substrings you may want to use String. However, subSequence() returns a CharSequence that shares the backing array.

    Warnings

    There are a few differences with standard string classes you should be aware of.
    1. This class is not synchronised. If multiple threads access an object of this class concurrently, and at least one of the threads modifies it, it must be synchronised externally.
    2. This class implements polymorphic versions of the equals method that compare the content of Strings and CharSequences, so that you can easily do checks like 
               mutableString.equals("Hello")
      Thus, you must not mix mutable strings with CharSequences in collections as equality between objects of those types is not symmetric.
    3. When the length of a string or char array argument is zero, some methods may just do nothing even if other parameters are out of bounds.
    4. The output of writeSelfDelimUTF8() is not compatible with the usual Java writeUTF().
    5. Even if this class is not final, most methods are declared final for efficiency, so you cannot override them (why should you ever want to override array()?).
    Since:
    0.3
    Author:
    Sebastiano Vigna, Paolo Boldi
    See Also:
    Serialized Form

    • Field Detail

      • array

        protected transient char[] array
        The backing array.

      • hashLength

        protected transient int hashLength
        This mutable string is compact iff this attribute is negative. It the string is compact, the attribute is its hash code (-1 denotes the invalid hash code). If the string is loose, the attribute is the number of characters actually stored in the backing array.

    • Constructor Detail

      • MutableString

        public MutableString()
        Creates a new loose empty mutable string with capacity 2.

      • MutableString

        public MutableString​(int capacity)
        Creates a new loose empty mutable string with given capacity.
        Parameters:
        capacity - the required capacity.

      • MutableString

        public MutableString​(MutableString s)
        Creates a new compact mutable string copying a given mutable string.
        Parameters:
        s - the initial contents of the string.

      • MutableString

        public MutableString​(String s)
        Creates a new compact mutable string copying a given String.
        Parameters:
        s - the initial contents of the string.

      • MutableString

        public MutableString​(CharSequence s)
        Creates a new compact mutable string copying a given CharSequence.
        Parameters:
        s - the initial contents of the string.

      • MutableString

        public MutableString​(char[] a)
        Creates a new compact mutable string copying a given character array.
        Parameters:
        a - the initial contents of the string.

      • MutableString

        public MutableString​(char[] a,
                     int offset,
                     int len)
        Creates a new compact mutable string copying a part of a given character array.
        Parameters:
        a - a character array.
        offset - an offset into the array.
        len - how many characters to copy.

    • Method Detail

      • copy

        public MutableString copy()
        Creates a new compact mutable string by copying this one.
        Returns:
        a compact copy of this mutable string.

      • clone

        public Object clone()
        Creates a new compact mutable string by copying this one.

        This method is identical to copy(), but the latter returns a more specific type.

        Overrides:
        clone in class Object
        Returns:
        a compact copy of this mutable string.

      • getChars

        public static void getChars​(CharSequence s,
                            int start,
                            int end,
                            char[] dest,
                            int destStart)
        Commodity static method implementing String.getChars(int,int,char[],int) for a CharSequences.
        Parameters:
        s - a CharSequence.
        start - copy start from this index (inclusive).
        end - copy ends at this index (exclusive).
        dest - destination array.
        destStart - the first character will be copied in dest[destStart].
        See Also:
        String.getChars(int,int,char[],int)

      • length

        public final int length()
        Returns the number of characters in this mutable string.
        Specified by:
        length in interface CharSequence
        Returns:
        the length of this mutable string.

      • isEmpty

        public final boolean isEmpty()
        Returns whether this mutable string is empty.
        Returns:
        whether this mutable string is empty.

      • capacity

        public final int capacity()
        Returns the current length of the backing array.
        Returns:
        the current length of the backing array.

      • array

        public final char[] array()
        Gets the backing array.

        For fast, repeated access to the characters of this mutable string, you can obtain the actual backing array. Be careful, and if this mutable string is compact do not modify its backing array without calling changed() immediately afterwards (or the cached hash code will get out of sync, with unforeseeable consequences).

        Returns:
        the backing array.
        See Also:
        changed()

      • getChars

        public final void getChars​(int start,
                           int end,
                           char[] dest,
                           int destStart)
        Characters with indices from start (inclusive) to index end (exclusive) are copied from this mutable string into the array dest, starting from index destStart.
        Parameters:
        start - copy start from this index (inclusive).
        end - copy ends at this index (exclusive).
        dest - destination array.
        destStart - the first character will be copied in dest[destStart].
        Throws:
        NullPointerException - if dest is null.
        IndexOutOfBoundsException - if any of the following is true:
        • start or end is negative
        • start is greater than end
        • end is greater than length()
        • end-start+destStart is greater than dest.length
        See Also:
        String.getChars(int,int,char[],int)

      • ensureCapacity

        public final MutableString ensureCapacity​(int minimumCapacity)
        Ensures that at least the given number of characters can be stored in this mutable string.

        The new capacity of this string will be exactly equal to the provided argument if this mutable string is compact (this differs markedly from StringBuffer). If this mutable string is loose, the provided argument is maximised with the current capacity doubled.

        Note that if the given argument is greater than the current length, you will make this string loose (see the class description).

        Parameters:
        minimumCapacity - we want at least this number of characters, but no more.
        Returns:
        this mutable string.

      • length

        public final MutableString length​(int newLength)
        Sets the length.

        If the provided length is greater than that of the current string, the string is padded with zeros. If it is shorter, the string is truncated to the given length. We do not reallocate the backing array, to increase object reuse. Use rather compact() for that purpose.

        Note that shortening a string will make it loose (see the class description).

        Parameters:
        newLength - the new length for this mutable string.
        Returns:
        this mutable string.
        See Also:
        compact()

      • setLength

        public final MutableString setLength​(int newLength)
        A nickname for length(int).
        Parameters:
        newLength - the new length for this mutable string.
        Returns:
        this mutable string.
        See Also:
        length(int)

      • compact

        public final MutableString compact()
        Makes this mutable string compact (see the class description).

        Note that this operation may require reallocating the backing array (of course, with a shorter length).

        Returns:
        this mutable string.
        See Also:
        isCompact()

      • loose

        public final MutableString loose()
        Makes this mutable string loose.
        Returns:
        this mutable string.
        See Also:
        isLoose()

      • isCompact

        public final boolean isCompact()
        Returns whether this mutable string is compact (see the class description).
        Returns:
        whether this mutable string is compact.
        See Also:
        compact()

      • isLoose

        public final boolean isLoose()
        Returns whether this mutable string is loose (see the class description).
        Returns:
        whether this mutable string is loose.
        See Also:
        loose()

      • changed

        public final MutableString changed()
        Invalidates the current cached hash code if this mutable string is compact.

        You will need to call this method only if you change the backing array of a compact mutable string directly.

        Returns:
        this mutable string.

      • wrap

        public static MutableString wrap​(char[] a)
        Wraps a given character array in a compact mutable string.

        The returned mutable string will be compact and backed by the given character array.

        Parameters:
        a - a character array.
        Returns:
        a compact mutable string backed by the given array.

      • wrap

        public static MutableString wrap​(char[] a,
                                 int length)
        Wraps a given character array for a given length in a loose mutable string.

        The returned mutable string will be loose and backed by the given character array.

        Parameters:
        a - a character array.
        length - a length.
        Returns:
        a loose mutable string backed by the given array with the given length.

      • charAt

        public final char charAt​(int index)
        Gets a character.

        If you end up calling repeatedly this method, you should consider using array() instead.

        Specified by:
        charAt in interface CharSequence
        Parameters:
        index - the index of a character.
        Returns:
        the chracter at that index.

      • setCharAt

        public final MutableString setCharAt​(int index,
                                     char c)
        A nickname for charAt(int,char).
        Parameters:
        index - the index of a character.
        c - the new character.
        Returns:
        this mutable string.
        See Also:
        charAt(int,char)

      • charAt

        public final MutableString charAt​(int index,
                                  char c)
        Sets the character at the given index.

        If you end up calling repeatedly this method, you should consider using array() instead.

        Parameters:
        index - the index of a character.
        c - the new character.
        Returns:
        this mutable string.

      • firstChar

        public final char firstChar()
        Returns the first character of this mutable string.
        Returns:
        the first character.
        Throws:
        StringIndexOutOfBoundsException - when called on the empty string.

      • lastChar

        public final char lastChar()
        Returns the last character of this mutable string.
        Returns:
        the last character.
        Throws:
        ArrayIndexOutOfBoundsException - when called on the empty string.

      • toCharArray

        public final char[] toCharArray()
        Converts this string to a new character array.
        Returns:
        a newly allocated character array with the same length and content of this mutable string.

      • substring

        public final MutableString substring​(int start,
                                     int end)
        Returns a substring of this mutable string.

        The creation of a substring implies the creation of a new backing array. The returned mutable string will be compact.

        Parameters:
        start - first character of the substring (inclusive).
        end - last character of the substring (exclusive).
        Returns:
        a substring defined as above.

      • substring

        public final MutableString substring​(int start)
        Returns a substring of this mutable string.
        Parameters:
        start - first character of the substring (inclusive).
        Returns:
        a substring ranging from the given position to the end of this string.
        See Also:
        substring(int,int)

      • subSequence

        public final CharSequence subSequence​(int start,
                                      int end)
        Returns a subsequence of this mutable string.

        Subsequences share the backing array. Thus, you should not use a subsequence after changing the characters of this mutable string between start and end.

        Equality of CharSequences returned by this method is defined by content equality, and hash codes are identical to mutable strings with the same content. Thus, you can mix mutable strings and CharSequences returned by this method in data structures, as the contracts of equals() and hashCode() are honoured.

        Specified by:
        subSequence in interface CharSequence
        Parameters:
        start - first character of the subsequence (inclusive).
        end - last character of the subsequence (exclusive).
        Returns:
        a subsequence defined as above.
        See Also:
        substring(int,int)

      • append

        public final MutableString append​(MutableString s)
        Appends the given mutable string to this mutable string.
        Parameters:
        s - the mutable string to append.
        Returns:
        this mutable string.

      • append

        public final MutableString append​(String s)
        Appends the given String to this mutable string.
        Parameters:
        s - a String (null is not allowed).
        Returns:
        this mutable string.
        Throws:
        NullPointerException - if the argument is null

      • append

        public final MutableString append​(CharSequence[] a,
                                  int offset,
                                  int length,
                                  CharSequence separator)
        Appends the given character sequences to this mutable string using the given separator.
        Parameters:
        a - an array.
        offset - the index of the first character sequence to append.
        length - the number of character sequences to append.
        separator - a separator that will be appended inbetween the character sequences.
        Returns:
        this mutable string.

      • append

        public final MutableString append​(CharSequence[] a,
                                  CharSequence separator)
        Appends the given character sequences to this mutable string using the given separator.
        Parameters:
        a - an array.
        separator - a separator that will be appended inbetween the character sequences.
        Returns:
        this mutable string.

      • append

        public final MutableString append​(Object[] a,
                                  int offset,
                                  int length,
                                  CharSequence separator)
        Appends the string representations of the given objects to this mutable string using the given separator.
        Parameters:
        a - an array of objects.
        offset - the index of the first object to append.
        length - the number of objects to append.
        separator - a separator that will be appended inbetween the string representations of the given objects.
        Returns:
        this mutable string.

      • append

        public final MutableString append​(Object[] a,
                                  CharSequence separator)
        Appends the string representations of the given objects to this mutable string using the given separator.
        Parameters:
        a - an array of objects.
        separator - a separator that will be appended inbetween the string representations of the given objects.
        Returns:
        this mutable string.

      • append

        public final MutableString append​(char[] a)
        Appends the given character array to this mutable string.
        Parameters:
        a - an array to append.
        Returns:
        this mutable string.

      • append

        public final MutableString append​(char[] a,
                                  int offset,
                                  int len)
        Appends a part of the given character array to this mutable string. Warning: the semantics of this method of that of append(CharSequence, int, int) are different.
        Parameters:
        a - an array.
        offset - the index of the first character to append.
        len - the number of characters to append.
        Returns:
        this mutable string.

      • append

        public final MutableString append​(CharList list)
        Appends the given character list to this mutable string.
        Parameters:
        list - the list to append.
        Returns:
        this mutable string.

      • append

        public final MutableString append​(CharList list,
                                  int offset,
                                  int len)
        Appends a part of the given character list to this mutable string. Warning: the semantics of this method of that of append(CharSequence, int, int) are different.
        Parameters:
        list - a character list.
        offset - the index of the first character to append.
        len - the number of characters to append.
        Returns:
        this mutable string.

      • append

        public final MutableString append​(boolean b)
        Appends a boolean to this mutable string.
        Parameters:
        b - the boolean to be appended.
        Returns:
        this mutable string.

      • append

        public final MutableString append​(char c)
        Appends a character to this mutable string.

        Note that this method will reallocate the backing array of a compact mutable string for each character appended. Do not call it lightly.

        Specified by:
        append in interface Appendable
        Parameters:
        c - a character.
        Returns:
        this mutable string.

      • append

        public final MutableString append​(int i)
        Appends an integer to this mutable string.
        Parameters:
        i - the integer to be appended.
        Returns:
        this mutable string.

      • append

        public final MutableString append​(long l)
        Appends a long to this mutable string.
        Parameters:
        l - the long to be appended.
        Returns:
        this mutable string.

      • append

        public final MutableString append​(float f)
        Appends a float to this mutable string.
        Parameters:
        f - the float to be appended.
        Returns:
        this mutable string.

      • append

        public final MutableString append​(double d)
        Appends a double to this mutable string.
        Parameters:
        d - the double to be appended.
        Returns:
        this mutable string.

      • append

        public final MutableString append​(Object o)
        Appends the string representation of an object to this mutable string.
        Parameters:
        o - the object to append.
        Returns:
        a reference to this mutable string.

      • insert

        public final MutableString insert​(int index,
                                  MutableString s)
        Inserts a mutable string in this mutable string, starting from index index.
        Parameters:
        index - position at which to insert the String.
        s - the mutable string to be inserted.
        Returns:
        this mutable string.
        Throws:
        NullPointerException - if s is null
        IndexOutOfBoundsException - if index is negative or greater than length().

      • insert

        public final MutableString insert​(int index,
                                  String s)
        Inserts a String in this mutable string, starting from index index.
        Parameters:
        index - position at which to insert the String.
        s - the String to be inserted.
        Returns:
        this mutable string.
        Throws:
        NullPointerException - if s is null
        IndexOutOfBoundsException - if index is negative or greater than length().

      • insert

        public final MutableString insert​(int index,
                                  CharSequence s)
        Inserts a CharSequence in this mutable string, starting from index index.
        Parameters:
        index - position at which to insert the CharSequence.
        s - the CharSequence to be inserted.
        Returns:
        this mutable string.
        Throws:
        NullPointerException - if s is null
        IndexOutOfBoundsException - if index is negative or greater than length().

      • insert

        public final MutableString insert​(int index,
                                  char[] c)
        Inserts characters in this mutable string. All of the characters of the array c are inserted in this mutable string, and the first inserted character is going to have index index.
        Parameters:
        index - position at which to insert subarray.
        c - the character array.
        Returns:
        this mutable string.
        Throws:
        NullPointerException - if c is null
        IndexOutOfBoundsException - if index is negative or greater than length().

      • insert

        public final MutableString insert​(int index,
                                  char[] c,
                                  int offset,
                                  int len)
        Inserts characters in this mutable string. len characters of the array c, with indices starting from offset, are inserted in this mutable string, and the first inserted character is going to have index index.
        Parameters:
        index - position at which to insert subarray.
        c - the character array.
        offset - the index of the first character of c to to be inserted.
        len - the number of characters of c to to be inserted.
        Returns:
        this mutable string.
        Throws:
        NullPointerException - if c is null
        IndexOutOfBoundsException - if index is negative or greater than length(), or offset or len are negative, or offset+len is greater than c.length.

      • insert

        public final MutableString insert​(int index,
                                  boolean b)
        Inserts a boolean in this mutable string, starting from index index.
        Parameters:
        index - position at which to insert the String.
        b - the boolean to be inserted.
        Returns:
        this mutable string.
        Throws:
        IndexOutOfBoundsException - if index is negative or greater than length().

      • insert

        public final MutableString insert​(int index,
                                  char c)
        Inserts a char in this mutable string, starting from index index.

        Note that this method will not expand the capacity of a compact mutable string by more than one character. Do not call it lightly.

        Parameters:
        index - position at which to insert the String.
        c - the char to be inserted.
        Returns:
        this mutable string.
        Throws:
        IndexOutOfBoundsException - if index is negative or greater than length().

      • insert

        public final MutableString insert​(int index,
                                  double d)
        Inserts a double in this mutable string, starting from index index.
        Parameters:
        index - position at which to insert the String.
        d - the double to be inserted.
        Returns:
        this mutable string.
        Throws:
        IndexOutOfBoundsException - if index is negative or greater than length().

      • insert

        public final MutableString insert​(int index,
                                  float f)
        Inserts a float in this mutable string, starting from index index.
        Parameters:
        index - position at which to insert the String.
        f - the float to be inserted.
        Returns:
        this mutable string.
        Throws:
        IndexOutOfBoundsException - if index is negative or greater than length().

      • insert

        public final MutableString insert​(int index,
                                  int x)
        Inserts an int in this mutable string, starting from index index.
        Parameters:
        index - position at which to insert the String.
        x - the int to be inserted.
        Returns:
        this mutable string.
        Throws:
        IndexOutOfBoundsException - if index is negative or greater than length().

      • insert

        public final MutableString insert​(int index,
                                  long l)
        Inserts a long in this mutable string, starting from index index.
        Parameters:
        index - position at which to insert the String.
        l - the long to be inserted.
        Returns:
        this mutable string.
        Throws:
        IndexOutOfBoundsException - if index is negative or greater than length().

      • insert

        public final MutableString insert​(int index,
                                  Object o)
        Inserts the string representation of an object in this mutable string, starting from index index.
        Parameters:
        index - position at which to insert the String.
        o - the object to be inserted.
        Returns:
        this mutable string.
        Throws:
        IndexOutOfBoundsException - if index is negative or greater than length().

      • delete

        public final MutableString delete​(int start,
                                  int end)
        Removes the characters of this mutable string with indices in the range from start (inclusive) to end (exclusive). If end is greater than or equal to the length of this mutable string, all characters with indices greater than or equal to start are deleted.
        Parameters:
        start - The beginning index (inclusive).
        end - The ending index (exclusive).
        Returns:
        this mutable string.
        Throws:
        IndexOutOfBoundsException - if start is greater than length(), or greater than end.

      • deleteCharAt

        public final MutableString deleteCharAt​(int index)
        Removes the character at the given index.

        Note that this method will reallocate the backing array of a compact mutable string for each character deleted. Do not call it lightly.

        Parameters:
        index - Index of character to remove
        Returns:
        this mutable string.
        Throws:
        IndexOutOfBoundsException - if index is negative, or greater than or equal to length().

      • delete

        public final MutableString delete​(char c)
        Removes all occurrences of the given character.
        Parameters:
        c - the character to remove.
        Returns:
        this mutable string.

      • delete

        public final MutableString delete​(CharSet s)
        Removes all occurrences of the given characters.
        Parameters:
        s - the set of characters to remove.
        Returns:
        this mutable string.

      • delete

        public final MutableString delete​(char[] c)
        Removes all occurrences of the given characters.
        Parameters:
        c - an array containing the characters to remove.
        Returns:
        this mutable string.

      • replace

        public final MutableString replace​(int start,
                                   int end,
                                   MutableString s)
        Replaces the characters with indices ranging from start (inclusive) to end (exclusive) with the given mutable string.
        Parameters:
        start - The starting index (inclusive).
        end - The ending index (exclusive).
        s - The mutable string to be copied.
        Returns:
        this mutable string.
        Throws:
        IndexOutOfBoundsException - if start is negative, greater than length(), or greater than end.

      • replace

        public final MutableString replace​(int start,
                                   int end,
                                   String s)
        Replaces the characters with indices ranging from start (inclusive) to end (exclusive) with the given String.
        Parameters:
        start - The starting index (inclusive).
        end - The ending index (exclusive).
        s - The String to be copied.
        Returns:
        this mutable string.
        Throws:
        IndexOutOfBoundsException - if start is negative, greater than length(), or greater than end.

      • replace

        public final MutableString replace​(int start,
                                   int end,
                                   CharSequence s)
        Replaces the characters with indices ranging from start (inclusive) to end (exclusive) with the given CharSequence.
        Parameters:
        start - The starting index (inclusive).
        end - The ending index (exclusive).
        s - The CharSequence to be copied.
        Returns:
        this mutable string.
        Throws:
        IndexOutOfBoundsException - if start is negative, greater than length(), or greater than end.

      • replace

        public final MutableString replace​(int start,
                                   int end,
                                   char c)
        Replaces the characters with indices ranging from start (inclusive) to end (exclusive) with the given character.
        Parameters:
        start - The starting index (inclusive).
        end - The ending index (exclusive).
        c - The character to be copied.
        Returns:
        this mutable string.
        Throws:
        IndexOutOfBoundsException - if start is negative, greater than length(), or greater than end.

      • replace

        public final MutableString replace​(MutableString s)
        Replaces the content of this mutable string with the given mutable string.
        Parameters:
        s - the mutable string whose content will replace the present one.
        Returns:
        this mutable string.

      • replace

        public final MutableString replace​(String s)
        Replaces the content of this mutable string with the given string.
        Parameters:
        s - the string whose content will replace the present one.
        Returns:
        this mutable string.

      • replace

        public final MutableString replace​(CharSequence s)
        Replaces the content of this mutable string with the given character sequence.
        Parameters:
        s - the character sequence whose content will replace the present one.
        Returns:
        this mutable string.

      • replace

        public final MutableString replace​(char c)
        Replaces the content of this mutable string with the given character.
        Parameters:
        c - the character whose content will replace the present content.
        Returns:
        this mutable string.

      • replace

        public final MutableString replace​(char[] c,
                                   MutableString[] s)
        Replaces each occurrence of a set of characters with a corresponding mutable string.

        Each occurrences of the character c[i] in this mutable string will be replaced by s[i]. Note that c and s must have the same length, and that c must not contain duplicates. Moreover, each replacement string must be nonempty.

        This method uses a Bloom filter to avoid repeated linear scans of the character array for length() times; however, this optimisation will be most effective with arrays of less than twenty characters, and, in fact, will very slightly slow down replacements with more than one hundred characters.

        This method will try at most one reallocation.

        Parameters:
        c - an array of characters to be replaced.
        s - an array of replacement mutable strings.
        Returns:
        this mutable string.
        Throws:
        IllegalArgumentException - if one of the replacement strings is empty.

      • replace

        public final MutableString replace​(char[] c,
                                   String[] s)
        Replaces each occurrence of a set of characters with a corresponding string.

        Each occurrences of the character c[i] in this mutable string will be replaced by s[i]. Note that c and s must have the same length, and that c must not contain duplicates. Moreover, each replacement string must be nonempty.

        This method uses a Bloom filter to avoid repeated linear scans of the character array for length() times; however, this optimisation will be most effective with arrays of less than twenty characters, and, in fact, will very slightly slow down replacements with more than one hundred characters.

        This method will try at most one reallocation.

        Parameters:
        c - an array of characters to be replaced.
        s - an array of replacement strings.
        Returns:
        this mutable string.
        Throws:
        IllegalArgumentException - if one of the replacement strings is empty.

      • replace

        public final MutableString replace​(char[] c,
                                   CharSequence[] s)
        Replaces each occurrence of a set of characters with a corresponding character sequence.

        Each occurrences of the character c[i] in this mutable string will be replaced by s[i]. Note that c and s must have the same length, and that c must not contain duplicates. Moreover, each replacement sequence must be nonempty.

        This method uses a Bloom filter to avoid repeated linear scans of the character array for length() times; however, this optimisation will be most effective with arrays of less than twenty characters, and, in fact, will very slightly slow down replacements with more than one hundred characters.

        This method will try at most one reallocation.

        Parameters:
        c - an array of characters to be replaced.
        s - an array of replacement character sequences.
        Returns:
        this mutable string.
        Throws:
        IllegalArgumentException - if one of the replacement sequences is empty.

      • replace

        public final MutableString replace​(char[] c,
                                   char[] r)
        Replaces each occurrence of a set characters with a corresponding character.

        Each occurrences of the character c[i] in this mutable string will be replaced by r[i]. Note that c and s must have the same length, and that c must not contain duplicates.

        This method uses a Bloom filter to avoid repeated linear scans of the character array for length() times; however, this optimisation will be most effective with arrays of less than twenty characters, and, in fact, will very slightly slow down replacements with more than one hundred characters.

        Parameters:
        c - an array of characters to be replaced.
        r - an array of replacement characters.
        Returns:
        this mutable string.

      • replace

        public final MutableString replace​(Char2CharMap m)
        Replaces characters following a replacement map.

        Each occurrence of a key of m will be substituted with the corresponding value.

        Parameters:
        m - a map specifiying the character replacements.
        Returns:
        this mutable string.

      • replace

        public final MutableString replace​(char c,
                                   MutableString s)
        Replaces each occurrence of a character with a corresponding mutable string.

        Each occurrences of the character c in this mutable string will be replaced by s. Note that s must be nonempty.

        This method will try at most one reallocation.

        Parameters:
        c - a character to be replaced.
        s - a replacement mutable string.
        Returns:
        this mutable string.
        Throws:
        IllegalArgumentException - if the replacement string is empty.

      • replace

        public final MutableString replace​(char c,
                                   String s)
        Replaces each occurrence of a character with a corresponding string.

        Each occurrences of the character c in this mutable string will be replaced by s. Note that s must be nonempty.

        This method will try at most one reallocation.

        Parameters:
        c - a character to be replaced.
        s - a replacement string.
        Returns:
        this mutable string.
        Throws:
        IllegalArgumentException - if the replacement sequence is empty.

      • replace

        public final MutableString replace​(char c,
                                   CharSequence s)
        Replaces each occurrence of a character with a corresponding character sequence.

        Each occurrences of the character c in this mutable string will be replaced by s. Note that s must be nonempty.

        This method will try at most one reallocation.

        Parameters:
        c - a character to be replaced.
        s - a replacement character sequence.
        Returns:
        this mutable string.
        Throws:
        IllegalArgumentException - if the replacement sequence is empty.

      • replace

        public final MutableString replace​(char c,
                                   char r)
        Replaces each occurrence of a character with a corresponding character.
        Parameters:
        c - a character to be replaced.
        r - a replacement character.
        Returns:
        this mutable string.

      • replace

        public final MutableString replace​(MutableString s,
                                   MutableString r)
        Replaces each occurrence of a mutable string with a corresponding mutable string.

        Each occurrences of the mutable string s in this mutable string will be replaced by r. Note that s must be nonempty, unless r is empty, too.

        If the replacement string is longer than the search string, occurrences of the search string are matched from the end of this mutable string (i.e., using lastIndexOf()). Otherwise, occurrences of the search string are matched from the start (i.e., using indexOf()). This has no effect on the semantics, unless there are overlapping occurrences.

        This method will try at most one reallocation.

        Parameters:
        s - a mutable string to be replaced.
        r - a replacement mutable string.
        Returns:
        this mutable string.
        Throws:
        IllegalArgumentException - if you try to replace the empty string with a nonempty string.

      • replace

        public final MutableString replace​(String s,
                                   String r)
        Replaces each occurrence of a string with a corresponding string.

        Each occurrences of the string s in this mutable string will be replaced by r. Note that s must be nonempty, unless r is empty, too.

        This method will try at most one reallocation.

        Parameters:
        s - a string to be replaced.
        r - a replacement string.
        Returns:
        this mutable string.
        Throws:
        IllegalArgumentException - if you try to replace the empty string with a nonempty string.
        See Also:
        replace(MutableString,MutableString)

      • replace

        public final MutableString replace​(CharSequence s,
                                   CharSequence r)
        Replaces each occurrence of a character sequence with a corresponding character sequence.

        Each occurrences of the string s in this mutable string will be replaced by r. Note that s must be nonempty, unless r is empty, too.

        This method will try at most one reallocation.

        Parameters:
        s - a character sequence to be replaced.
        r - a replacement character sequence.
        Returns:
        this mutable string.
        Throws:
        IllegalArgumentException - if you try to replace the empty sequence with a nonempty sequence.
        See Also:
        replace(MutableString,MutableString)

      • indexOf

        public final int indexOf​(char c)
        Returns the index of the first occurrence of the specified character.
        Parameters:
        c - the character to look for.
        Returns:
        the index of the first occurrence of c, or -1, if the character never appears.

      • indexOf

        public final int indexOf​(char c,
                         int from)
        Returns the index of the first occurrence of the specified character, starting at the specified index.
        Parameters:
        c - the character to look for.
        from - the index from which the search must start.
        Returns:
        the index of the first occurrence of c, or -1, if the character never appears with index greater than or equal to from.

      • indexOf

        public final int indexOf​(MutableString pattern,
                         int from)
        Returns the index of the first occurrence of the specified mutable string, starting at the specified index.

        This method uses a lightweight combination of Sunday's QuickSearch (a simplified but very effective variant of the Boyer—Moore search algorithm) and Bloom filters. More precisely, instead of recording the last occurrence of all characters in the pattern, we simply record in a small Bloom filter which characters belong to the pattern. Every time there is a mismatch, we look at the character immediately following the pattern: if it is not in the Bloom filter, besides moving to the next position we can additionally skip a number of characters equal to the length of the pattern.

        Unless called with a pattern that saturates the filter, this method will usually outperform that of String.

        Parameters:
        pattern - the mutable string to look for.
        from - the index from which the search must start.
        Returns:
        the index of the first occurrence of pattern after the first from characters, or -1, if the string never appears.

      • indexOf

        public final int indexOf​(MutableString pattern)
        Returns the index of the first occurrence of the specified mutable string.
        Parameters:
        pattern - the mutable string to look for.
        Returns:
        the index of the first occurrence of pattern, or -1, if the string never appears.
        See Also:
        indexOf(MutableString,int)

      • indexOf

        public final int indexOf​(CharSequence pattern,
                         int from)
        Returns the index of the first occurrence of the specified character sequence, starting at the specified index.

        Searching for a character sequence is slightly slower than searching for a mutable string, as every character of the pattern must be accessed through a method call. Please consider wrapping pattern in a mutable string, or use TextPattern for repeated searches.

        Parameters:
        pattern - the character sequence to look for.
        from - the index from which the search must start.
        Returns:
        the index of the first occurrence of pattern after the first from characters, or -1, if the string never appears.
        See Also:
        indexOf(MutableString,int)

      • indexOf

        public final int indexOf​(CharSequence pattern)
        Returns the index of the first occurrence of the specified character sequence.
        Parameters:
        pattern - the character sequence to look for.
        Returns:
        the index of the first occurrence of pattern, or -1, if the string never appears.
        See Also:
        indexOf(CharSequence,int)

      • indexOf

        public int indexOf​(TextPattern pattern,
                   int from)
        Returns the index of the first occurrence of the specified text pattern, starting at the specified index.

        To use this method, you have to create a text pattern first.

        Parameters:
        pattern - a compiled text pattern to be searched for.
        from - the index from which the search must start.
        Returns:
        the index of the first occurrence of pattern, or -1, if no such character ever appears.

      • indexOf

        public int indexOf​(TextPattern pattern)
        Returns the index of the first occurrence of the specified text pattern, starting at the specified index.
        Parameters:
        pattern - a compiled text pattern to be searched for.
        Returns:
        the index of the first occurrence of pattern, or -1, if no such character ever appears.
        See Also:
        indexOf(TextPattern, int)

      • indexOfAnyOf

        public int indexOfAnyOf​(CharSet s,
                        int from)
        Returns the index of the first occurrence of any of the specified characters, starting at the specified index.
        Parameters:
        s - a set of characters to be searched for.
        from - the index from which the search must start.
        Returns:
        the index of the first occurrence of any of the characters in s, or -1, if no such character ever appears.

      • indexOfAnyOf

        public int indexOfAnyOf​(CharSet s)
        Returns the index of the first occurrence of any of the specified characters.
        Parameters:
        s - a set of characters to be searched for.
        Returns:
        the index of the first occurrence of any of the characters in s, or -1, if no such character ever appears.
        See Also:
        indexOfAnyOf(CharSet,int)

      • indexOfAnyOf

        public int indexOfAnyOf​(char[] c,
                        int from)
        Returns the index of the first occurrence of any of the specified characters, starting at the specified index.

        This method uses a Bloom filter to avoid repeated linear scans of the array c; however, this optimisation will be most effective with arrays of less than twenty characters, and, in fact, will very slightly slow down searches for more than one hundred characters.

        Parameters:
        c - an array of characters to be searched for.
        from - the index from which the search must start.
        Returns:
        the index of the first occurrence of any of the characters in c, or -1, if no such character ever appears.

      • indexOfAnyOf

        public int indexOfAnyOf​(char[] c)
        Returns the index of the first occurrence of any of the specified characters.
        Parameters:
        c - an array of characters to be searched for.
        Returns:
        the index of the first occurrence of any of the characters in c, or -1, if no such character ever appears.
        See Also:
        indexOfAnyOf(char[],int)

      • indexOfAnyBut

        public int indexOfAnyBut​(CharSet s,
                         int from)
        Returns the index of the first occurrence of any character, except those specified, starting at the specified index.
        Parameters:
        s - a set of characters to be searched for.
        from - the index from which the search must start.
        Returns:
        the index of the first occurrence of any of the characters not in s, or -1, if no such character ever appears.

      • indexOfAnyBut

        public int indexOfAnyBut​(CharSet s)
        Returns the index of the first occurrence of any character, except those specified.
        Parameters:
        s - a set of characters to be searched for.
        Returns:
        the index of the first occurrence of any of the characters not in s, or -1, if no such character ever appears.
        See Also:
        indexOfAnyBut(CharSet,int)

      • indexOfAnyBut

        public int indexOfAnyBut​(char[] c,
                         int from)
        Returns the index of the first occurrence of any character, except those specified, starting at the specified index.

        This method uses a Bloom filter to avoid repeated linear scans of the array c; however, this optimisation will be most effective with arrays of less than twenty characters, and, in fact, will very slightly slow down searches for more than one hundred characters.

        Parameters:
        c - an array of characters to be searched for.
        from - the index from which the search must start.
        Returns:
        the index of the first occurrence of any of the characters not in c, or -1, if no such character ever appears.

      • indexOfAnyBut

        public int indexOfAnyBut​(char[] c)
        Returns the index of the first occurrence of any character, except those specified.
        Parameters:
        c - an array of characters to be searched for.
        Returns:
        the index of the first occurrence of any of the characters not in c, or -1, if no such character ever appears.
        See Also:
        indexOfAnyBut(char[],int)

      • lastIndexOf

        public final int lastIndexOf​(char c)
        Returns the index of the last occurrence of the specified character.
        Parameters:
        c - the character to look for.
        Returns:
        the index of the last occurrence of c, or -1, if the character never appears.

      • lastIndexOf

        public final int lastIndexOf​(char c,
                             int from)
        Returns the index of the last occurrence of the specified character, searching backward starting at the specified index.
        Parameters:
        c - the character to look for.
        from - the index from which the search must start.
        Returns:
        the index of the last occurrence of c, or -1, if the character never appears with index smaller than or equal to from.

      • lastIndexOf

        public final int lastIndexOf​(MutableString pattern,
                             int from)
        Returns the index of the last occurrence of the specified mutable string, searching backward starting at the specified index.
        Parameters:
        pattern - the mutable string to look for.
        from - the index from which the search must start.
        Returns:
        the index of the last occurrence of pattern, or -1, if the pattern never appears with index smaller than or equal to from.

      • lastIndexOf

        public final int lastIndexOf​(MutableString pattern)
        Returns the index of the last occurrence of the specified mutable string.
        Parameters:
        pattern - the mutable string to look for.
        Returns:
        the index of the last occurrence of pattern, or -1, if the pattern never appears.
        See Also:
        lastIndexOf(MutableString,int)

      • lastIndexOf

        public final int lastIndexOf​(CharSequence pattern,
                             int from)
        Returns the index of the last occurrence of the specified character sequence, searching backward starting at the specified index.
        Parameters:
        pattern - the character sequence to look for.
        from - the index from which the search must start.
        Returns:
        the index of the last occurrence of pattern, or -1, if the pattern never appears with index smaller than or equal to from.
        See Also:
        lastIndexOf(MutableString,int)

      • lastIndexOf

        public final int lastIndexOf​(CharSequence pattern)
        Returns the index of the last occurrence of the specified character sequence.
        Parameters:
        pattern - the character sequence to look for.
        Returns:
        the index of the last occurrence of pattern, or -1, if the pattern never appears.
        See Also:
        lastIndexOf(CharSequence,int)

      • lastIndexOfAnyOf

        public int lastIndexOfAnyOf​(CharSet s,
                            int from)
        Returns the index of the last occurrence of any of the specified characters, searching backwards starting at the specified index.

        This method uses a Bloom filter to avoid repeated linear scans of the array c; however, this optimisation will be most effective with arrays of less than twenty characters, and, in fact, will very slightly slow down searches for more than one hundred characters.

        Parameters:
        s - a set of characters to be searched for.
        from - the index from which the search must start.
        Returns:
        the index of the last occurrence of any character in s, or -1, if no character in s ever appears with index smaller than or equal to from.

      • lastIndexOfAnyOf

        public int lastIndexOfAnyOf​(CharSet s)
        Returns the index of the last occurrence of any of the specified characters.
        Parameters:
        s - a set of characters to be searched for.
        Returns:
        the index of the last occurrence of any of the characters in s, or -1, if no such character ever appears.
        See Also:
        lastIndexOfAnyOf(CharSet, int)

      • lastIndexOfAnyOf

        public int lastIndexOfAnyOf​(char[] c,
                            int from)
        Returns the index of the last occurrence of any of the specified characters, searching backwards starting at the specified index.

        This method uses a Bloom filter to avoid repeated linear scans of the array c; however, this optimisation will be most effective with arrays of less than twenty characters, and, in fact, will very slightly slow down searches for more than one hundred characters.

        Parameters:
        c - an array of characters to be searched for.
        from - the index from which the search must start.
        Returns:
        the index of the last occurrence of any character in c, or -1, if no character in c ever appears with index smaller than or equal to from.

      • lastIndexOfAnyOf

        public int lastIndexOfAnyOf​(char[] c)
        Returns the index of the last occurrence of any of the specified characters.
        Parameters:
        c - an array of characters to be searched for.
        Returns:
        the index of the last occurrence of any of the characters in c, or -1, if no such character ever appears.
        See Also:
        lastIndexOfAnyOf(char[], int)

      • lastIndexOfAnyBut

        public int lastIndexOfAnyBut​(CharSet s,
                             int from)
        Returns the index of the last occurrence of any character, except those specified, starting at the specified index.

        This method uses a Bloom filter to avoid repeated linear scans of the array c; however, this optimisation will be most effective with arrays of less than twenty characters, and, in fact, will very slightly slow down searches for more than one hundred characters.

        Parameters:
        s - a set of characters to be searched for.
        from - the index from which the search must start.
        Returns:
        the index of the last occurrence of any of the characters not in c, or -1, if no such character ever appears.

      • lastIndexOfAnyBut

        public int lastIndexOfAnyBut​(CharSet s)
        Returns the index of the last occurrence of any character, except those specified.
        Parameters:
        s - a set of characters to be searched for.
        Returns:
        the index of the last occurrence of any of the characters not in s, or -1, if no such character ever appears.
        See Also:
        lastIndexOfAnyBut(CharSet,int)

      • lastIndexOfAnyBut

        public int lastIndexOfAnyBut​(char[] c,
                             int from)
        Returns the index of the last occurrence of any character, except those specified, starting at the specified index.

        This method uses a Bloom filter to avoid repeated linear scans of the array c; however, this optimisation will be most effective with arrays of less than twenty characters, and, in fact, will very slightly slow down searches for more than one hundred characters.

        Parameters:
        c - an array of characters to be searched for.
        from - the index from which the search must start.
        Returns:
        the index of the last occurrence of any of the characters not in c, or -1, if no such character ever appears.

      • lastIndexOfAnyBut

        public int lastIndexOfAnyBut​(char[] c)
        Returns the index of the last occurrence of any character, except those specified.
        Parameters:
        c - an array of characters to be searched for.
        Returns:
        the index of the last occurrence of any of the characters not in c, or -1, if no such character ever appears.
        See Also:
        lastIndexOfAnyBut(char[],int)

      • span

        public int span​(CharSet s,
                int from)
        Spans a segment of this mutable string made of the specified characters.
        Parameters:
        s - a set of characters.
        from - the index from which to span.
        Returns:
        the length of the maximal subsequence of this mutable string made of characters in s starting at from.
        See Also:
        cospan(CharSet, int)

      • span

        public int span​(CharSet s)
        Spans the initial segment of this mutable string made of the specified characters.
        Parameters:
        s - a set of characters.
        Returns:
        the length of the maximal initial subsequence of this mutable string made of characters in s.
        See Also:
        span(CharSet, int)

      • span

        public int span​(char[] c,
                int from)
        Spans a segment of this mutable string made of the specified characters.

        This method uses a Bloom filter to avoid repeated linear scans of the array c; however, this optimisation will be most effective with arrays of less than twenty characters, and, in fact, will very slightly slow down searches for more than one hundred characters.

        Parameters:
        c - an array of characters.
        from - the index from which to span.
        Returns:
        the length of the maximal subsequence of this mutable string made of characters in c starting at from.
        See Also:
        cospan(char[], int)

      • span

        public int span​(char[] c)
        Spans the initial segment of this mutable string made of the specified characters.
        Parameters:
        c - an array of characters.
        Returns:
        the length of the maximal initial subsequence of this mutable string made of characters in c.
        See Also:
        span(char[], int)

      • cospan

        public int cospan​(CharSet s,
                  int from)
        Spans a segment of this mutable string made of the complement of the specified characters.
        Parameters:
        s - a set of characters.
        from - the index from which to span.
        Returns:
        the length of the maximal subsequence of this mutable string made of characters not in s starting at from.
        See Also:
        span(CharSet, int)

      • cospan

        public int cospan​(CharSet s)
        Spans the initial segment of this mutable string made of the complement of the specified characters.
        Parameters:
        s - a set of characters.
        Returns:
        the length of the maximal initial subsequence of this mutable string made of characters not in s.
        See Also:
        cospan(CharSet, int)

      • cospan

        public int cospan​(char[] c,
                  int from)
        Spans a segment of this mutable string made of the complement of the specified characters.

        This method uses a Bloom filter to avoid repeated linear scans of the array c; however, this optimisation will be most effective with arrays of less than twenty characters, and, in fact, will very slightly slow down searches for more than one hundred characters.

        Parameters:
        c - an array of characters.
        from - the index from which to span.
        Returns:
        the length of the maximal subsequence of this mutable string made of characters not in c starting at from.
        See Also:
        span(char[], int)

      • cospan

        public int cospan​(char[] c)
        Spans the initial segment of this mutable string made of the complement of the specified characters.
        Parameters:
        c - an array of characters.
        Returns:
        the length of the maximal initial subsequence of this mutable string made of characters not in c.
        See Also:
        cospan(char[], int)

      • startsWith

        public final boolean startsWith​(MutableString prefix)
        Returns whether this mutable string starts with the given mutable string.
        Parameters:
        prefix - a mutable string.
        Returns:
        true if this mutable string starts with prefix.

      • startsWith

        public final boolean startsWith​(String prefix)
        Returns whether this mutable string starts with the given string.
        Parameters:
        prefix - a string.
        Returns:
        true if this mutable string starts with prefix.

      • startsWith

        public final boolean startsWith​(CharSequence prefix)
        Returns whether this mutable string starts with the given character sequence.
        Parameters:
        prefix - a character sequence.
        Returns:
        true if this mutable string starts with prefix.

      • startsWithIgnoreCase

        public final boolean startsWithIgnoreCase​(MutableString prefix)
        Returns whether this mutable string starts with the given mutable string disregarding case.
        Parameters:
        prefix - a mutable string.
        Returns:
        true if this mutable string starts with prefix up to case.

      • startsWithIgnoreCase

        public final boolean startsWithIgnoreCase​(String prefix)
        Returns whether this mutable string starts with the given string disregarding case.
        Parameters:
        prefix - a string.
        Returns:
        true if this mutable string starts with prefix up to case.

      • startsWithIgnoreCase

        public final boolean startsWithIgnoreCase​(CharSequence prefix)
        Returns whether this mutable string starts with the given character sequence disregarding case.
        Parameters:
        prefix - a character sequence.
        Returns:
        true if this mutable string starts with prefix up to case.

      • endsWith

        public final boolean endsWith​(MutableString suffix)
        Returns whether this mutable string ends with the given mutable string.
        Parameters:
        suffix - a mutable string.
        Returns:
        true if this mutable string ends with suffix.

      • endsWith

        public final boolean endsWith​(String suffix)
        Returns whether this mutable string ends with the given string.
        Parameters:
        suffix - a string.
        Returns:
        true if this mutable string ends with suffix.

      • endsWith

        public final boolean endsWith​(CharSequence suffix)
        Returns whether this mutable string ends with the given character sequence.
        Parameters:
        suffix - a character sequence.
        Returns:
        true if this mutable string ends with prefix.

      • endsWithIgnoreCase

        public final boolean endsWithIgnoreCase​(MutableString suffix)
        Returns whether this mutable string ends with the given mutable string disregarding case.
        Parameters:
        suffix - a mutable string.
        Returns:
        true if this mutable string ends with suffix up to case.

      • endsWithIgnoreCase

        public final boolean endsWithIgnoreCase​(String suffix)
        Returns whether this mutable string ends with the given string disregarding case.
        Parameters:
        suffix - a string.
        Returns:
        true if this mutable string ends with suffix up to case.

      • endsWithIgnoreCase

        public final boolean endsWithIgnoreCase​(CharSequence suffix)
        Returns whether this mutable string ends with the given character sequence disregarding case.
        Parameters:
        suffix - a character sequence.
        Returns:
        true if this mutable string ends with prefix up to case.

      • toLowerCase

        public final MutableString toLowerCase()
        Converts all of the characters in this mutable string to lower case using the rules of the default locale.
        Returns:
        this mutable string.

      • toUpperCase

        public final MutableString toUpperCase()
        Converts all of the characters in this mutable string to upper case using the rules of the default locale.
        Returns:
        this mutable string.

      • trim

        public final MutableString trim()
        Trims all leading and trailing whitespace from this string. Whitespace here is any character smaller than ' ' (the ASCII space).
        Returns:
        this mutable string.

      • trimLeft

        public final MutableString trimLeft()
        Trims all leading whitespace from this string. Whitespace here is any character smaller than ' ' (the ASCII space).
        Returns:
        this mutable string.

      • trimRight

        public final MutableString trimRight()
        Trims all trailing whitespace from this string. Whitespace here is any character smaller than ' ' (the ASCII space).
        Returns:
        this mutable string.

      • squeezeWhitespace

        public final MutableString squeezeWhitespace()
        Squeezes and normalises whitespace in this mutable string. All subsequences of consecutive characters satisfying Character.isWhitespace(char) will be transformed into a single space.
        Returns:
        this mutable string.
        See Also:
        squeezeSpace()

      • squeezeSpace

        public final MutableString squeezeSpace()
        Squeezes and normalises spaces in this mutable string. All subsequences of consecutive characters satisfying Character.isSpaceChar(char) will be transformed into a single space.
        Returns:
        this mutable string.
        See Also:
        squeezeWhitespace()

      • reverse

        public final MutableString reverse()
        The characters in this mutable string get reversed.
        Returns:
        this mutable string.

      • read

        public final int read​(Reader r,
                      int length)
               throws IOException
        Reads a mutable string that has been written by write(Writer) from a Reader.

        If length is smaller than the current capacity or the number of characters actually read is smaller than length the string will become loose.

        Parameters:
        r - a Reader.
        length - the number of characters to read.
        Returns:
        The number of characters read, or -1 if the end of the stream has been reached.
        Throws:
        IOException - if thrown by the provided Reader.

      • writeUTF8

        @Deprecated
public final void writeUTF8​(DataOutput s)
                     throws IOException
        Deprecated.
        This method will not process surrogate pairs correctly.
        Writes this mutable string in UTF-8 encoding.

        The string is coded in UTF-8, not in the Java modified UTF representation. Thus, an ASCII NUL is represented by a single zero. Watch out!

        This method does not try to do any caching (in particular, it does not create any object). On non-buffered data outputs it might be very slow.

        Parameters:
        s - a data output.
        Throws:
        IOException - if s does.

      • readUTF8

        @Deprecated
public final MutableString readUTF8​(DataInput s,
                                    int length)
                             throws IOException
        Deprecated.
        This method will not process surrogate pairs correctly.
        Reads a mutable string in UTF-8 encoding.

        This method does not try to do any read-ahead (in particular, it does not create any object). On non-buffered data inputs it might be very slow.

        This method is able to read only strings containing UTF-8 sequences of at most 3 bytes. Longer sequences will cause a UTFDataFormatException.

        If length is smaller than the current capacity, the string will become loose.

        Parameters:
        s - a data input.
        length - the number of characters to read.
        Returns:
        this mutable string.
        Throws:
        UTFDataFormatException - on UTF-8 sequences longer than three octects.
        IOException - if s does.

      • writeSelfDelimUTF8

        public final void writeSelfDelimUTF8​(DataOutput s)
                              throws IOException
        Writes this mutable string to a DataOutput as a length followed by a UTF-8 encoding.

        The purpose of this method and of readSelfDelimUTF8(DataInput) is to provide a simple, ready-to-use (even if not particularly efficient) method for storing arbitrary mutable strings in a self-delimiting way.

        You can save any mutable string using this method. The length will be written in packed 7-bit format, that is, as a list of blocks of 7 bits (from higher to lower) in which the seventh bit determines whether there is another block in the list. For strings shorter than 27 characters, the length will be packed in one byte, for strings shorter than 214 in 2 bytes and so on.

        The string following the length is coded in UTF-8, not in the Java modified UTF representation. Thus, an ASCII NUL is represented by a single zero. Note also that surrogate pairs will be written as such, that is, without coalescing them into a single codepoint. Watch out!

        Parameters:
        s - a data output.
        Throws:
        IOException - if s does.

      • equals

        public final boolean equals​(Object o)
        Compares this mutable string to another object.

        This method will return true iff its argument is a CharSequence containing the same characters of this mutable string.

        A potentially nasty consequence is that equality is not symmetric. See the discussion in the class description.

        Overrides:
        equals in class Object
        Parameters:
        o - an Object.
        Returns:
        true if the argument is a CharSequences that contains the same characters of this mutable string.

      • equals

        public final boolean equals​(MutableString s)
        Type-specific version of equals(). This version of the equals(Object) method will be called on mutable strings.
        Parameters:
        s - a mutable string.
        Returns:
        true if the two mutable strings contain the same characters.
        See Also:
        equals(Object)

      • equals

        public final boolean equals​(String s)
        Type-specific version of equals(). This version of the equals(Object) method will be called on Strings. It is guaranteed that it will return true iff the mutable string and the String contain the same characters. Thus, you can use expressions like 
         mutableString.equals("Hello")
        to check against string contants.
        Parameters:
        s - a String.
        Returns:
        true if the String contain the same characters of this mutable string.
        See Also:
        equals(Object)

      • equals

        public final boolean equals​(CharSequence s)
        Type-specific version of equals(). This version of the equals(Object) method will be called on character sequences. It is guaranteed that it will return true iff this mutable string and the character sequence contain the same characters.
        Parameters:
        s - a character sequence.
        Returns:
        true if the character sequence contains the same characters of this mutable string.
        See Also:
        equals(Object)

      • equalsIgnoreCase

        public final boolean equalsIgnoreCase​(MutableString s)
        Checks two mutable strings for equality ignoring case.
        Parameters:
        s - a mutable string.
        Returns:
        true if the two mutable strings contain the same characters up to case.
        See Also:
        String.equalsIgnoreCase(String)

      • equalsIgnoreCase

        public final boolean equalsIgnoreCase​(String s)
        Type-specific version of equalsIgnoreCase().
        Parameters:
        s - a string.
        Returns:
        true if the string contains the same characters of this mutable string up to case.
        See Also:
        equalsIgnoreCase(MutableString)

      • equalsIgnoreCase

        public final boolean equalsIgnoreCase​(CharSequence s)
        Type-specific version of equalsIgnoreCase().
        Parameters:
        s - a character sequence.
        Returns:
        true if the character sequence contains the same characters of this mutable string up to case.
        See Also:
        equalsIgnoreCase(MutableString)

      • compareTo

        public final int compareTo​(MutableString s)
        Compares this mutable string to another mutable string performing a lexicographical comparison.
        Specified by:
        compareTo in interface Comparable<MutableString>
        Parameters:
        s - a mutable string.
        Returns:
        a negative integer, zero, or a positive integer as this mutable string is less than, equal to, or greater than the specified mutable string.

      • compareTo

        public final int compareTo​(String s)
        Compares this mutable string to a string performing a lexicographical comparison.
        Parameters:
        s - a String.
        Returns:
        a negative integer, zero, or a positive integer as this mutable string is less than, equal to, or greater than the specified String.

      • compareTo

        public final int compareTo​(CharSequence s)
        Compares this mutable string to a character sequence performing a lexicographical comparison.
        Parameters:
        s - a character sequence.
        Returns:
        a negative integer, zero, or a positive integer as this mutable string is less than, equal to, or greater than the specified character sequence.

      • compareToIgnoreCase

        public final int compareToIgnoreCase​(MutableString s)
        Compares this mutable string to another object disregarding case. If the argument is a character sequence, this method performs a lexicographical comparison; otherwise, it throws a ClassCastException.

        A potentially nasty consequence is that comparisons are not symmetric. See the discussion in the class description.

        Parameters:
        s - a mutable string.
        Returns:
        a negative integer, zero, or a positive integer as this mutable string is less than, equal to, or greater than the specified mutable string once case differences have been eliminated.
        See Also:
        String.compareToIgnoreCase(String)

      • compareToIgnoreCase

        public final int compareToIgnoreCase​(String s)
        Type-specific version of compareToIgnoreCase().
        Parameters:
        s - a mutable string.
        Returns:
        a negative integer, zero, or a positive integer as this mutable string is less than, equal to, or greater than the specified string once case differences have been eliminated.
        See Also:
        compareToIgnoreCase(MutableString)

      • compareToIgnoreCase

        public final int compareToIgnoreCase​(CharSequence s)
        Type-specific version of compareToIgnoreCase().
        Parameters:
        s - a mutable string.
        Returns:
        a negative integer, zero, or a positive integer as this mutable string is less than, equal to, or greater than the specified character sequence once case differences have been eliminated.
        See Also:
        compareToIgnoreCase(MutableString)

      • hashCode

        public final int hashCode()
        Returns a hash code for this mutable string.

        The hash code of a mutable string is the same as that of a String with the same content, but with the leftmost bit set.

        A compact mutable string caches its hash code, so it is very efficient on data structures that check hash codes before invoking equals().

        Overrides:
        hashCode in class Object
        Returns:
        a hash code array for this object.
        See Also:
        String.hashCode()