Class AttributedString
- All Implemented Interfaces:
CharSequence
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:
-
Nested Class Summary
Nested classes/interfaces inherited from class org.jline.utils.AttributedCharSequence
AttributedCharSequence.ForceMode
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final AttributedString
An empty AttributedString with no characters.static final AttributedString
An AttributedString containing only a newline character.Fields inherited from class org.jline.utils.AttributedCharSequence
TRUE_COLORS
-
Constructor Summary
ConstructorsConstructorDescriptionCreates a new AttributedString from the specified character sequence.AttributedString
(CharSequence str, int start, int end) Creates a new AttributedString from a subsequence of the specified character sequence.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.Creates a new AttributedString from the specified character sequence with the specified style. -
Method Summary
Modifier and TypeMethodDescriptionprotected char[]
buffer()
Returns the character buffer for this attributed string.boolean
Compares this AttributedString with another object for equality.static AttributedString
Creates an AttributedString from an ANSI-encoded string.static AttributedString
Creates an AttributedString from an ANSI-encoded string with a specified tab size.static AttributedString
Creates an AttributedString from an ANSI-encoded string with custom tab stops.static AttributedString
Creates an AttributedString from an ANSI-encoded string with custom tab stops and alternate character set sequences.static AttributedString
Creates an AttributedString from an ANSI-encoded string, using terminal capabilities.int
hashCode()
Returns a hash code for this AttributedString.static AttributedString
join
(AttributedString delimiter, Iterable<AttributedString> elements) Joins an Iterable of AttributedString objects with a delimiter.static AttributedString
join
(AttributedString delimiter, AttributedString... elements) Joins multiple AttributedString objects with a delimiter.int
length()
Returns the length of this attributed string.protected int
offset()
Returns the offset in the buffer where this attributed string starts.static String
Strips ANSI escape sequences from a string.styleAt
(int index) Returns the style at the specified index in this attributed string.styleMatches
(Pattern pattern, AttributedStyle style) Returns a new AttributedString with the specified style applied to all matches of the pattern.subSequence
(int start, int end) Returns a new AttributedString that is a subsequence of this attributed string.Methods inherited from class org.jline.utils.AttributedCharSequence
charAt, codePointAt, codePointBefore, codePointCount, columnLength, columnSplitLength, columnSplitLength, columnSubSequence, contains, isHidden, print, println, rgbColor, roundColor, roundRgbColor, runLimit, runStart, substring, toAnsi, toAnsi, toAnsi, toAnsi, toAnsi, toAnsi, toAnsi, toAttributedString, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface java.lang.CharSequence
chars, codePoints, isEmpty
-
Field Details
-
EMPTY
An empty AttributedString with no characters. -
NEWLINE
An AttributedString containing only a newline character.
-
-
Constructor Details
-
AttributedString
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
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 copystart
- 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
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 copys
- the style to apply to all characters, or null for default style
-
AttributedString
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 copystart
- 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
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
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 parsetabs
- the tab size in columns- Returns:
- an AttributedString with styles based on the ANSI escape sequences
-
fromAnsi
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 parsetabs
- the list of tab stop positions, or null for default tab stops- Returns:
- an AttributedString with styles based on the ANSI escape sequences
-
fromAnsi
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 parseterminal
- 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 parsetabs
- the list of tab stop positions, or null for default tab stopsaltIn
- the sequence to enable the alternate character set, or nullaltOut
- the sequence to disable the alternate character set, or null- Returns:
- an AttributedString with styles based on the ANSI escape sequences
-
stripAnsi
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 classAttributedCharSequence
- 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 classAttributedCharSequence
- 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
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 classAttributedCharSequence
- 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
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 interfaceCharSequence
- Specified by:
subSequence
in classAttributedCharSequence
- Parameters:
start
- the start index, inclusiveend
- 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
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 matchstyle
- the style to apply to matching regions- Returns:
- a new AttributedString with the specified style applied to matching regions
-
equals
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.
-
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.
-
join
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 elementselements
- 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 delimiterelements
- the elements to join- Returns:
- a new AttributedString containing the joined elements
- Throws:
NullPointerException
- if elements is null
-