Package icyllis.modernui.text

# Class TextUtils

java.lang.Object
icyllis.modernui.text.TextUtils

public final class TextUtils extends Object

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static interface`
  `TextUtils.EllipsizeCallback`
  `static enum`
  `TextUtils.TruncateAt`
  Where to truncate.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `ABSOLUTE_SIZE_SPAN`
  `static final int`
  `ACCESSIBILITY_CLICKABLE_SPAN`
  `static final int`
  `ACCESSIBILITY_REPLACEMENT_SPAN`
  `static final int`
  `ACCESSIBILITY_URL_SPAN`
  `static final int`
  `ALIGNMENT_SPAN`
  `static final int`
  `ANNOTATION`
  `static final int`
  `BACKGROUND_COLOR_SPAN`
  `static final int`
  `BULLET_SPAN`
  `static final int`
  `EASY_EDIT_SPAN`
  `static final int`
  `FIRST_SPAN`
  `static final int`
  `FOREGROUND_COLOR_SPAN`
  `static final int`
  `LAST_SPAN`
  `static final int`
  `LEADING_MARGIN_SPAN`
  `static final int`
  `LINE_BACKGROUND_SPAN`
  `static final int`
  `LINE_HEIGHT_SPAN`
  `static final int`
  `LOCALE_SPAN`
  `static final int`
  `QUOTE_SPAN`
  `static final int`
  `RELATIVE_SIZE_SPAN`
  `static final int`
  `SCALE_X_SPAN`
  `static final int`
  `SPELL_CHECK_SPAN`
  `static final int`
  `STRIKETHROUGH_SPAN`
  `static final int`
  `STYLE_SPAN`
  `static final int`
  `SUBSCRIPT_SPAN`
  `static final int`
  `SUGGESTION_RANGE_SPAN`
  `static final int`
  `SUGGESTION_SPAN`
  `static final int`
  `SUPERSCRIPT_SPAN`
  `static final int`
  `TEXT_APPEARANCE_SPAN`
  `static final int`
  `TRAILING_MARGIN_SPAN`
  `static final int`
  `TTS_SPAN`
  `static final int`
  `TYPEFACE_SPAN`
  `static final int`
  `UNDERLINE_SPAN`
  `static final int`
  `URL_SPAN`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static String`
  `binaryCompact(long num)`
  `static void`
  `binaryCompact(Appendable a, long num)`
  `static CharSequence`
  `concat(CharSequence... elements)`
  Returns a CharSequence concatenating the specified CharSequences, retaining their spans if any.
  `static CharSequence`
  `concat(Iterable<? extends CharSequence> elements)`
  Returns a CharSequence concatenating the specified CharSequences, retaining their spans if any.
  `static boolean`
  `contentEquals(CharSequence a, CharSequence b)`
  `static void`
  `copySpansFrom(Spanned source, int start, int end, Class<?> type, Spannable dest, int destoff)`
  Copies the spans from the region `start...end` in `source` to the region `destoff...destoff+end-start` in `dest`.
  `static CharSequence`
  `createFromParcel(Parcel p)`
  `static int`
  `distance(CharSequence a, CharSequence b)`
  Find the Levenshtein distance between a and b.
  `static void`
  `drawTextRun(Canvas canvas, char[] text, int start, int end, int contextStart, int contextEnd, float x, float y, boolean isRtl, TextPaint paint)`
  Draw a run of text, all in a single direction, with optional context for complex text shaping.
  `static void`
  `drawTextRun(Canvas canvas, CharSequence text, int start, int end, int contextStart, int contextEnd, float x, float y, boolean isRtl, TextPaint paint)`
  Draw a run of text, all in a single direction, with optional context for complex text shaping.
  `static CharSequence`
  `ellipsize(CharSequence text, TextPaint p, float avail, TextUtils.TruncateAt where)`
  Returns the original text if it fits in the specified width given the properties of the specified Paint, or, if it does not fit, a truncated copy with ellipsis character added at the specified edge or center.
  `static CharSequence`
  `ellipsize(CharSequence text, TextPaint paint, float avail, TextUtils.TruncateAt where, boolean preserveLength, TextUtils.EllipsizeCallback callback)`
  Returns the original text if it fits in the specified width given the properties of the specified Paint, or, if it does not fit, a copy with ellipsis character added at the specified edge or center.
  `static void`
  `getChars(CharSequence s, int srcBegin, int srcEnd, char[] dst, int dstBegin)`
  Copies a block of characters efficiently.
  `static char[]`
  `getEllipsisChars(TextUtils.TruncateAt method)`
  `static String`
  `getEllipsisString(TextUtils.TruncateAt method)`
  `static int`
  `getLayoutDirectionFromLocale(Locale locale)`
  Return the layout direction for a given Locale
  `static int`
  `indexOf(CharSequence s, char ch)`
  `static int`
  `indexOf(CharSequence s, char ch, int start)`
  `static int`
  `indexOf(CharSequence s, char ch, int start, int end)`
  `static boolean`
  `isEmpty(CharSequence csq)`
  Returns true if the char sequence is null or 0-length.
  `static CharSequence`
  `join(CharSequence delimiter, CharSequence... elements)`
  Returns a CharSequence composed of copies of the elements joined together with the specified delimiter.
  `static CharSequence`
  `join(CharSequence delimiter, Iterable<? extends CharSequence> elements)`
  Returns a CharSequence composed of copies of the elements joined together with the specified delimiter.
  `static int`
  `lastIndexOf(CharSequence s, char ch)`
  `static int`
  `lastIndexOf(CharSequence s, char ch, int last)`
  `static int`
  `lastIndexOf(CharSequence s, char ch, int start, int last)`
  `static <T> List<T>`
  `removeEmptySpans(List<T> spans, Spanned spanned)`
  Removes empty spans from the `spans` list.
  `static CharSequence`
  `stringOrSpannedString(CharSequence source)`
  `static String`
  `substring(CharSequence source, int start, int end)`
  Create a new String object containing the given range of characters from the source string.
  `static String`
  `validateSurrogatePairs(String text)`
  Replace all invalid surrogate pairs with 'U+FFFD' for the given UTF-16 string.
  `static void`
  `writeToParcel(CharSequence cs, Parcel dest, int flags)`
  Flatten a `CharSequence` and whatever styles can be copied across processes into the output.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### FIRST_SPAN

    @Internal public static final int FIRST_SPAN
    See Also:
      - Constant Field Values

  - ### ALIGNMENT_SPAN

    @Internal public static final int ALIGNMENT_SPAN
    See Also:
      - Constant Field Values

  - ### FOREGROUND_COLOR_SPAN

    @Internal public static final int FOREGROUND_COLOR_SPAN
    See Also:
      - Constant Field Values

  - ### RELATIVE_SIZE_SPAN

    @Internal public static final int RELATIVE_SIZE_SPAN
    See Also:
      - Constant Field Values

  - ### SCALE_X_SPAN

    @Internal public static final int SCALE_X_SPAN
    See Also:
      - Constant Field Values

  - ### STRIKETHROUGH_SPAN

    @Internal public static final int STRIKETHROUGH_SPAN
    See Also:
      - Constant Field Values

  - ### UNDERLINE_SPAN

    @Internal public static final int UNDERLINE_SPAN
    See Also:
      - Constant Field Values

  - ### STYLE_SPAN

    @Internal public static final int STYLE_SPAN
    See Also:
      - Constant Field Values

  - ### BULLET_SPAN

    @Internal public static final int BULLET_SPAN
    See Also:
      - Constant Field Values

  - ### QUOTE_SPAN

    @Internal public static final int QUOTE_SPAN
    See Also:
      - Constant Field Values

  - ### LEADING_MARGIN_SPAN

    @Internal public static final int LEADING_MARGIN_SPAN
    See Also:
      - Constant Field Values

  - ### URL_SPAN

    @Internal public static final int URL_SPAN
    See Also:
      - Constant Field Values

  - ### BACKGROUND_COLOR_SPAN

    @Internal public static final int BACKGROUND_COLOR_SPAN
    See Also:
      - Constant Field Values

  - ### TYPEFACE_SPAN

    @Internal public static final int TYPEFACE_SPAN
    See Also:
      - Constant Field Values

  - ### SUPERSCRIPT_SPAN

    @Internal public static final int SUPERSCRIPT_SPAN
    See Also:
      - Constant Field Values

  - ### SUBSCRIPT_SPAN

    @Internal public static final int SUBSCRIPT_SPAN
    See Also:
      - Constant Field Values

  - ### ABSOLUTE_SIZE_SPAN

    @Internal public static final int ABSOLUTE_SIZE_SPAN
    See Also:
      - Constant Field Values

  - ### TEXT_APPEARANCE_SPAN

    @Internal public static final int TEXT_APPEARANCE_SPAN
    See Also:
      - Constant Field Values

  - ### ANNOTATION

    @Internal public static final int ANNOTATION
    See Also:
      - Constant Field Values

  - ### SUGGESTION_SPAN

    @Internal public static final int SUGGESTION_SPAN
    See Also:
      - Constant Field Values

  - ### SPELL_CHECK_SPAN

    @Internal public static final int SPELL_CHECK_SPAN
    See Also:
      - Constant Field Values

  - ### SUGGESTION_RANGE_SPAN

    @Internal public static final int SUGGESTION_RANGE_SPAN
    See Also:
      - Constant Field Values

  - ### EASY_EDIT_SPAN

    @Internal public static final int EASY_EDIT_SPAN
    See Also:
      - Constant Field Values

  - ### LOCALE_SPAN

    @Internal public static final int LOCALE_SPAN
    See Also:
      - Constant Field Values

  - ### TTS_SPAN

    @Internal public static final int TTS_SPAN
    See Also:
      - Constant Field Values

  - ### ACCESSIBILITY_CLICKABLE_SPAN

    @Internal public static final int ACCESSIBILITY_CLICKABLE_SPAN
    See Also:
      - Constant Field Values

  - ### ACCESSIBILITY_URL_SPAN

    @Internal public static final int ACCESSIBILITY_URL_SPAN
    See Also:
      - Constant Field Values

  - ### LINE_BACKGROUND_SPAN

    @Internal public static final int LINE_BACKGROUND_SPAN
    See Also:
      - Constant Field Values

  - ### LINE_HEIGHT_SPAN

    @Internal public static final int LINE_HEIGHT_SPAN
    See Also:
      - Constant Field Values

  - ### ACCESSIBILITY_REPLACEMENT_SPAN

    @Internal public static final int ACCESSIBILITY_REPLACEMENT_SPAN
    See Also:
      - Constant Field Values

  - ### TRAILING_MARGIN_SPAN

    @Internal public static final int TRAILING_MARGIN_SPAN
    See Also:
      - Constant Field Values

  - ### LAST_SPAN

    @Internal public static final int LAST_SPAN
    See Also:
      - Constant Field Values

- ## Method Details

  - ### getEllipsisString

    @NonNull public static String getEllipsisString(@NonNull TextUtils.TruncateAt method)

  - ### getEllipsisChars

    @Internal @NonNull public static char[] getEllipsisChars(@NonNull TextUtils.TruncateAt method)

  - ### stringOrSpannedString

    public static CharSequence stringOrSpannedString(CharSequence source)

  - ### isEmpty

    public static boolean isEmpty(@Nullable CharSequence csq)
    Returns true if the char sequence is null or 0-length.
    Parameters:
      `csq` - the char sequence to be examined
    Returns:
      true if csq is null or zero length

  - ### contentEquals

    public static boolean contentEquals(@Nullable CharSequence a, @Nullable CharSequence b)

  - ### getChars

    public static void getChars(@NonNull CharSequence s, int srcBegin, int srcEnd, @NonNull char[] dst, int dstBegin)
    Copies a block of characters efficiently.

  - ### removeEmptySpans

    @NonNull public static <T> List<T> removeEmptySpans(@NonNull List<T> spans, @NonNull Spanned spanned)
    Removes empty spans from the `spans` list.

    When parsing a Spanned using `Spanned.nextSpanTransition(int, int, Class)`, empty spans will (correctly) create span transitions, and calling getSpans on a slice of text bounded by one of these transitions will (correctly) include the empty overlapping span.

    However, these empty spans should not be taken into account when laying-out or rendering the string and this method provides a way to filter getSpans' results accordingly.

    Parameters:
      `spans` - A list of spans retrieved using `Spanned.getSpans(int, int, Class)` from the `spanned`
      `spanned` - The Spanned from which spans were extracted
    Returns:
      A subset of spans where empty spans (`Spanned.getSpanStart(Object)` == `Spanned.getSpanEnd(Object)` have been removed. The initial order is preserved

  - ### substring

    public static String substring(CharSequence source, int start, int end)
    Create a new String object containing the given range of characters from the source string. This is different than simply calling `CharSequence.subSequence` in that it does not preserve any style runs in the source sequence, allowing a more efficient implementation.

  - ### indexOf

    public static int indexOf(CharSequence s, char ch)

  - ### indexOf

    public static int indexOf(CharSequence s, char ch, int start)

  - ### indexOf

    public static int indexOf(@NonNull CharSequence s, char ch, int start, int end)

  - ### lastIndexOf

    public static int lastIndexOf(CharSequence s, char ch)

  - ### lastIndexOf

    public static int lastIndexOf(CharSequence s, char ch, int last)

  - ### lastIndexOf

    public static int lastIndexOf(CharSequence s, char ch, int start, int last)

  - ### writeToParcel

    public static void writeToParcel(@Nullable CharSequence cs, @NonNull Parcel dest, int flags)
    Flatten a `CharSequence` and whatever styles can be copied across processes into the output.

  - ### createFromParcel

    @Nullable public static CharSequence createFromParcel(@NonNull Parcel p)

  - ### drawTextRun

    public static void drawTextRun(@NonNull Canvas canvas, @NonNull char[] text, int start, int end, int contextStart, int contextEnd, float x, float y, boolean isRtl, @NonNull TextPaint paint)
    Draw a run of text, all in a single direction, with optional context for complex text shaping.

    See `drawTextRun(Canvas, CharSequence, int, int, int, int, float, float, boolean, TextPaint)` for more details. This method uses a character array rather than CharSequence to represent the string.

    Parameters:
      `canvas` - the canvas
      `text` - the text to render
      `start` - the start of the text to render. Data before this position can be used for shaping context.
      `end` - the end of the text to render. Data at or after this position can be used for shaping context.
      `contextStart` - the index of the start of the shaping context
      `contextEnd` - the index of the end of the shaping context
      `x` - the x position at which to draw the text
      `y` - the y position at which to draw the text
      `isRtl` - whether the run is in RTL direction
      `paint` - the paint

  - ### drawTextRun

    public static void drawTextRun(@NonNull Canvas canvas, @NonNull CharSequence text, int start, int end, int contextStart, int contextEnd, float x, float y, boolean isRtl, @NonNull TextPaint paint)
    Draw a run of text, all in a single direction, with optional context for complex text shaping.

    The run of text includes the characters from `start` to `end` in the text. In addition, the range `contextStart` to `contextEnd` is used as context for the purpose of complex text shaping, such as Arabic text potentially shaped differently based on the text next to it.

    All text outside the range `contextStart..contextEnd` is ignored. The text between `start` and `end` will be laid out and drawn. The context range is useful for contextual shaping, e.g. Kerning, Arabic contextual form.

    The direction of the run is explicitly specified by `isRtl`. Thus, this method is suitable only for runs of a single direction. Alignment of the text is as determined by the Paint's TextAlign value. Further, `0 <= contextStart <= start <= end <= contextEnd <= text.length` must hold on entry.

    Parameters:
      `canvas` - the canvas
      `text` - the text to render
      `start` - the start of the text to render. Data before this position can be used for shaping context.
      `end` - the end of the text to render. Data at or after this position can be used for shaping context.
      `contextStart` - the index of the start of the shaping context
      `contextEnd` - the index of the end of the shaping context
      `x` - the x position at which to draw the text
      `y` - the y position at which to draw the text
      `isRtl` - whether the run is in RTL direction
      `paint` - the paint
    See Also:
      - `drawTextRun(Canvas, char[], int, int, int, int, float, float, boolean, TextPaint)`

  - ### ellipsize

    @NonNull public static CharSequence ellipsize(@NonNull CharSequence text, @NonNull TextPaint p, float avail, @NonNull TextUtils.TruncateAt where)
    Returns the original text if it fits in the specified width given the properties of the specified Paint, or, if it does not fit, a truncated copy with ellipsis character added at the specified edge or center.

  - ### ellipsize

    @NonNull public static CharSequence ellipsize(@NonNull CharSequence text, @NonNull TextPaint paint, float avail, @NonNull TextUtils.TruncateAt where, boolean preserveLength, @Nullable TextUtils.EllipsizeCallback callback)
    Returns the original text if it fits in the specified width given the properties of the specified Paint, or, if it does not fit, a copy with ellipsis character added at the specified edge or center. If `preserveLength` is specified, the returned copy will be padded with zero-width spaces to preserve the original length and offsets instead of truncating. If `callback` is non-null, it will be called to report the start and end of the ellipsized range. TextDirection is determined by the first strong directional character.

  - ### concat

    public static CharSequence concat(@NonNull CharSequence... elements)
    Returns a CharSequence concatenating the specified CharSequences, retaining their spans if any.

    If there are no elements, an empty string will be returned.

    If the number of elements is exactly one, that element is returned, even if it is null or mutable.

    If the number of elements is at least two, any null CharSequence among the elements is treated as if it was the string `"null"`, and a new String or SpannedString is returned.

    If there are paragraph spans in the source CharSequences that satisfy paragraph boundary requirements in the sources but would no longer satisfy them in the concatenated CharSequence, they may get extended in the resulting CharSequence or not retained.

    Since:
      3.10.1

  - ### concat

    public static CharSequence concat(@NonNull Iterable<? extends CharSequence> elements)
    Returns a CharSequence concatenating the specified CharSequences, retaining their spans if any.

    If there are no elements, an empty string will be returned.

    If the number of elements is exactly one, that element is returned, even if it is null or mutable.

    If the number of elements is at least two, any null CharSequence among the elements is treated as if it was the string `"null"`, and a new String or SpannedString is returned.

    If there are paragraph spans in the source CharSequences that satisfy paragraph boundary requirements in the sources but would no longer satisfy them in the concatenated CharSequence, they may get extended in the resulting CharSequence or not retained.

    Since:
      3.10.1

  - ### join

    @NonNull public static CharSequence join(@NonNull CharSequence delimiter, @NonNull CharSequence... elements)
    Returns a CharSequence composed of copies of the elements joined together with the specified delimiter.

    If there are no elements, an empty string will be returned. Otherwise, returns a new CharSequence. Any null value will be replaced with the string `"null"`.

    Unlike Android, this method retains their spans if any. If you want to ignore all the spans, use `String.join(CharSequence, CharSequence...)` instead.

    If there are paragraph spans in the source CharSequences that satisfy paragraph boundary requirements in the sources but would no longer satisfy them in the concatenated CharSequence, they may get extended in the resulting CharSequence or not retained.

    Parameters:
      `delimiter` - the delimiter that separates each element, may be `Spanned`
      `elements` - an array of char sequences to join together, may be `Spanned`
    Returns:
      a String or SpannedString
    Since:
      3.10.1

  - ### join

    @NonNull public static CharSequence join(@NonNull CharSequence delimiter, @NonNull Iterable<? extends CharSequence> elements)
    Returns a CharSequence composed of copies of the elements joined together with the specified delimiter.

    If there are no elements, an empty string will be returned. Otherwise, returns a new CharSequence. Any null value will be replaced with the string `"null"`.

    Unlike Android, this method retains their spans if any. If you want to ignore all the spans, use `String.join(CharSequence, Iterable)` instead.

    If there are paragraph spans in the source CharSequences that satisfy paragraph boundary requirements in the sources but would no longer satisfy them in the concatenated CharSequence, they may get extended in the resulting CharSequence or not retained.

    Parameters:
      `delimiter` - the delimiter that separates each element, may be `Spanned`
      `elements` - an iterable of char sequences to join together, may be `Spanned`
    Returns:
      a String or SpannedString
    Since:
      3.10.1

  - ### binaryCompact

    @NonNull public static String binaryCompact(long num)

  - ### binaryCompact

    public static void binaryCompact(@NonNull Appendable a, long num)

  - ### copySpansFrom

    public static void copySpansFrom(@NonNull Spanned source, int start, int end, @Nullable Class<?> type, @NonNull Spannable dest, int destoff)
    Copies the spans from the region `start...end` in `source` to the region `destoff...destoff+end-start` in `dest`. Spans in `source` that begin before `start` or end after `end` but overlap this range are trimmed as if they began at `start` or ended at `end`.
    Throws:
      `IndexOutOfBoundsException` - if any of the copied spans are out of range in `dest`.

  - ### getLayoutDirectionFromLocale

    public static int getLayoutDirectionFromLocale(@Nullable Locale locale)
    Return the layout direction for a given Locale
    Parameters:
      `locale` - the Locale for which we want the layout direction. Can be null.
    Returns:
      the layout direction. This may be one of: `View.LAYOUT_DIRECTION_LTR` or `View.LAYOUT_DIRECTION_RTL`.

      Be careful: this code will need to be updated when vertical scripts will be supported

  - ### validateSurrogatePairs

    @NonNull public static String validateSurrogatePairs(@NonNull String text)
    Replace all invalid surrogate pairs with 'U+FFFD' for the given UTF-16 string. Return the given string as-is if it was validated, or a new string.

  - ### distance

    public static int distance(@NonNull CharSequence a, @NonNull CharSequence b)
    Find the Levenshtein distance between a and b. This algorithm has a time complexity of O(m*n) and a space complexity of O(n), where m is the length of a and n is the length of b.

    This method only works for Unicode BMP characters without taking into account grapheme clusters.

    Returns:
      the Levenshtein distance in chars (u16)
    Since:
      3.7