Android APIs
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)
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".
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)
static int getTrimmedLength(CharSequence s)
Returns the length that the specified CharSequence would have if spaces and 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)
static int indexOf(CharSequence s, CharSequence needle)
static int indexOf(CharSequence s, CharSequence needle, int start)
static int indexOf(CharSequence s, char ch, int start, int end)
static int indexOf(CharSequence s, char ch, int start)
static int indexOf(CharSequence s, CharSequence needle, int start, int end)
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)
Returns whether this character is a printable character.
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 start, int last)
static int lastIndexOf(CharSequence s, char ch)
static int lastIndexOf(CharSequence s, char ch, int last)
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.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int CAP_MODE_CHARACTERS

Added in API level 3

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)

public static final int CAP_MODE_SENTENCES

Added in API level 3

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)

public static final int CAP_MODE_WORDS

Added in API level 3

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

public static final Creator<CharSequence> CHAR_SEQUENCE_CREATOR

Added in API level 1

Public Methods

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

Added in API level 1

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 the text to truncate
p the Paint with which to measure the text
avail the horizontal width available for the text
oneMore the string for "1 more" in the current locale
more the string for "%d more" in the current locale
Returns
CharSequence

public static CharSequence concat (CharSequence... text)

Added in API level 1

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

Parameters
text
Returns
CharSequence

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

Added in API level 1

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
start
end
kind
dest
destoff
Throws
IndexOutOfBoundsException if any of the copied spans are out of range in dest.

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

Added in API level 3

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
printer
prefix

public static CharSequence ellipsize (CharSequence text, TextPaint p, float avail, TextUtils.TruncateAt where)

Added in API level 1

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
p
avail
where
Returns
CharSequence

public static CharSequence ellipsize (CharSequence text, TextPaint paint, float avail, TextUtils.TruncateAt where, boolean preserveLength, TextUtils.EllipsizeCallback callback)

Added in API level 1

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
paint
avail
where
preserveLength
callback
Returns
CharSequence

public static boolean equals (CharSequence a, CharSequence b)

Added in API level 1

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 first CharSequence to check
b second CharSequence to check
Returns
boolean true if a and b are equal

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

Added in API level 1

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 the input text containing "^1"-style placeholder values. This object is not modified; a copy is returned.
values 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.

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

Added in API level 3

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 The text that should be checked for caps modes.
off Location in the text at which to check.
reqModes 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.

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

Added in API level 1

Parameters
s
start
end
dest
destoff

public static int getLayoutDirectionFromLocale (Locale locale)

Added in API level 17

Return the layout direction for a given Locale

Parameters
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

public static int getOffsetAfter (CharSequence text, int offset)

Added in API level 1

Parameters
text
offset
Returns
int

public static int getOffsetBefore (CharSequence text, int offset)

Added in API level 1

Parameters
text
offset
Returns
int

public static CharSequence getReverse (CharSequence source, int start, int end)

Added in API level 1

Parameters
source
start
end
Returns
CharSequence

public static int getTrimmedLength (CharSequence s)

Added in API level 1

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

Parameters
s
Returns
int

public static String htmlEncode (String s)

Added in API level 1

Html-encode the string.

Parameters
s the string to be encoded
Returns
String the encoded string

public static int indexOf (CharSequence s, char ch)

Added in API level 1

Parameters
s
ch
Returns
int

public static int indexOf (CharSequence s, CharSequence needle)

Added in API level 1

Parameters
s
needle
Returns
int

public static int indexOf (CharSequence s, CharSequence needle, int start)

Added in API level 1

Parameters
s
needle
start
Returns
int

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

Added in API level 1

Parameters
s
ch
start
end
Returns
int

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

Added in API level 1

Parameters
s
ch
start
Returns
int

public static int indexOf (CharSequence s, CharSequence needle, int start, int end)

Added in API level 1

Parameters
s
needle
start
end
Returns
int

public static boolean isDigitsOnly (CharSequence str)

Added in API level 1

Returns whether the given CharSequence contains only digits.

Parameters
str
Returns
boolean

public static boolean isEmpty (CharSequence str)

Added in API level 1

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

Parameters
str the string to be examined
Returns
boolean true if str is null or zero length

public static boolean isGraphic (CharSequence str)

Added in API level 1

Returns whether the given CharSequence contains any printable characters.

Parameters
str
Returns
boolean

public static boolean isGraphic (char c)

Added in API level 1

Returns whether this character is a printable character.

Parameters
c
Returns
boolean

public static String join (CharSequence delimiter, Iterable tokens)

Added in API level 1

Returns a string containing the tokens joined by delimiters.

Parameters
tokens an array objects to be joined. Strings will be formed from the objects by calling object.toString().
Returns
String

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

Added in API level 1

Returns a string containing the tokens joined by delimiters.

Parameters
tokens an array objects to be joined. Strings will be formed from the objects by calling object.toString().
Returns
String

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

Added in API level 1

Parameters
s
ch
start
last
Returns
int

public static int lastIndexOf (CharSequence s, char ch)

Added in API level 1

Parameters
s
ch
Returns
int

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

Added in API level 1

Parameters
s
ch
last
Returns
int

public static boolean regionMatches (CharSequence one, int toffset, CharSequence two, int ooffset, int len)

Added in API level 1

Parameters
one
toffset
two
ooffset
len
Returns
boolean

public static CharSequence replace (CharSequence template, String[] sources, CharSequence[] destinations)

Added in API level 1

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

Parameters
template
sources
destinations
Returns
CharSequence

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

Added in API level 1

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 the string to split
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

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

Added in API level 1

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 the string to split
expression 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

public static CharSequence stringOrSpannedString (CharSequence source)

Added in API level 1

Parameters
source
Returns
CharSequence

public static String substring (CharSequence source, int start, int end)

Added in API level 1

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
start
end
Returns
String

public static void writeToParcel (CharSequence cs, Parcel p, int parcelableFlags)

Added in API level 1

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

Parameters
cs
p
parcelableFlags