Class AttributedString

  • All Implemented Interfaces:
    java.lang.CharSequence

    public class AttributedString
    extends AttributedCharSequence
    An immutable character sequence with ANSI style attributes.

    The AttributedString class represents a character sequence where each character has associated style attributes (colors, bold, underline, etc.). It extends AttributedCharSequence and provides an immutable implementation, making it safe to use in concurrent contexts.

    Key features of this class include:

    • Immutability - Once created, instances cannot be modified
    • Memory efficiency - Substrings are created without any memory copy
    • Rich styling - Support for foreground/background colors and text attributes
    • Concatenation - Multiple AttributedStrings can be joined together
    • Pattern matching - Regular expressions can be applied to find and extract parts

    This class is commonly used for displaying styled text in terminal applications, such as prompts, menus, and highlighted output. For building AttributedStrings dynamically, use AttributedStringBuilder.

    See Also:
    AttributedCharSequence, AttributedStringBuilder, AttributedStyle
    • Field Detail

      • EMPTY

        public static final AttributedString EMPTY
        An empty AttributedString with no characters.
      • NEWLINE

        public static final AttributedString NEWLINE
        An AttributedString containing only a newline character.
    • Constructor Detail

      • AttributedString

        public AttributedString​(java.lang.CharSequence str)
        Creates a new AttributedString from the specified character sequence.

        This constructor creates a new AttributedString containing the characters from the specified character sequence with default style (no attributes).

        Parameters:
        str - the character sequence to copy
      • AttributedString

        public AttributedString​(java.lang.CharSequence str,
                                int start,
                                int end)
        Creates a new AttributedString from a subsequence of the specified character sequence.

        This constructor creates a new AttributedString containing the characters from the specified range of the character sequence with default style (no attributes).

        Parameters:
        str - the character sequence to copy
        start - the index of the first character to copy (inclusive)
        end - the index after the last character to copy (exclusive)
        Throws:
        java.security.InvalidParameterException - if end is less than start
      • AttributedString

        public AttributedString​(java.lang.CharSequence str,
                                AttributedStyle s)
        Creates a new AttributedString from the specified character sequence with the specified style.

        This constructor creates a new AttributedString containing the characters from the specified character sequence with the specified style applied to all characters.

        Parameters:
        str - the character sequence to copy
        s - the style to apply to all characters, or null for default style
      • AttributedString

        public AttributedString​(java.lang.CharSequence str,
                                int start,
                                int end,
                                AttributedStyle s)
        Creates a new AttributedString from a subsequence of the specified character sequence with the specified style.

        This constructor creates a new AttributedString containing the characters from the specified range of the character sequence with the specified style applied to all characters.

        If the character sequence is an AttributedString or AttributedStringBuilder, this constructor preserves the existing style information and applies the specified style on top of it (if not null).

        Parameters:
        str - the character sequence to copy
        start - the index of the first character to copy (inclusive)
        end - the index after the last character to copy (exclusive)
        s - the style to apply to all characters, or null to preserve existing styles
        Throws:
        java.security.InvalidParameterException - if end is less than start
    • Method Detail

      • fromAnsi

        public static AttributedString fromAnsi​(java.lang.String ansi)
        Creates an AttributedString from an ANSI-encoded string.

        This method parses the ANSI escape sequences in the input string and creates an AttributedString with the corresponding styles. This is useful for converting ANSI-colored output from external commands into styled text that can be displayed in the terminal.

        Parameters:
        ansi - the ANSI-encoded string to parse
        Returns:
        an AttributedString with styles based on the ANSI escape sequences
        See Also:
        fromAnsi(String, Terminal)
      • fromAnsi

        public static AttributedString fromAnsi​(java.lang.String ansi,
                                                int tabs)
        Creates an AttributedString from an ANSI-encoded string with a specified tab size.

        This method parses the ANSI escape sequences in the input string and creates an AttributedString with the corresponding styles. It also handles tab characters according to the specified tab size.

        Parameters:
        ansi - the ANSI-encoded string to parse
        tabs - the tab size in columns
        Returns:
        an AttributedString with styles based on the ANSI escape sequences
      • fromAnsi

        public static AttributedString fromAnsi​(java.lang.String ansi,
                                                java.util.List<java.lang.Integer> tabs)
        Creates an AttributedString from an ANSI-encoded string with custom tab stops.

        This method parses the ANSI escape sequences in the input string and creates an AttributedString with the corresponding styles. It also handles tab characters according to the specified tab stops.

        Parameters:
        ansi - the ANSI-encoded string to parse
        tabs - the list of tab stop positions, or null for default tab stops
        Returns:
        an AttributedString with styles based on the ANSI escape sequences
      • fromAnsi

        public static AttributedString fromAnsi​(java.lang.String ansi,
                                                Terminal terminal)
        Creates an AttributedString from an ANSI-encoded string, using terminal capabilities.

        This method parses the ANSI escape sequences in the input string and creates an AttributedString with the corresponding styles. It uses the specified terminal's capabilities to handle alternate character sets.

        Parameters:
        ansi - the ANSI-encoded string to parse
        terminal - the terminal to use for capabilities, or null
        Returns:
        an AttributedString with styles based on the ANSI escape sequences
      • fromAnsi

        public static AttributedString fromAnsi​(java.lang.String ansi,
                                                java.util.List<java.lang.Integer> tabs,
                                                java.lang.String altIn,
                                                java.lang.String altOut)
        Creates an AttributedString from an ANSI-encoded string with custom tab stops and alternate character set sequences.

        This method parses the ANSI escape sequences in the input string and creates an AttributedString with the corresponding styles. It also handles tab characters according to the specified tab stops and alternate character set sequences.

        Parameters:
        ansi - the ANSI-encoded string to parse
        tabs - the list of tab stop positions, or null for default tab stops
        altIn - the sequence to enable the alternate character set, or null
        altOut - the sequence to disable the alternate character set, or null
        Returns:
        an AttributedString with styles based on the ANSI escape sequences
      • stripAnsi

        public static java.lang.String stripAnsi​(java.lang.String ansi)
        Strips ANSI escape sequences from a string.

        This method removes all ANSI escape sequences from the input string, returning a plain text string with no styling information. This is useful for extracting the text content from ANSI-colored output.

        Parameters:
        ansi - the ANSI-encoded string to strip
        Returns:
        a plain text string with ANSI escape sequences removed, or null if the input is null
      • buffer

        protected char[] buffer()
        Returns the character buffer for this attributed string.

        This method is used internally by the AttributedCharSequence implementation to access the underlying character buffer.

        Specified by:
        buffer in class AttributedCharSequence
        Returns:
        the character buffer
      • offset

        protected int offset()
        Returns the offset in the buffer where this attributed string starts.

        This method is used internally by the AttributedCharSequence implementation to determine the starting position in the buffer.

        Specified by:
        offset in class AttributedCharSequence
        Returns:
        the offset in the buffer
      • length

        public int length()
        Returns the length of this attributed string.

        This method returns the number of characters in this attributed string.

        Returns:
        the number of characters in this attributed string
      • styleAt

        public AttributedStyle styleAt​(int index)
        Returns the style at the specified index in this attributed string.

        This method returns the AttributedStyle object associated with the character at the specified index in this attributed string.

        Specified by:
        styleAt in class AttributedCharSequence
        Parameters:
        index - the index of the character whose style to return
        Returns:
        the style at the specified index
        Throws:
        java.lang.IndexOutOfBoundsException - if the index is out of range
      • subSequence

        public AttributedString subSequence​(int start,
                                            int end)
        Returns a new AttributedString that is a subsequence of this attributed string.

        This method returns a new AttributedString that contains the characters and styles from this attributed string starting at the specified start index (inclusive) and ending at the specified end index (exclusive).

        The subsequence preserves the style information from the original string.

        Specified by:
        subSequence in interface java.lang.CharSequence
        Specified by:
        subSequence in class AttributedCharSequence
        Parameters:
        start - the start index, inclusive
        end - the end index, exclusive
        Returns:
        the specified subsequence with its attributes
        Throws:
        java.lang.IndexOutOfBoundsException - if start or end are negative, if end is greater than length(), or if start is greater than end
      • styleMatches

        public AttributedString styleMatches​(java.util.regex.Pattern pattern,
                                             AttributedStyle style)
        Returns a new AttributedString with the specified style applied to all matches of the pattern.

        This method finds all matches of the specified regular expression pattern in this attributed string and applies the specified style to the matching regions. It returns a new AttributedString with the modified styles.

        If no matches are found, this method returns the original attributed string.

        Parameters:
        pattern - the regular expression pattern to match
        style - the style to apply to matching regions
        Returns:
        a new AttributedString with the specified style applied to matching regions
      • equals

        public boolean equals​(java.lang.Object o)
        Compares this AttributedString with another object for equality.

        Two AttributedString objects are considered equal if they have the same length, the same characters, and the same styles at each position.

        Overrides:
        equals in class java.lang.Object
        Parameters:
        o - the object to compare with
        Returns:
        true if the objects are equal, false otherwise
      • hashCode

        public int hashCode()
        Returns a hash code for this AttributedString.

        The hash code is computed based on the characters, styles, and range of this attributed string.

        Overrides:
        hashCode in class java.lang.Object
        Returns:
        a hash code value for this object
      • join

        public static AttributedString join​(AttributedString delimiter,
                                            AttributedString... elements)
        Joins multiple AttributedString objects with a delimiter.

        This method concatenates the specified AttributedString elements, inserting the specified delimiter between each element. The resulting AttributedString preserves the styles of all elements and the delimiter.

        Parameters:
        delimiter - the delimiter to insert between elements
        elements - the elements to join
        Returns:
        a new AttributedString containing the joined elements
        Throws:
        java.lang.NullPointerException - if delimiter or elements is null
      • join

        public static AttributedString join​(AttributedString delimiter,
                                            java.lang.Iterable<AttributedString> elements)
        Joins an Iterable of AttributedString objects with a delimiter.

        This method concatenates the AttributedString elements in the specified Iterable, inserting the specified delimiter between each element. The resulting AttributedString preserves the styles of all elements and the delimiter.

        If the delimiter is null, the elements are concatenated without any separator.

        Parameters:
        delimiter - the delimiter to insert between elements, or null for no delimiter
        elements - the elements to join
        Returns:
        a new AttributedString containing the joined elements
        Throws:
        java.lang.NullPointerException - if elements is null