TextUtils
public
class
TextUtils
extends Object
Summary
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<T> 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 String.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(java.lang.CharSequence) instead.
|
static
String
|
join(CharSequence delimiter, Iterable<T> 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
CharSequence
|
makeSafeForPresentation(String unclean, int maxCharactersToConsider, float ellipsizeDip, int flags)
Remove html, remove bad characters, and truncate string.
|
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)
This method yields the same result as text.split(expression, -1) except that if
text.isEmpty() then this method returns an empty array whereas
"".split(expression, -1) would have returned an array with a single "" .
|
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
Object
|
clone()
Creates and returns a copy of this object.
|
boolean
|
equals(Object obj)
Indicates whether some other object is "equal to" this one.
|
void
|
finalize()
Called by the garbage collector on an object when garbage collection
determines that there are no more references to the object.
|
final
Class<?>
|
getClass()
Returns the runtime class of this Object .
|
int
|
hashCode()
Returns a hash code value for the object.
|
final
void
|
notify()
Wakes up a single thread that is waiting on this object's
monitor.
|
final
void
|
notifyAll()
Wakes up all threads that are waiting on this object's monitor.
|
String
|
toString()
Returns a string representation of the object.
|
final
void
|
wait(long timeoutMillis, int nanos)
Causes the current thread to wait until it is awakened, typically
by being notified or interrupted, or until a
certain amount of real time has elapsed.
|
final
void
|
wait(long timeoutMillis)
Causes the current thread to wait until it is awakened, typically
by being notified or interrupted, or until a
certain amount of real time has elapsed.
|
final
void
|
wait()
Causes the current thread to wait until it is awakened, typically
by being notified or interrupted.
|
|
Constants
SAFE_STRING_FLAG_FIRST_LINE
public static final int SAFE_STRING_FLAG_FIRST_LINE
Return only first line of text (truncate at first newline). Cannot be set at the same time as
SAFE_STRING_FLAG_SINGLE_LINE
.
Constant Value:
4
(0x00000004)
SAFE_STRING_FLAG_SINGLE_LINE
public static final int SAFE_STRING_FLAG_SINGLE_LINE
Force entire string into single line of text (no newlines). Cannot be set at the same time as
SAFE_STRING_FLAG_FIRST_LINE
.
Constant Value:
2
(0x00000002)
SAFE_STRING_FLAG_TRIM
public static final int SAFE_STRING_FLAG_TRIM
Remove whitespace
and non-breaking spaces from the edges
of the label.
Constant Value:
1
(0x00000001)
Fields
Public methods
commaEllipsize
public 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.
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 |
concat
public static 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 |
copySpansFrom
public static void copySpansFrom (Spanned source,
int start,
int end,
Class<T> 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 |
dumpSpans
public static 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
public 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.
Parameters |
text |
CharSequence |
p |
TextPaint |
avail |
float |
where |
TextUtils.TruncateAt |
ellipsize
public 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.
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 : This value may be null . |
equals
public static 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
public static 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
public static 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
.
getChars
public static void getChars (CharSequence s,
int start,
int end,
char[] dest,
int destoff)
Parameters |
s |
CharSequence |
start |
int |
end |
int |
dest |
char |
destoff |
int |
getLayoutDirectionFromLocale
public static 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. |
getOffsetAfter
public static int getOffsetAfter (CharSequence text,
int offset)
Parameters |
text |
CharSequence |
offset |
int |
getOffsetBefore
public static int getOffsetBefore (CharSequence text,
int offset)
Parameters |
text |
CharSequence |
offset |
int |
getReverse
public static CharSequence getReverse (CharSequence source,
int start,
int end)
This method was deprecated
in API level 24.
Do not use.
This function only reverses individual char
s 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 |
getTrimmedLength
public 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 String.trim
.
Parameters |
s |
CharSequence |
htmlEncode
public static String htmlEncode (String s)
Html-encode the string.
Parameters |
s |
String : the string to be encoded |
Returns |
String |
the encoded string |
indexOf
public static int indexOf (CharSequence s,
char ch,
int start,
int end)
Parameters |
s |
CharSequence |
ch |
char |
start |
int |
end |
int |
indexOf
public static int indexOf (CharSequence s,
CharSequence needle,
int start,
int end)
Parameters |
s |
CharSequence |
needle |
CharSequence |
start |
int |
end |
int |
indexOf
public static int indexOf (CharSequence s,
CharSequence needle,
int start)
Parameters |
s |
CharSequence |
needle |
CharSequence |
start |
int |
indexOf
public static int indexOf (CharSequence s,
char ch,
int start)
Parameters |
s |
CharSequence |
ch |
char |
start |
int |
indexOf
public static int indexOf (CharSequence s,
char ch)
Parameters |
s |
CharSequence |
ch |
char |
isDigitsOnly
public static boolean isDigitsOnly (CharSequence str)
Returns whether the given CharSequence contains only digits.
Parameters |
str |
CharSequence |
isEmpty
public static 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
public static boolean isGraphic (CharSequence str)
Returns whether the given CharSequence contains any printable characters.
Parameters |
str |
CharSequence |
isGraphic
public static boolean isGraphic (char c)
This method was deprecated
in API level 24.
Use isGraphic(java.lang.CharSequence)
instead.
Returns whether this character is a printable character.
This does not support non-BMP characters and should not be used.
join
public static String join (CharSequence delimiter,
Iterable<T> tokens)
Returns a string containing the tokens joined by delimiters.
Parameters |
delimiter |
CharSequence : a CharSequence that will be inserted between the tokens. If null, the string
"null" will be used as the delimiter. |
tokens |
Iterable : an array objects to be joined. Strings will be formed from the objects by
calling object.toString(). If tokens is null, a NullPointerException will be thrown. If
tokens is empty, an empty string will be returned. |
join
public static String join (CharSequence delimiter,
Object[] tokens)
Returns a string containing the tokens joined by delimiters.
Parameters |
delimiter |
CharSequence : a CharSequence that will be inserted between the tokens. If null, the string
"null" will be used as the delimiter. |
tokens |
Object : an array objects to be joined. Strings will be formed from the objects by
calling object.toString(). If tokens is null, a NullPointerException will be thrown. If
tokens is an empty array, an empty string will be returned. |
lastIndexOf
public static int lastIndexOf (CharSequence s,
char ch,
int last)
Parameters |
s |
CharSequence |
ch |
char |
last |
int |
lastIndexOf
public static int lastIndexOf (CharSequence s,
char ch)
Parameters |
s |
CharSequence |
ch |
char |
lastIndexOf
public static int lastIndexOf (CharSequence s,
char ch,
int start,
int last)
Parameters |
s |
CharSequence |
ch |
char |
start |
int |
last |
int |
listEllipsize
public 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.
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 BidiFormatter.unicodeWrap
based on the locale of the input
Context. If the input Context
is null, the default BidiFormatter from
BidiFormatter.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 cannot be null . |
paint |
TextPaint : the Paint with which to measure the text
This value cannot 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. |
makeSafeForPresentation
public static CharSequence makeSafeForPresentation (String unclean,
int maxCharactersToConsider,
float ellipsizeDip,
int flags)
Remove html, remove bad characters, and truncate string.
This method is meant to remove common mistakes and nefarious formatting from strings that
were loaded from untrusted sources (such as other packages).
This method first treats the string like HTML
and then ...
- Removes new lines or truncates at first new line
- Trims the white-space off the end
- Truncates the string
... if specified.
Parameters |
unclean |
String : The input string
This value cannot be null . |
maxCharactersToConsider |
int : The maximum number of characters of unclean to
consider from the input string. 0 disables this
feature.
Value is 0 or greater |
ellipsizeDip |
float : Assuming maximum length of the string (in dip), assuming font size 42.
This is roughly 50 characters for ellipsizeDip == 1000 .
Usually ellipsizing should be left to the view showing the string. If a
string is used as an input to another string, it might be useful to
control the length of the input string though. 0 disables this
feature.
Value is 0 or greater |
flags |
int : Flags controlling cleaning behavior (Can be SAFE_STRING_FLAG_TRIM ,
SAFE_STRING_FLAG_SINGLE_LINE ,
and SAFE_STRING_FLAG_FIRST_LINE )
Value is either 0 or a combination of SAFE_STRING_FLAG_TRIM , SAFE_STRING_FLAG_SINGLE_LINE , and SAFE_STRING_FLAG_FIRST_LINE |
Returns |
CharSequence |
The cleaned string
This value cannot be null . |
regionMatches
public static boolean regionMatches (CharSequence one,
int toffset,
CharSequence two,
int ooffset,
int len)
Parameters |
one |
CharSequence |
toffset |
int |
two |
CharSequence |
ooffset |
int |
len |
int |
replace
public 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.
Parameters |
template |
CharSequence |
sources |
String |
destinations |
CharSequence |
split
public static String[] split (String text,
Pattern pattern)
Splits a string on a pattern. This method yields the same result as
pattern.split(text, -1)
except that if text.isEmpty()
then this method
returns an empty array whereas pattern.split("", -1)
would have returned an array
with a single ""
.
The -1
means that trailing empty Strings are not removed from the result;
Note that whether a leading zero-width match can result in a leading ""
depends
on whether your app targets
an SDK version
<= 28
; see Pattern.split(CharSequence, int)
.
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 |
split
public static String[] split (String text,
String expression)
This method yields the same result as text.split(expression, -1)
except that if
text.isEmpty()
then this method returns an empty array whereas
"".split(expression, -1)
would have returned an array with a single ""
.
The -1
means that trailing empty Strings are not removed from the result; for
example split("a,", "," ) returns {"a", ""}. Note that whether a leading zero-width match
can result in a leading ""
depends on whether your app
targets an SDK version
<= 28
; see Pattern.split(CharSequence, int)
.
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 |
stringOrSpannedString
public static CharSequence stringOrSpannedString (CharSequence source)
Parameters |
source |
CharSequence |
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.
Parameters |
source |
CharSequence |
start |
int |
end |
int |
writeToParcel
public static 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 : This value may be null . |
p |
Parcel : This value cannot be null . |
parcelableFlags |
int |