Class AttributedString

All Implemented Interfaces:
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:
  • Field Details

    • 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 Details

    • AttributedString

      public AttributedString(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(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:
      InvalidParameterException - if end is less than start
    • AttributedString

      public AttributedString(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(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:
      InvalidParameterException - if end is less than start
  • Method Details

    • fromAnsi

      public static AttributedString fromAnsi(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

      public static AttributedString fromAnsi(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(String ansi, List<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(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(String ansi, List<Integer> tabs, String altIn, 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 String stripAnsi(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:
      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 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:
      IndexOutOfBoundsException - if start or end are negative, if end is greater than length(), or if start is greater than end
    • styleMatches

      public AttributedString styleMatches(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(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 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 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:
      NullPointerException - if delimiter or elements is null
    • join

      public static AttributedString join(AttributedString delimiter, 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:
      NullPointerException - if elements is null