Package com.dua3.utility.text

Class RichText

java.lang.Object
com.dua3.utility.text.RichText
All Implemented Interfaces:
AttributedCharSequence, RichTextRuns, ToRichText, CharSequence, Iterable<Run>
public final class RichText extends Object implements AttributedCharSequence, ToRichText, RichTextRuns
A class for rich text, i.e., text together with attributes like color, font etc.

Sequences of characters that share the same formatting attributes form a Run. Use RichTextBuilder create RichText instances.

  • Field Details

    • SPLIT_MARKER

      public static final int SPLIT_MARKER
      A character used as a delimiter or marker to insert where subsequent text segment should not be joined into a single one.

      When two texts both marked to have italic style are joined, the RichTextBuilder class will not detect the attribute change and for example when converted to HTML, the result of the joined texts will not be "<i>some text </i><i>other text</i>" but instead "<i>some text other text<i>".

      For attributes that merely control text appearance, this is usually the desired result. But to prevent two paragraphs to be joined into a single one, at least one character must come between both texts so that the change can be detected. A SPLIT_MARKER can thus be inserted to make sure the paragraphs are not joined.

      The HtmlConverter class for example automatically removes SPLIT_MARKER from the output.

      See Also:

  • Method Details

    • emptyText

      public static RichText emptyText()
      Returns the empty String as RichText.
      Returns:
      the empty text

    • space

      public static RichText space()
      Returns RichText containing a single space character.
      Returns:
      RichText.valueOf(" ")

    • tab

      public static RichText tab()
      Returns RichText containing a single tabulator.
      Returns:
      RichText.valueOf(" \ t ")

    • newline

      public static RichText newline()
      Returns RichText containing a single newline character.
      Returns:
      RichText.valueOf(" \ n ")

    • valueOf

      public static RichText valueOf(@Nullable Object obj)
      Get RichText containing an objects string representation.
      Parameters:
      obj - the object to convert to RichText
      Returns:
      RichText.valueOf(String.valueOf ( obj))

    • valueOf

      public static RichText valueOf(@Nullable String s)
      Convert String to RichText.
      Parameters:
      s - the String to convert
      Returns:
      RichText representation of s

    • valueOf

      public static RichText valueOf(@Nullable String s, Map<String,@Nullable Object> attributes)
      Creates a new RichText instance with the given string and applies the specified style.
      Parameters:
      s - the source string to be converted to RichText, may be null.
      attributes - the attributes to be applied to the RichText instance.
      Returns:
      a RichText instance containing the specified string with the applied style.

    • valueOf

      public static RichText valueOf(char c)
      Convert char to RichText.
      Parameters:
      c - the character
      Returns:
      RichText containing only the character c

    • valueOf

      public static RichText valueOf(@Nullable Object obj, Style... styles)
      Get styled RichText containing an object's string representation.
      Parameters:
      obj - the object to convert to RichText
      styles - the styles to apply
      Returns:
      RichText.valueOf(String.valueOf ( obj))

    • valueOf

      public static RichText valueOf(@Nullable Object obj, Collection<Style> styles)
      Get styled RichText containing an object's string representation.
      Parameters:
      obj - the object to convert to RichText
      styles - the styles to apply
      Returns:
      RichText representation of s

    • valueOf

      public static RichText valueOf(char c, Style... styles)
      Convert char to RichText.
      Parameters:
      c - the character
      styles - the styles to apply
      Returns:
      RichText containing only the character c

    • valueOf

      public static RichText valueOf(char c, Collection<Style> styles)
      Convert char to RichText.
      Parameters:
      c - the character
      styles - the styles to apply
      Returns:
      RichText containing only the character c

    • textAndFontEquals

      public static boolean textAndFontEquals(@Nullable RichText a, @Nullable RichText b)
      Check if texts and style are equal, ignoring other attributes.
      Parameters:
      a - text
      b - text
      Returns:
      true, if a and b consist of the same characters with the same styling

    • join

      public static RichText join(CharSequence delimiter, CharSequence... elements)
      Join RichText instances together.
      Parameters:
      delimiter - the delimiter
      elements - the elements to join
      Returns:
      RichText containing the joined elements

    • join

      public static RichText join(CharSequence delimiter, Iterable<? extends CharSequence> elements)
      Join RichText instances together.
      Parameters:
      delimiter - the delimiter
      elements - the elements to join
      Returns:
      RichText containing the joined elements

    • matcher

      public static RichTextMatcher matcher(Pattern pattern, RichText text)
      Create a RichTextMatcher.
      Parameters:
      pattern - the pattern
      text - the text
      Returns:
      a matcher

    • joiner

      public static RichTextJoiner joiner(RichText delimiter)
      Create a RichTextJoiner.
      Parameters:
      delimiter - the delimiter to use
      Returns:
      the joiner

    • joiner

      public static RichTextJoiner joiner(RichText delimiter, RichText prefix, RichText suffix)
      Create a RichTextJoiner.
      Parameters:
      delimiter - the delimiter to use
      prefix - the prefix
      suffix - the suffix
      Returns:
      the joiner

    • joiner

      public static RichTextJoiner joiner(String delimiter)
      Create a RichTextJoiner.
      Parameters:
      delimiter - the delimiter to use
      Returns:
      the joiner

    • joiner

      public static RichTextJoiner joiner(String delimiter, String prefix, String suffix)
      Create a RichTextJoiner.
      Parameters:
      delimiter - the delimiter to use
      prefix - the prefix
      suffix - the suffix
      Returns:
      the joiner

    • equals

      public boolean equals(@Nullable Object obj)
      Overrides:
      equals in class Object

    • equals

      public boolean equals(@Nullable RichText other, BiPredicate<? super Run,? super Run> runEquals)
      Compare using a user supplied predicate for comparing Run instances.
      Parameters:
      other - the object to compare to
      runEquals - the BiPredicate used for comparing
      Returns:
      result true, if obj is an instance of RichText and all runs compare as equal to this instance's runs using the supplied predicate

    • equalsTextAndFont

      public boolean equalsTextAndFont(@Nullable RichText other)
      Check if texts and style are equal, ignoring other attributes.
      Parameters:
      other - the text to compare with
      Returns:
      true, if other consist of the same characters with the same styling as this instance

    • equalsText

      public boolean equalsText(@Nullable CharSequence other)
      Textual compare.
      Parameters:
      other - the CharSequence to compare to
      Returns:
      true, if this instance contains the same sequence of characters as other

    • equalsTextIgnoreCase

      public boolean equalsTextIgnoreCase(@Nullable CharSequence other)
      Textual compare ignoring case.
      Parameters:
      other - the CharSequence to compare to
      Returns:
      true, if this instance contains the same sequence of characters as other

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • isBlank

      public boolean isBlank()
      Test if blank.
      Returns:
      true if this instance is empty or contains only whitespace characters, false otherwise

    • iterator

      public Iterator<Run> iterator()
      Specified by:
      iterator in interface Iterable<Run>

    • length

      public int length()
      Length of text in characters.
      Specified by:
      length in interface CharSequence
      Returns:
      the text length

    • stream

      public Stream<Run> stream()
      A stream of the Runs this text consists of.
      Returns:
      stream of Runs

    • toString

      public String toString()
      Specified by:
      toString in interface CharSequence
      Overrides:
      toString in class Object

    • appendTo

      public void appendTo(RichTextBuilder builder)
      Description copied from interface: ToRichText
      Append this object's rich text representation to a buffer.
      Specified by:
      appendTo in interface ToRichText
      Parameters:
      builder - the builder

    • appendTo

      public void appendTo(RichTextBuilder builder, int from, int to)
      Appends a subset of rich text content to the specified RichTextBuilder. The content to be appended is determined by the specified start and end indices.
      Specified by:
      appendTo in interface ToRichText
      Parameters:
      builder - the RichTextBuilder to which the content will be appended
      from - the start index (inclusive) of the content to be appended
      to - the end index (exclusive) of the content to be appended
      Throws:
      IndexOutOfBoundsException - if the specified start or end indices are out of bounds or if start is greater than end
      NullPointerException - if builder is null

    • toRichText

      public RichText toRichText()
      Description copied from interface: ToRichText
      Get RichText representation of this object (similar to toString()).
      Specified by:
      toRichText in interface ToRichText
      Returns:
      RichText presentation of the object

    • lines

      public Stream<RichText> lines()
      Get stream of lines contained in this instance.
      Returns:
      stream of this text's lines

    • subSequence

      public RichText subSequence(int start, int end)
      Get a subrange of this instance.
      Specified by:
      subSequence in interface AttributedCharSequence
      Specified by:
      subSequence in interface CharSequence
      Parameters:
      start - begin index (inclusive)
      end - end index (exclusive)
      Returns:
      RichText instance of the subrange

    • subSequence

      public RichText subSequence(int start)
      Get a subrange of this instance.
      Parameters:
      start - start index (inclusive)
      Returns:
      RichText instance of the subrange from beginIndex to the end

    • charAt

      public char charAt(int index)
      Specified by:
      charAt in interface CharSequence

    • attributedCharAt

      public AttributedCharacter attributedCharAt(int index)
      Description copied from interface: AttributedCharSequence
      Returns the AttributedCharacter value at the specified index.
      Specified by:
      attributedCharAt in interface AttributedCharSequence
      Parameters:
      index - the index of the AttributedCharacter value to be returned
      Returns:
      the specified AttributedCharacter value

    • attributesAt

      public TextAttributes attributesAt(int idx)
      Retrieves the text attributes at the specified index.
      Parameters:
      idx - the index for which the text attributes are requested
      Returns:
      the text attributes associated with the run at the specified index

    • trim

      public RichText trim()
      Remove leading and trailing whitespace, defined as "any character whose codepoint is less than or equal to 'U+0020' (the space character)".
      Returns:
      copy of this instance with leading and trailing whitespace according to above criteria removed
      See Also:

    • strip

      public RichText strip()
      Remove leading and trailing whitespace, as defined by Unicode, removed.
      Returns:
      copy of this instance with leading and trailing whitespace (according to Unicode) removed
      See Also:

    • stripLeading

      public RichText stripLeading()
      Remove leading whitespace, as defined by Unicode, removed.
      Returns:
      copy of this instance with leading whitespace (according to Unicode) removed
      See Also:

    • stripTrailing

      public RichText stripTrailing()
      Remove trailing whitespace, as defined by Unicode, removed.
      Returns:
      copy of this instance with trailing whitespace (according to Unicode) removed
      See Also:

    • split

      public RichText[] split(String regex)
      Splits this RichText into an array of RichText objects based on the provided regular expression.
      Parameters:
      regex - the regular expression to use as a delimiter for splitting this RichText
      Returns:
      an array of RichText objects computed by splitting this RichText around matches of the given regular expression
      See Also:

    • split

      public RichText[] split(Pattern pattern)
      Splits the current RichText into an array of RichText instances based on the provided pattern.
      Parameters:
      pattern - the regular expression pattern used to split the RichText. It determines the boundaries for splitting.
      Returns:
      an array of RichText objects resulting from splitting the current RichText based on the given pattern.
      See Also:

    • split

      public RichText[] split(String regex, int limit)
      Splits the current RichText object into an array of RichText objects based on the given regular expression and limit.

      The method splits the text into segments using the provided regular expression as the delimiter. The maximum number of resulting segments can be controlled by the limit parameter.

      Parameters:
      regex - the regular expression used to determine the boundaries for splitting
      limit - the maximum number of segments to include in the result; if the limit is zero or negative, the method will include all segments, including trailing empty strings if any
      Returns:
      an array of RichText objects resulting from the split operation
      See Also:

    • split

      public RichText[] split(Pattern pattern, int limit)
      Splits the current text into an array of RichText objects based on the given pattern and limit.
      Parameters:
      pattern - the regular expression pattern used to define delimiters for splitting the text
      limit - the maximum number of elements in the result array; if limit is less than or equal to zero, splits are unlimited; if limit is 0, trailing empty matches are removed from the result
      Returns:
      an array of RichText objects, split from the current text based on the specified pattern and limit
      See Also:

    • replace

      public RichText replace(int start, int end, RichText replacement)
      Replaces a text range with the supplied replacement.

      This method avoids rebuilding a monolithic backing string. Instead it splices run metadata and uses a segmented shared character sequence as backing storage.

      Parameters:
      start - start index (inclusive)
      end - end index (exclusive)
      replacement - replacement rich text
      Returns:
      updated rich text

    • commonPrefixLength

      public int commonPrefixLength(RichText other)
      Returns the number of leading characters that are equal in this text and other, including matching text attributes.
      Parameters:
      other - other text
      Returns:
      common prefix length

    • commonSuffixLength

      public int commonSuffixLength(RichText other)
      Returns the number of trailing characters that are equal in this text and other, including matching text attributes.
      Parameters:
      other - other text
      Returns:
      common suffix length

    • replaceFirst

      public RichText replaceFirst(String regex, RichText replacement)
      Replaces the first substring of this RichText that matches the given regular expression with the specified replacement RichText.
      Parameters:
      regex - the regular expression to which this RichText is to be matched
      replacement - the RichText to be used as a replacement for the first match
      Returns:
      a new RichText with the first matching substring replaced by the replacement RichText
      See Also:

    • replaceFirst

      public RichText replaceFirst(String regex, String replacement)
      Replaces the first substring of this RichText object that matches the given regular expression with the specified replacement string.
      Parameters:
      regex - the regular expression to which the substring should match
      replacement - the string to replace the first matching substring
      Returns:
      a new RichText object with the first matching substring replaced
      See Also:

    • replaceAll

      public RichText replaceAll(String regex, RichText replacement)
      Replaces each substring of this RichText that matches the given regular expression with the specified RichText replacement.
      Parameters:
      regex - the regular expression to which this RichText is matched
      replacement - the RichText to be substituted for each match
      Returns:
      a new RichText resulting from replacing all occurrences of the pattern with the specified replacement
      See Also:

    • replaceAll

      public RichText replaceAll(String regex, String replacement)
      Replaces every occurrence of the specified regular expression in the text with the given replacement string.
      Parameters:
      regex - the regular expression to be matched
      replacement - the string to replace each match
      Returns:
      a new RichText object with the replacements made
      See Also:

    • indexOf

      public int indexOf(int ch)
      Find character.
      Parameters:
      ch - the character
      Returns:
      the index of the first occurrence of ch, or -1 if not found
      See Also:

    • indexOf

      public int indexOf(char ch, int off)
      Find character.
      Parameters:
      ch - the character
      off - the starting position
      Returns:
      the position where the char was found or -1 if not found
      See Also:

    • indexOf

      public int indexOf(CharSequence s)
      Return the index of the needle in this RichText instance.
      Parameters:
      s - the text to find
      Returns:
      the first index, where s is found within this instance
      See Also:

    • indexOf

      public int indexOf(CharSequence s, int fromIndex)
      Return the index of the needle in this RichText instance.
      Parameters:
      s - the text to find
      fromIndex - the starting position
      Returns:
      the first index, where s is found within this instance
      See Also:

    • startsWith

      public boolean startsWith(CharSequence s)
      Test whether this instance starts with the given CharSequence.
      Parameters:
      s - the sequence to test
      Returns:
      true, if this instance starts with s
      See Also:

    • contains

      public boolean contains(CharSequence s)
      Test if CharSequence is contained.
      Parameters:
      s - the sequence to search for
      Returns:
      true, if s is contained
      See Also:

    • apply

      public RichText apply(Map<String,@Nullable Object> attributes)
      Returns a copy of this text with the supplied attributes applied to all characters. Existing attributes are preserved unless overwritten by an entry in attributes.
      Parameters:
      attributes - attributes to apply
      Returns:
      copy with the attributes applied

    • apply

      public RichText apply(Map<String,@Nullable Object> attributes, int from, int to)
      Returns a copy of this text with the supplied attributes applied to a subrange. Existing attributes are preserved unless overwritten by an entry in attributes.
      Parameters:
      attributes - attributes to apply
      from - start index (inclusive)
      to - end index (exclusive)
      Returns:
      copy with the attributes applied to the selected range

    • removeStyle

      public RichText removeStyle(Style style, int start, int end)
      Returns a copy of this text with the specified style removed from a subrange. Other attributes are preserved.
      Parameters:
      style - the style to remove
      start - start index (inclusive)
      end - end index (exclusive)
      Returns:
      copy with the style removed from the selected range

    • stylesAt

      public List<Style> stylesAt(int pos)
      Get active styles at position.
      Parameters:
      pos - the position (character index)
      Returns:
      (unmodifiable) list of styles

    • runAt

      public Run runAt(int pos)
      Get run at position.
      Parameters:
      pos - the position (character index)
      Returns:
      the Run the character at the given position belongs to

    • runs

      public List<Run> runs()
      Get the runs of this instance.
      Specified by:
      runs in interface RichTextRuns
      Returns:
      unmodifiable list of runs

    • isEmpty

      public boolean isEmpty()
      Description copied from interface: RichTextRuns
      Checks if the collection of rich text runs is empty.
      Specified by:
      isEmpty in interface CharSequence
      Specified by:
      isEmpty in interface RichTextRuns
      Returns:
      true if there are no rich text runs in the collection; false otherwise

    • runStream

      public Stream<Run> runStream()
      Get a stream containing the runs of this instance.
      Specified by:
      runStream in interface RichTextRuns
      Returns:
      stream of runs

    • equalizer

      public static BiPredicate<@Nullable RichText,@Nullable RichText> equalizer(ComparisonSettings s)
      Returns a BiPredicate that checks whether two RichText objects are equal based on the provided ComparisonSettings.
      Parameters:
      s - the ComparisonSettings to be used for the equality check
      Returns:
      the BiPredicate that checks for equality based on the ComparisonSettings

    • getBaseline

      public double getBaseline(Font defaultFont)
      Calculates the baseline value based on the maximum descent of fonts within the runs of text.
      Parameters:
      defaultFont - the default font used as a fallback when deriving fonts from font definitions
      Returns:
      the maximum descent value among all derived fonts; returns 0.0 if no runs are present