Skip to content

Most visited

Recently visited

navigation

TextUtils

public class TextUtils
extends Object

java.lang.Object
   ↳ android.text.TextUtils


Summary

Nested classes

interface TextUtils.EllipsizeCallback

 

class TextUtils.SimpleStringSplitter

A simple string splitter. 

interface TextUtils.StringSplitter

An interface for splitting strings according to rules that are opaque to the user of this interface. 

enum TextUtils.TruncateAt

 

Constants

int CAP_MODE_CHARACTERS

Capitalization mode for getCapsMode(CharSequence, int, int): capitalize all characters.

int CAP_MODE_SENTENCES

Capitalization mode for getCapsMode(CharSequence, int, int): capitalize the first character of each sentence.

int CAP_MODE_WORDS

Capitalization mode for getCapsMode(CharSequence, int, int): capitalize the first character of all words.

Fields

public static final Creator<CharSequence> CHAR_SEQUENCE_CREATOR

Public methods

static CharSequence commaEllipsize(CharSequence text, TextPaint p, float avail, String oneMore, String more)

This method was deprecated in API level 26. Do not use. This is not internationalized, and has known issues with right-to-left text, languages that have more than one plural form, languages that use a different character as a comma-like separator, etc. Use listEllipsize(Context, List, String, TextPaint, float, int) instead.

static CharSequence concat(CharSequence... text)

Returns a CharSequence concatenating the specified CharSequences, retaining their spans if any.

static void copySpansFrom(Spanned source, int start, int end, Class kind, Spannable dest, int destoff)

Copies the spans from the region start...end in source to the region destoff...destoff+end-start in dest.

static void dumpSpans(CharSequence cs, Printer printer, String prefix)

Debugging tool to print the spans in a CharSequence.

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 boolean equals(CharSequence a, CharSequence b)

Returns true if a and b are equal, including if they are both null.

static CharSequence expandTemplate(CharSequence template, CharSequence... values)

Replace instances of "^1", "^2", etc.

static int getCapsMode(CharSequence cs, int off, int reqModes)

Determine what caps mode should be in effect at the current offset in the text.

static void getChars(CharSequence s, int start, int end, char[] dest, int destoff)
static int getLayoutDirectionFromLocale(Locale locale)

Return the layout direction for a given Locale

static int getOffsetAfter(CharSequence text, int offset)
static int getOffsetBefore(CharSequence text, int offset)
static CharSequence getReverse(CharSequence source, int start, int end)

This method was deprecated in API level 24. Do not use.

static int getTrimmedLength(CharSequence s)

Returns the length that the specified CharSequence would have if spaces and ASCII control characters were trimmed from the start and end, as by trim().

static String htmlEncode(String s)

Html-encode the string.

static int indexOf(CharSequence s, char ch, int start, int end)
static int indexOf(CharSequence s, CharSequence needle, int start, int end)
static int indexOf(CharSequence s, CharSequence needle, int start)
static int indexOf(CharSequence s, CharSequence needle)
static int indexOf(CharSequence s, char ch, int start)
static int indexOf(CharSequence s, char ch)
static boolean isDigitsOnly(CharSequence str)

Returns whether the given CharSequence contains only digits.

static boolean isEmpty(CharSequence str)

Returns true if the string is null or 0-length.

static boolean isGraphic(CharSequence str)

Returns whether the given CharSequence contains any printable characters.

static boolean isGraphic(char c)

This method was deprecated in API level 24. Use isGraphic(CharSequence) instead.

static String join(CharSequence delimiter, Iterable tokens)

Returns a string containing the tokens joined by delimiters.

static String join(CharSequence delimiter, Object[] tokens)

Returns a string containing the tokens joined by delimiters.

static int lastIndexOf(CharSequence s, char ch, int last)
static int lastIndexOf(CharSequence s, char ch)
static int lastIndexOf(CharSequence s, char ch, int start, int last)
static CharSequence listEllipsize(Context context, List<CharSequence> elements, String separator, TextPaint paint, float avail, int moreId)

Formats a list of CharSequences by repeatedly inserting the separator between them, but stopping when the resulting sequence is too wide for the specified width.

static boolean regionMatches(CharSequence one, int toffset, CharSequence two, int ooffset, int len)
static CharSequence replace(CharSequence template, String[] sources, CharSequence[] destinations)

Return a new CharSequence in which each of the source strings is replaced by the corresponding element of the destinations.

static String[] split(String text, Pattern pattern)

Splits a string on a pattern.

static String[] split(String text, String expression)

String.split() returns [''] when the string to be split is empty.

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 void writeToParcel(CharSequence cs, Parcel p, int parcelableFlags)

Flatten a CharSequence and whatever styles can be copied across processes into the parcel.

Inherited methods

From class java.lang.Object

Constants

CAP_MODE_CHARACTERS

added in API level 3
int CAP_MODE_CHARACTERS

Capitalization mode for getCapsMode(CharSequence, int, int): capitalize all characters. This value is explicitly defined to be the same as TYPE_TEXT_FLAG_CAP_CHARACTERS.

Constant Value: 4096 (0x00001000)

CAP_MODE_SENTENCES

added in API level 3
int CAP_MODE_SENTENCES

Capitalization mode for getCapsMode(CharSequence, int, int): capitalize the first character of each sentence. This value is explicitly defined to be the same as TYPE_TEXT_FLAG_CAP_SENTENCES.

Constant Value: 16384 (0x00004000)

CAP_MODE_WORDS

added in API level 3
int CAP_MODE_WORDS

Capitalization mode for getCapsMode(CharSequence, int, int): capitalize the first character of all words. This value is explicitly defined to be the same as TYPE_TEXT_FLAG_CAP_WORDS.

Constant Value: 8192 (0x00002000)

Fields

CHAR_SEQUENCE_CREATOR

added in API level 1
Creator<CharSequence> CHAR_SEQUENCE_CREATOR

Public methods

commaEllipsize

added in API level 1
CharSequence commaEllipsize (CharSequence text, 
                TextPaint p, 
                float avail, 
                String oneMore, 
                String more)

This method was deprecated in API level 26.
Do not use. This is not internationalized, and has known issues with right-to-left text, languages that have more than one plural form, languages that use a different character as a comma-like separator, etc. Use listEllipsize(Context, List, String, TextPaint, float, int) instead.

Converts a CharSequence of the comma-separated form "Andy, Bob, Charles, David" that is too wide to fit into the specified width into one like "Andy, Bob, 2 more".

Parameters
text CharSequence: the text to truncate

p TextPaint: the Paint with which to measure the text

avail float: the horizontal width available for the text (in pixels)

oneMore String: the string for "1 more" in the current locale

more String: the string for "%d more" in the current locale

Returns
CharSequence

concat

added in API level 1
CharSequence concat (CharSequence... text)

Returns a CharSequence concatenating the specified CharSequences, retaining their spans if any. If there are no parameters, an empty string will be returned. If the number of parameters is exactly one, that parameter is returned as output, even if it is null. If the number of parameters is at least two, any null CharSequence among the parameters is treated as if it was the string "null". 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
text CharSequence

Returns
CharSequence

copySpansFrom

added in API level 1
void copySpansFrom (Spanned source, 
                int start, 
                int end, 
                Class kind, 
                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.

Parameters
source Spanned

start int

end int

kind Class

dest Spannable

destoff int

Throws
IndexOutOfBoundsException if any of the copied spans are out of range in dest.

dumpSpans

added in API level 3
void dumpSpans (CharSequence cs, 
                Printer printer, 
                String prefix)

Debugging tool to print the spans in a CharSequence. The output will be printed one span per line. If the CharSequence is not a Spanned, then the entire string will be printed on a single line.

Parameters
cs CharSequence

printer Printer

prefix String

ellipsize

added in API level 1
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.

Parameters
text CharSequence

p TextPaint

avail float

where TextUtils.TruncateAt

Returns
CharSequence

ellipsize

added in API level 1
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. 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.

Parameters
text CharSequence

paint TextPaint

avail float

where TextUtils.TruncateAt

preserveLength boolean

callback TextUtils.EllipsizeCallback

Returns
CharSequence

equals

added in API level 1
boolean equals (CharSequence a, 
                CharSequence b)

Returns true if a and b are equal, including if they are both null.

Note: In platform versions 1.1 and earlier, this method only worked well if both the arguments were instances of String.

Parameters
a CharSequence: first CharSequence to check

b CharSequence: second CharSequence to check

Returns
boolean true if a and b are equal

expandTemplate

added in API level 1
CharSequence expandTemplate (CharSequence template, 
                CharSequence... values)

Replace instances of "^1", "^2", etc. in the template CharSequence with the corresponding values. "^^" is used to produce a single caret in the output. Only up to 9 replacement values are supported, "^10" will be produce the first replacement value followed by a '0'.

Parameters
template CharSequence: the input text containing "^1"-style placeholder values. This object is not modified; a copy is returned.

values CharSequence: CharSequences substituted into the template. The first is substituted for "^1", the second for "^2", and so on.

Returns
CharSequence the new CharSequence produced by doing the replacement

Throws
IllegalArgumentException if the template requests a value that was not provided, or if more than 9 values are provided.

getCapsMode

added in API level 3
int getCapsMode (CharSequence cs, 
                int off, 
                int reqModes)

Determine what caps mode should be in effect at the current offset in the text. Only the mode bits set in reqModes will be checked. Note that the caps mode flags here are explicitly defined to match those in InputType.

Parameters
cs CharSequence: The text that should be checked for caps modes.

off int: Location in the text at which to check.

reqModes int: The modes to be checked: may be any combination of CAP_MODE_CHARACTERS, CAP_MODE_WORDS, and CAP_MODE_SENTENCES.

Returns
int Returns the actual capitalization modes that can be in effect at the current position, which is any combination of CAP_MODE_CHARACTERS, CAP_MODE_WORDS, and CAP_MODE_SENTENCES.

getChars

added in API level 1
void getChars (CharSequence s, 
                int start, 
                int end, 
                char[] dest, 
                int destoff)

Parameters
s CharSequence

start int

end int

dest char

destoff int

getLayoutDirectionFromLocale

added in API level 17
int getLayoutDirectionFromLocale (Locale locale)

Return the layout direction for a given Locale

Parameters
locale Locale: the Locale for which we want the layout direction. Can be null.

Returns
int the layout direction. This may be one of: LAYOUT_DIRECTION_LTR or LAYOUT_DIRECTION_RTL. Be careful: this code will need to be updated when vertical scripts will be supported

getOffsetAfter

added in API level 1
int getOffsetAfter (CharSequence text, 
                int offset)

Parameters
text CharSequence

offset int

Returns
int

getOffsetBefore

added in API level 1
int getOffsetBefore (CharSequence text, 
                int offset)

Parameters
text CharSequence

offset int

Returns
int

getReverse

added in API level 1
CharSequence getReverse (CharSequence source, 
                int start, 
                int end)

This method was deprecated in API level 24.
Do not use.

This function only reverses individual chars and not their associated spans. It doesn't support surrogate pairs (that correspond to non-BMP code points), combining sequences or conjuncts either.

Parameters
source CharSequence

start int

end int

Returns
CharSequence

getTrimmedLength

added in API level 1
int getTrimmedLength (CharSequence s)

Returns the length that the specified CharSequence would have if spaces and ASCII control characters were trimmed from the start and end, as by trim().

Parameters
s CharSequence

Returns
int

htmlEncode

added in API level 1
String htmlEncode (String s)

Html-encode the string.

Parameters
s String: the string to be encoded

Returns
String the encoded string

indexOf

added in API level 1
int indexOf (CharSequence s, 
                char ch, 
                int start, 
                int end)

Parameters
s CharSequence

ch char

start int

end int

Returns
int

indexOf

added in API level 1
int indexOf (CharSequence s, 
                CharSequence needle, 
                int start, 
                int end)

Parameters
s CharSequence

needle CharSequence

start int

end int

Returns
int

indexOf

added in API level 1
int indexOf (CharSequence s, 
                CharSequence needle, 
                int start)

Parameters
s CharSequence

needle CharSequence

start int

Returns
int

indexOf

added in API level 1
int indexOf (CharSequence s, 
                CharSequence needle)

Parameters
s CharSequence

needle CharSequence

Returns
int

indexOf

added in API level 1
int indexOf (CharSequence s, 
                char ch, 
                int start)

Parameters
s CharSequence

ch char

start int

Returns
int

indexOf

added in API level 1
int indexOf (CharSequence s, 
                char ch)

Parameters
s CharSequence

ch char

Returns
int

isDigitsOnly

added in API level 1
boolean isDigitsOnly (CharSequence str)

Returns whether the given CharSequence contains only digits.

Parameters
str CharSequence

Returns
boolean

isEmpty

added in API level 1
boolean isEmpty (CharSequence str)

Returns true if the string is null or 0-length.

Parameters
str CharSequence: the string to be examined

This value may be null.

Returns
boolean true if str is null or zero length

isGraphic

added in API level 1
boolean isGraphic (CharSequence str)

Returns whether the given CharSequence contains any printable characters.

Parameters
str CharSequence

Returns
boolean

isGraphic

added in API level 1
boolean isGraphic (char c)

This method was deprecated in API level 24.
Use isGraphic(CharSequence) instead.

Returns whether this character is a printable character. This does not support non-BMP characters and should not be used.

Parameters
c char

Returns
boolean

join

added in API level 1
String join (CharSequence delimiter, 
                Iterable tokens)

Returns a string containing the tokens joined by delimiters.

Parameters
delimiter CharSequence

tokens Iterable: an array objects to be joined. Strings will be formed from the objects by calling object.toString().

Returns
String

join

added in API level 1
String join (CharSequence delimiter, 
                Object[] tokens)

Returns a string containing the tokens joined by delimiters.

Parameters
delimiter CharSequence

tokens Object: an array objects to be joined. Strings will be formed from the objects by calling object.toString().

Returns
String

lastIndexOf

added in API level 1
int lastIndexOf (CharSequence s, 
                char ch, 
                int last)

Parameters
s CharSequence

ch char

last int

Returns
int

lastIndexOf

added in API level 1
int lastIndexOf (CharSequence s, 
                char ch)

Parameters
s CharSequence

ch char

Returns
int

lastIndexOf

added in API level 1
int lastIndexOf (CharSequence s, 
                char ch, 
                int start, 
                int last)

Parameters
s CharSequence

ch char

start int

last int

Returns
int

listEllipsize

added in API level 26
CharSequence listEllipsize (Context context, 
                List<CharSequence> elements, 
                String separator, 
                TextPaint paint, 
                float avail, 
                int moreId)

Formats a list of CharSequences by repeatedly inserting the separator between them, but stopping when the resulting sequence is too wide for the specified width. This method actually tries to fit the maximum number of elements. So if "A, 11 more" fits, "A, B, 10 more" doesn't fit, but "A, B, C, 9 more" fits again (due to the glyphs for the digits being very wide, for example), it returns "A, B, C, 9 more". Because of this, this method may be inefficient for very long lists. Note that the elements of the returned value, as well as the string for moreId, will be bidi-wrapped using unicodeWrap(CharSequence) based on the locale of the input Context. If the input Context is null, the default BidiFormatter from getInstance() will be used.

Parameters
context Context: the Context to get the moreId resource from. If null, an ellipsis (U+2026) would be used for moreId.

elements List: the list to format

This value may be null.

separator String: a separator, such as ", "

This value must never be null.

paint TextPaint: the Paint with which to measure the text

This value must never be null.

avail float: the horizontal width available for the text (in pixels)

Value is 0.0 or greater.

moreId int: the resource ID for the pluralized string to insert at the end of sequence when some of the elements don't fit.

Returns
CharSequence the formatted CharSequence. If even the shortest sequence (e.g. "A, 11 more") doesn't fit, it will return an empty string.

regionMatches

added in API level 1
boolean regionMatches (CharSequence one, 
                int toffset, 
                CharSequence two, 
                int ooffset, 
                int len)

Parameters
one CharSequence

toffset int

two CharSequence

ooffset int

len int

Returns
boolean

replace

added in API level 1
CharSequence replace (CharSequence template, 
                String[] sources, 
                CharSequence[] destinations)

Return a new CharSequence in which each of the source strings is replaced by the corresponding element of the destinations.

Parameters
template CharSequence

sources String

destinations CharSequence

Returns
CharSequence

split

added in API level 1
String[] split (String text, 
                Pattern pattern)

Splits a string on a pattern. String.split() returns [''] when the string to be split is empty. This returns []. This does not remove any empty strings from the result.

Parameters
text String: the string to split

pattern Pattern: the regular expression to match

Returns
String[] an array of strings. The array will be empty if text is empty

Throws
NullPointerException if expression or text is null

split

added in API level 1
String[] split (String text, 
                String expression)

String.split() returns [''] when the string to be split is empty. This returns []. This does not remove any empty strings from the result. For example split("a,", "," ) returns {"a", ""}.

Parameters
text String: the string to split

expression String: the regular expression to match

Returns
String[] an array of strings. The array will be empty if text is empty

Throws
NullPointerException if expression or text is null

stringOrSpannedString

added in API level 1
CharSequence stringOrSpannedString (CharSequence source)

Parameters
source CharSequence

Returns
CharSequence

substring

added in API level 1
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.

Parameters
source CharSequence

start int

end int

Returns
String

writeToParcel

added in API level 1
void writeToParcel (CharSequence cs, 
                Parcel p, 
                int parcelableFlags)

Flatten a CharSequence and whatever styles can be copied across processes into the parcel.

Parameters
cs CharSequence

p Parcel

parcelableFlags int

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Follow Google Developers on WeChat

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience.
(Sep 2017 survey)