Class FormattedStringBuilder

  • All Implemented Interfaces:
    java.lang.Appendable, java.lang.CharSequence

    public class FormattedStringBuilder
    extends java.lang.Object
    implements java.lang.CharSequence, java.lang.Appendable
    A StringBuilder optimized for formatting. It implements the following key features beyond a normal JDK StringBuilder:
    1. Efficient prepend as well as append.
    2. Keeps tracks of Fields in an efficient manner.
    3. String operations are fast-pathed to code point operations when possible.
    See also FormattedValueStringBuilderImpl.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      (package private) java.lang.Object appendableField
      Field applied when Appendable methods are used.
      (package private) int appendOffset
      Number of characters from the end where .append() operations insert.
      (package private) char[] chars  
      static FormattedStringBuilder EMPTY
      A constant, empty FormattedStringBuilder.
      (package private) java.lang.Object[] fields  
      private static java.util.Map<java.lang.Object,​java.lang.Character> fieldToDebugChar  
      (package private) int length  
      (package private) int zero  
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      java.lang.Appendable append​(char c)
      This method is provided for Java Appendable compatibility.
      int append​(char[] chars, java.lang.Object[] fields)
      Appends the chars in the specified char array to the end of the string, and associates them with the fields in the specified field array, which must have the same length as chars.
      int append​(FormattedStringBuilder other)
      Appends the contents of another FormattedStringBuilder to the end of this instance.
      java.lang.Appendable append​(java.lang.CharSequence csq)
      This method is provided for Java Appendable compatibility.
      java.lang.Appendable append​(java.lang.CharSequence csq, int start, int end)
      This method is provided for Java Appendable compatibility.
      int append​(java.lang.CharSequence sequence, java.lang.Object field)
      Appends the specified CharSequence to the end of the string.
      int appendChar16​(char codeUnit, java.lang.Object field)  
      int appendCodePoint​(int codePoint, java.lang.Object field)
      Appends the specified codePoint to the end of the string.
      char charAt​(int index)  
      FormattedStringBuilder clear()  
      int codePointAt​(int index)  
      int codePointBefore​(int index)  
      int codePointCount()  
      boolean contentEquals​(char[] chars, java.lang.Object[] fields)  
      boolean contentEquals​(FormattedStringBuilder other)  
      void copyFrom​(FormattedStringBuilder source)  
      boolean equals​(java.lang.Object other)  
      java.lang.Object fieldAt​(int index)  
      private int getCapacity()  
      int getFirstCodePoint()  
      int getLastCodePoint()  
      int hashCode()  
      int insert​(int index, char[] chars, java.lang.Object[] fields)
      Inserts the chars in the specified char array at the specified index in the string, and associates them with the fields in the specified field array, which must have the same length as chars.
      int insert​(int index, FormattedStringBuilder other)
      Inserts the contents of another FormattedStringBuilder into this instance at the given index.
      int insert​(int index, java.lang.CharSequence sequence, int start, int end, java.lang.Object field)
      Inserts the specified CharSequence at the specified index in the string, reading from the CharSequence from start (inclusive) to end (exclusive).
      int insert​(int index, java.lang.CharSequence sequence, java.lang.Object field)
      Inserts the specified CharSequence at the specified index in the string.
      int insertChar16​(int index, char codeUnit, java.lang.Object field)  
      int insertCodePoint​(int index, int codePoint, java.lang.Object field)
      Inserts the specified codePoint at the specified index in the string.
      int length()  
      private int prepareForInsert​(int index, int count)
      Shifts around existing data if necessary to make room for new characters.
      private int prepareForInsertHelper​(int index, int count)  
      private int remove​(int index, int count)
      Removes the "count" chars starting at "index".
      void setAppendableField​(java.lang.Object field)
      Call this method before using any of the Appendable overrides.
      void setAppendIndex​(int index)
      Sets the index at which append operations insert.
      int splice​(int startThis, int endThis, java.lang.CharSequence sequence, int startOther, int endOther, java.lang.Object field)
      Replaces the chars between startThis and endThis with the chars between startOther and endOther of the given CharSequence.
      java.lang.CharSequence subSequence​(int start, int end)
      Deprecated.
      java.lang.String subString​(int start, int end)
      Use this instead of subSequence if returning publicly.
      char[] toCharArray()  
      java.lang.String toDebugString()
      Returns a string that includes field information, for debugging purposes.
      java.lang.Object[] toFieldArray()  
      java.lang.String toString()
      Returns the string represented by the characters in this string builder.
      static java.text.Format.Field unwrapField​(java.lang.Object field)  
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
      • Methods inherited from interface java.lang.CharSequence

        chars, codePoints
    • Field Detail

      • EMPTY

        public static final FormattedStringBuilder EMPTY
        A constant, empty FormattedStringBuilder. Do NOT call mutative operations on this.
      • chars

        char[] chars
      • fields

        java.lang.Object[] fields
      • zero

        int zero
      • length

        int length
      • appendOffset

        int appendOffset
        Number of characters from the end where .append() operations insert.
      • appendableField

        java.lang.Object appendableField
        Field applied when Appendable methods are used.
      • fieldToDebugChar

        private static final java.util.Map<java.lang.Object,​java.lang.Character> fieldToDebugChar
    • Constructor Detail

      • FormattedStringBuilder

        public FormattedStringBuilder()
      • FormattedStringBuilder

        public FormattedStringBuilder​(int capacity)
    • Method Detail

      • unwrapField

        public static java.text.Format.Field unwrapField​(java.lang.Object field)
      • length

        public int length()
        Specified by:
        length in interface java.lang.CharSequence
      • codePointCount

        public int codePointCount()
      • charAt

        public char charAt​(int index)
        Specified by:
        charAt in interface java.lang.CharSequence
      • fieldAt

        public java.lang.Object fieldAt​(int index)
      • getFirstCodePoint

        public int getFirstCodePoint()
      • getLastCodePoint

        public int getLastCodePoint()
      • codePointAt

        public int codePointAt​(int index)
      • codePointBefore

        public int codePointBefore​(int index)
      • setAppendIndex

        public void setAppendIndex​(int index)
        Sets the index at which append operations insert. Defaults to the end.
        Parameters:
        index - The index at which append operations should insert.
      • appendChar16

        public int appendChar16​(char codeUnit,
                                java.lang.Object field)
      • insertChar16

        public int insertChar16​(int index,
                                char codeUnit,
                                java.lang.Object field)
      • appendCodePoint

        public int appendCodePoint​(int codePoint,
                                   java.lang.Object field)
        Appends the specified codePoint to the end of the string.
        Returns:
        The number of chars added: 1 if the code point is in the BMP, or 2 otherwise.
      • insertCodePoint

        public int insertCodePoint​(int index,
                                   int codePoint,
                                   java.lang.Object field)
        Inserts the specified codePoint at the specified index in the string.
        Returns:
        The number of chars added: 1 if the code point is in the BMP, or 2 otherwise.
      • append

        public int append​(java.lang.CharSequence sequence,
                          java.lang.Object field)
        Appends the specified CharSequence to the end of the string.
        Returns:
        The number of chars added, which is the length of CharSequence.
      • insert

        public int insert​(int index,
                          java.lang.CharSequence sequence,
                          java.lang.Object field)
        Inserts the specified CharSequence at the specified index in the string.
        Returns:
        The number of chars added, which is the length of CharSequence.
      • insert

        public int insert​(int index,
                          java.lang.CharSequence sequence,
                          int start,
                          int end,
                          java.lang.Object field)
        Inserts the specified CharSequence at the specified index in the string, reading from the CharSequence from start (inclusive) to end (exclusive).
        Returns:
        The number of chars added, which is the length of CharSequence.
      • splice

        public int splice​(int startThis,
                          int endThis,
                          java.lang.CharSequence sequence,
                          int startOther,
                          int endOther,
                          java.lang.Object field)
        Replaces the chars between startThis and endThis with the chars between startOther and endOther of the given CharSequence. Calling this method with startThis == endThis is equivalent to calling insert.
        Returns:
        The number of chars added, which may be negative if the removed segment is longer than the length of the CharSequence segment that was inserted.
      • append

        public int append​(char[] chars,
                          java.lang.Object[] fields)
        Appends the chars in the specified char array to the end of the string, and associates them with the fields in the specified field array, which must have the same length as chars.
        Returns:
        The number of chars added, which is the length of the char array.
      • insert

        public int insert​(int index,
                          char[] chars,
                          java.lang.Object[] fields)
        Inserts the chars in the specified char array at the specified index in the string, and associates them with the fields in the specified field array, which must have the same length as chars.
        Returns:
        The number of chars added, which is the length of the char array.
      • prepareForInsert

        private int prepareForInsert​(int index,
                                     int count)
        Shifts around existing data if necessary to make room for new characters.
        Parameters:
        index - The location in the string where the operation is to take place.
        count - The number of chars (UTF-16 code units) to be inserted at that location.
        Returns:
        The position in the char array to insert the chars.
      • prepareForInsertHelper

        private int prepareForInsertHelper​(int index,
                                           int count)
      • remove

        private int remove​(int index,
                           int count)
        Removes the "count" chars starting at "index". Returns the position at which the chars were removed.
      • getCapacity

        private int getCapacity()
      • subSequence

        @Deprecated
        public java.lang.CharSequence subSequence​(int start,
                                                  int end)
        Deprecated.
        Note: this returns a FormattedStringBuilder. Do not return publicly.
        Specified by:
        subSequence in interface java.lang.CharSequence
      • subString

        public java.lang.String subString​(int start,
                                          int end)
        Use this instead of subSequence if returning publicly.
      • toString

        public java.lang.String toString()
        Returns the string represented by the characters in this string builder.

        For a string intended be used for debugging, use toDebugString().

        Specified by:
        toString in interface java.lang.CharSequence
        Overrides:
        toString in class java.lang.Object
      • toDebugString

        public java.lang.String toDebugString()
        Returns a string that includes field information, for debugging purposes.

        For example, if the string is "-12.345", the debug string will be something like "<FormattedStringBuilder [-123.45] [-iii.ff]>"

        Returns:
        A string for debugging purposes.
      • toCharArray

        public char[] toCharArray()
        Returns:
        A new array containing the contents of this string builder.
      • toFieldArray

        public java.lang.Object[] toFieldArray()
        Returns:
        A new array containing the field values of this string builder.
      • setAppendableField

        public void setAppendableField​(java.lang.Object field)
        Call this method before using any of the Appendable overrides.
        Parameters:
        field - The field used when inserting strings.
      • append

        public java.lang.Appendable append​(java.lang.CharSequence csq)
        This method is provided for Java Appendable compatibility. In most cases, please use the append methods that take a Field parameter. If you do use this method, you must call setAppendableField(java.lang.Object) first.
        Specified by:
        append in interface java.lang.Appendable
      • append

        public java.lang.Appendable append​(java.lang.CharSequence csq,
                                           int start,
                                           int end)
        This method is provided for Java Appendable compatibility. In most cases, please use the append methods that take a Field parameter. If you do use this method, you must call setAppendableField(java.lang.Object) first.
        Specified by:
        append in interface java.lang.Appendable
      • append

        public java.lang.Appendable append​(char c)
        This method is provided for Java Appendable compatibility. In most cases, please use the append methods that take a Field parameter. If you do use this method, you must call setAppendableField(java.lang.Object) first.
        Specified by:
        append in interface java.lang.Appendable
      • contentEquals

        public boolean contentEquals​(char[] chars,
                                     java.lang.Object[] fields)
        Returns:
        Whether the contents and field values of this string builder are equal to the given chars and fields.
        See Also:
        toCharArray(), toFieldArray()
      • contentEquals

        public boolean contentEquals​(FormattedStringBuilder other)
        Parameters:
        other - The instance to compare.
        Returns:
        Whether the contents of this instance is currently equal to the given instance.
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • equals

        public boolean equals​(java.lang.Object other)
        Overrides:
        equals in class java.lang.Object