public final class

String

extends Object
implements Serializable CharSequence Comparable<T>
java.lang.Object
   ↳ java.lang.String

Class Overview

An immutable sequence of characters/code units (chars). A String is represented by array of UTF-16 values, such that Unicode supplementary characters (code points) are stored/encoded as surrogate pairs via Unicode code units (char).

Backing Arrays

This class is implemented using a char[]. The length of the array may exceed the length of the string. For example, the string "Hello" may be backed by the array ['H', 'e', 'l', 'l', 'o', 'W'. 'o', 'r', 'l', 'd'] with offset 0 and length 5.

Multiple strings can share the same char[] because strings are immutable. The substring(int) method always returns a string that shares the backing array of its source string. Generally this is an optimization: fewer character arrays need to be allocated, and less copying is necessary. But this can also lead to unwanted heap retention. Taking a short substring of long string means that the long shared char[] won't be garbage until both strings are garbage. This typically happens when parsing small substrings out of a large input. To avoid this where necessary, call new String(longString.subString(...)). The string copy constructor always ensures that the backing array is no larger than necessary.

See Also

Summary

Constants
Comparator<String> CASE_INSENSITIVE_ORDER A comparator ignoring the case of the characters.
Public Constructors
String()
Creates an empty string.
String(byte[] data)
Converts the byte array to a string using the system's default charset.
String(byte[] data, int high)
This constructor is deprecated. Use String(byte[]) or String(byte[], String) instead.
String(byte[] data, int start, int length)
Converts a subsequence of the byte array to a string using the system's default charset.
String(byte[] data, int high, int start, int length)
This constructor is deprecated. Use String(byte[], int, int) instead.
String(byte[] data, int start, int length, String charsetName)
Converts the byte array to a string using the named charset.
String(byte[] data, String charsetName)
Converts the byte array to a string using the named charset.
String(byte[] data, int start, int length, Charset charset)
Converts the byte array to a string using the given charset.
String(byte[] data, Charset charset)
Converts the byte array to a String using the given charset.
String(char[] data)
Initializes this string to contain the characters in the specified character array.
String(char[] data, int start, int length)
Initializes this string to contain the specified characters in the character array.
String(String toCopy)
Constructs a new string with the same sequence of characters as toCopy.
String(StringBuffer stringbuffer)
Creates a String from the contents of the specified StringBuffer.
String(int[] codePoints, int offset, int count)
Creates a String from the sub-array of Unicode code points.
String(StringBuilder sb)
Creates a String from the contents of the specified StringBuilder.
Public Methods
char charAt(int index)
Returns the character at the specified offset in this string.
int codePointAt(int index)
Returns the Unicode code point at the given index.
int codePointBefore(int index)
Returns the Unicode code point that precedes the given index.
int codePointCount(int beginIndex, int endIndex)
Calculates the number of Unicode code points between beginIndex and endIndex.
int compareTo(String string)
Compares the specified string to this string using the Unicode values of the characters.
int compareToIgnoreCase(String string)
Compares the specified string to this string using the Unicode values of the characters, ignoring case differences.
String concat(String string)
Concatenates this string and the specified string.
boolean contains(CharSequence cs)
Determines if this String contains the sequence of characters in the CharSequence passed.
boolean contentEquals(CharSequence cs)
Compares a CharSequence to this String to determine if their contents are equal.
boolean contentEquals(StringBuffer strbuf)
Returns whether the characters in the StringBuffer strbuf are the same as those in this string.
static String copyValueOf(char[] data, int start, int length)
Creates a new string containing the specified characters in the character array.
static String copyValueOf(char[] data)
Creates a new string containing the characters in the specified character array.
boolean endsWith(String suffix)
Compares the specified string to this string to determine if the specified string is a suffix.
boolean equals(Object object)
Compares the specified object to this string and returns true if they are equal.
boolean equalsIgnoreCase(String string)
Compares the specified string to this string ignoring the case of the characters and returns true if they are equal.
static String format(Locale locale, String format, Object... args)
Returns a formatted string, using the supplied format and arguments, localized to the given locale.
static String format(String format, Object... args)
Returns a localized formatted string, using the supplied format and arguments, using the user's default locale.
void getBytes(int start, int end, byte[] data, int index)
This method is deprecated. Use getBytes() or getBytes(String)
byte[] getBytes(String charsetName)
Returns a new byte array containing the characters of this string encoded using the named charset.
byte[] getBytes(Charset charset)
Returns a new byte array containing the characters of this string encoded using the given charset.
byte[] getBytes()
Returns a new byte array containing the characters of this string encoded using the system's default charset.
void getChars(int start, int end, char[] buffer, int index)
Copies the specified characters in this string to the character array starting at the specified offset in the character array.
int hashCode()
Returns an integer hash code for this object.
int indexOf(int c)
Searches in this string for the first index of the specified character.
int indexOf(int c, int start)
Searches in this string for the index of the specified character.
int indexOf(String subString, int start)
Searches in this string for the index of the specified string.
int indexOf(String string)
Searches in this string for the first index of the specified string.
String intern()
Searches an internal table of strings for a string equal to this string.
boolean isEmpty()
Returns true if the length of this string is 0.
int lastIndexOf(String string)
Searches in this string for the last index of the specified string.
int lastIndexOf(int c, int start)
Searches in this string for the index of the specified character.
int lastIndexOf(int c)
Searches in this string for the last index of the specified character.
int lastIndexOf(String subString, int start)
Searches in this string for the index of the specified string.
int length()
Returns the size of this string.
boolean matches(String regularExpression)
Tests whether this string matches the given regularExpression.
int offsetByCodePoints(int index, int codePointOffset)
Returns the index within this object that is offset from index by codePointOffset code points.
boolean regionMatches(boolean ignoreCase, int thisStart, String string, int start, int length)
Compares the specified string to this string and compares the specified range of characters to determine if they are the same.
boolean regionMatches(int thisStart, String string, int start, int length)
Compares the specified string to this string and compares the specified range of characters to determine if they are the same.
String replace(CharSequence target, CharSequence replacement)
Copies this string replacing occurrences of the specified target sequence with another sequence.
String replace(char oldChar, char newChar)
Copies this string replacing occurrences of the specified character with another character.
String replaceAll(String regularExpression, String replacement)
Replaces all matches for regularExpression within this string with the given replacement.
String replaceFirst(String regularExpression, String replacement)
Replaces the first match for regularExpression within this string with the given replacement.
String[] split(String regularExpression)
Splits this string using the supplied regularExpression.
String[] split(String regularExpression, int limit)
Splits this string using the supplied regularExpression.
boolean startsWith(String prefix)
Compares the specified string to this string to determine if the specified string is a prefix.
boolean startsWith(String prefix, int start)
Compares the specified string to this string, starting at the specified offset, to determine if the specified string is a prefix.
CharSequence subSequence(int start, int end)
Has the same result as the substring function, but is present so that string may implement the CharSequence interface.
String substring(int start)
Returns a string containing a suffix of this string.
String substring(int start, int end)
Returns a string containing a subsequence of characters from this string.
char[] toCharArray()
Copies the characters in this string to a character array.
String toLowerCase(Locale locale)
Converts this string to lowercase, using the rules of locale.
String toLowerCase()
Converts this string to lowercase, using the rules of the user's default locale.
String toString()
Returns this string.
String toUpperCase(Locale locale)
Converts this this string to uppercase, using the rules of locale.
String toUpperCase()
Converts this this string to uppercase, using the rules of the user's default locale.
String trim()
Copies this string removing white space characters from the beginning and end of the string.
static String valueOf(long value)
Converts the specified long to its string representation.
static String valueOf(Object value)
Converts the specified object to its string representation.
static String valueOf(char[] data)
Creates a new string containing the characters in the specified character array.
static String valueOf(double value)
Converts the specified double to its string representation.
static String valueOf(int value)
Converts the specified integer to its string representation.
static String valueOf(float value)
Converts the specified float to its string representation.
static String valueOf(char[] data, int start, int length)
Creates a new string containing the specified characters in the character array.
static String valueOf(boolean value)
Converts the specified boolean to its string representation.
static String valueOf(char value)
Converts the specified character to its string representation.
[Expand]
Inherited Methods
From class java.lang.Object
From interface java.lang.CharSequence
From interface java.lang.Comparable

Constants

public static final Comparator<String> CASE_INSENSITIVE_ORDER

Since: API Level 1

A comparator ignoring the case of the characters.

Public Constructors

public String ()

Since: API Level 1

Creates an empty string.

public String (byte[] data)

Since: API Level 1

Converts the byte array to a string using the system's default charset.

public String (byte[] data, int high)

Since: API Level 1

This constructor is deprecated.
Use String(byte[]) or String(byte[], String) instead.

Converts the byte array to a string, setting the high byte of every character to the specified value.

Parameters
data the byte array to convert to a string.
high the high byte to use.
Throws
NullPointerException when data is null.

public String (byte[] data, int start, int length)

Since: API Level 1

Converts a subsequence of the byte array to a string using the system's default charset.

Parameters
data the byte array to convert to a string.
start the starting offset in the byte array.
length the number of bytes to convert.
Throws
NullPointerException when data is null.
IndexOutOfBoundsException if length < 0, start < 0 or start + length > data.length.

public String (byte[] data, int high, int start, int length)

Since: API Level 1

This constructor is deprecated.
Use String(byte[], int, int) instead.

Converts the byte array to a string, setting the high byte of every character to the specified value.

Parameters
data the byte array to convert to a string.
high the high byte to use.
start the starting offset in the byte array.
length the number of bytes to convert.
Throws
NullPointerException when data is null.
IndexOutOfBoundsException if length < 0, start < 0 or start + length > data.length

public String (byte[] data, int start, int length, String charsetName)

Since: API Level 1

Converts the byte array to a string using the named charset.

The behavior when the bytes cannot be decoded by the named charset is unspecified. Use CharsetDecoder for more control.

Parameters
data the byte array to convert to a string.
start the starting offset in the byte array.
length the number of bytes to convert.
charsetName the charset name.
Throws
NullPointerException when data is null.
IndexOutOfBoundsException if length < 0, start < 0 or start + length > data.length.
UnsupportedEncodingException if the named charset is not supported.

public String (byte[] data, String charsetName)

Since: API Level 1

Converts the byte array to a string using the named charset.

The behavior when the bytes cannot be decoded by the named charset is unspecified. Use CharsetDecoder for more control.

Parameters
data the byte array to convert to a string.
charsetName the charset name.
Throws
NullPointerException when data is null.
UnsupportedEncodingException if charsetName is not supported.

public String (byte[] data, int start, int length, Charset charset)

Since: API Level 9

Converts the byte array to a string using the given charset.

The behavior when the bytes cannot be decoded by the given charset is to replace malformed input and unmappable characters with the charset's default replacement string. Use CharsetDecoder for more control.

Parameters
data the byte array to convert to a String
start the starting offset in the byte array
length the number of bytes to convert
charset the charset
Throws
IndexOutOfBoundsException when length < 0, start < 0 or start + length > data.length
NullPointerException when data is null
See Also

public String (byte[] data, Charset charset)

Since: API Level 9

Converts the byte array to a String using the given charset.

Throws
NullPointerException if data == null
See Also

public String (char[] data)

Since: API Level 1

Initializes this string to contain the characters in the specified character array. Modifying the character array after creating the string has no effect on the string.

Parameters
data the array of characters.
Throws
NullPointerException when data is null.

public String (char[] data, int start, int length)

Since: API Level 1

Initializes this string to contain the specified characters in the character array. Modifying the character array after creating the string has no effect on the string.

Parameters
data the array of characters.
start the starting offset in the character array.
length the number of characters to use.
Throws
NullPointerException when data is null.
IndexOutOfBoundsException if length < 0, start < 0 or start + length > data.length

public String (String toCopy)

Since: API Level 1

Constructs a new string with the same sequence of characters as toCopy. The returned string's backing array is no larger than necessary.

public String (StringBuffer stringbuffer)

Since: API Level 1

Creates a String from the contents of the specified StringBuffer.

Parameters
stringbuffer the buffer to get the contents from.

public String (int[] codePoints, int offset, int count)

Since: API Level 1

Creates a String from the sub-array of Unicode code points.

Parameters
codePoints the array of Unicode code points to convert.
offset the inclusive index into codePoints to begin converting from.
count the number of elements in codePoints to copy.
Throws
NullPointerException if codePoints is null.
IllegalArgumentException if any of the elements of codePoints are not valid Unicode code points.
IndexOutOfBoundsException if offset or count are not within the bounds of codePoints.

public String (StringBuilder sb)

Since: API Level 1

Creates a String from the contents of the specified StringBuilder.

Parameters
sb the StringBuilder to copy the contents from.
Throws
NullPointerException if sb is null.

Public Methods

public char charAt (int index)

Since: API Level 1

Returns the character at the specified offset in this string.

Parameters
index the zero-based index in this string.
Returns
  • the character at the index.
Throws
IndexOutOfBoundsException if index < 0 or index >= length().

public int codePointAt (int index)

Since: API Level 1

Returns the Unicode code point at the given index.

Throws
IndexOutOfBoundsException if index < 0 || index >= length()
See Also

public int codePointBefore (int index)

Since: API Level 1

Returns the Unicode code point that precedes the given index.

Throws
IndexOutOfBoundsException if index < 1 || index > length()
See Also

public int codePointCount (int beginIndex, int endIndex)

Since: API Level 1

Calculates the number of Unicode code points between beginIndex and endIndex.

Parameters
beginIndex the inclusive beginning index of the subsequence.
endIndex the exclusive end index of the subsequence.
Returns
  • the number of Unicode code points in the subsequence.
Throws
IndexOutOfBoundsException if beginIndex < 0 || endIndex > length() || beginIndex > endIndex
See Also

public int compareTo (String string)

Since: API Level 1

Compares the specified string to this string using the Unicode values of the characters. Returns 0 if the strings contain the same characters in the same order. Returns a negative integer if the first non-equal character in this string has a Unicode value which is less than the Unicode value of the character at the same position in the specified string, or if this string is a prefix of the specified string. Returns a positive integer if the first non-equal character in this string has a Unicode value which is greater than the Unicode value of the character at the same position in the specified string, or if the specified string is a prefix of this string.

Parameters
string the string to compare.
Returns
  • 0 if the strings are equal, a negative integer if this string is before the specified string, or a positive integer if this string is after the specified string.
Throws
NullPointerException if string is null.

public int compareToIgnoreCase (String string)

Since: API Level 1

Compares the specified string to this string using the Unicode values of the characters, ignoring case differences. Returns 0 if the strings contain the same characters in the same order. Returns a negative integer if the first non-equal character in this string has a Unicode value which is less than the Unicode value of the character at the same position in the specified string, or if this string is a prefix of the specified string. Returns a positive integer if the first non-equal character in this string has a Unicode value which is greater than the Unicode value of the character at the same position in the specified string, or if the specified string is a prefix of this string.

Parameters
string the string to compare.
Returns
  • 0 if the strings are equal, a negative integer if this string is before the specified string, or a positive integer if this string is after the specified string.
Throws
NullPointerException if string is null.

public String concat (String string)

Since: API Level 1

Concatenates this string and the specified string.

Parameters
string the string to concatenate
Returns
  • a new string which is the concatenation of this string and the specified string.

public boolean contains (CharSequence cs)

Since: API Level 1

Determines if this String contains the sequence of characters in the CharSequence passed.

Parameters
cs the character sequence to search for.
Returns
  • true if the sequence of characters are contained in this string, otherwise false.

public boolean contentEquals (CharSequence cs)

Since: API Level 1

Compares a CharSequence to this String to determine if their contents are equal.

Parameters
cs the character sequence to compare to.
Returns
  • true if equal, otherwise false

public boolean contentEquals (StringBuffer strbuf)

Since: API Level 1

Returns whether the characters in the StringBuffer strbuf are the same as those in this string.

Parameters
strbuf the StringBuffer to compare this string to.
Returns
  • true if the characters in strbuf are identical to those in this string. If they are not, false will be returned.
Throws
NullPointerException if strbuf is null.

public static String copyValueOf (char[] data, int start, int length)

Since: API Level 1

Creates a new string containing the specified characters in the character array. Modifying the character array after creating the string has no effect on the string.

Parameters
data the array of characters.
start the starting offset in the character array.
length the number of characters to use.
Returns
  • the new string.
Throws
NullPointerException if data is null.
IndexOutOfBoundsException if length < 0, start < 0 or start + length > data.length.

public static String copyValueOf (char[] data)

Since: API Level 1

Creates a new string containing the characters in the specified character array. Modifying the character array after creating the string has no effect on the string.

Parameters
data the array of characters.
Returns
  • the new string.
Throws
NullPointerException if data is null.

public boolean endsWith (String suffix)

Since: API Level 1

Compares the specified string to this string to determine if the specified string is a suffix.

Parameters
suffix the suffix to look for.
Returns
  • true if the specified string is a suffix of this string, false otherwise.
Throws
NullPointerException if suffix is null.

public boolean equals (Object object)

Since: API Level 1

Compares the specified object to this string and returns true if they are equal. The object must be an instance of string with the same characters in the same order.

Parameters
object the object to compare.
Returns
  • true if the specified object is equal to this string, false otherwise.
See Also

public boolean equalsIgnoreCase (String string)

Since: API Level 1

Compares the specified string to this string ignoring the case of the characters and returns true if they are equal.

Parameters
string the string to compare.
Returns
  • true if the specified string is equal to this string, false otherwise.

public static String format (Locale locale, String format, Object... args)

Since: API Level 1

Returns a formatted string, using the supplied format and arguments, localized to the given locale.

Parameters
locale the locale to apply; null value means no localization.
format the format string (see format(String, Object...))
args the list of arguments passed to the formatter. If there are more arguments than required by format, additional arguments are ignored.
Returns
  • the formatted string.
Throws
NullPointerException if format == null
IllegalFormatException if the format is invalid.

public static String format (String format, Object... args)

Since: API Level 1

Returns a localized formatted string, using the supplied format and arguments, using the user's default locale.

If you're formatting a string other than for human consumption, you should use the format(Locale, String, Object...) overload and supply Locale.US. See "Be wary of the default locale".

Parameters
format the format string (see format(String, Object...))
args the list of arguments passed to the formatter. If there are more arguments than required by format, additional arguments are ignored.
Returns
  • the formatted string.
Throws
NullPointerException if format == null
IllegalFormatException if the format is invalid.

public void getBytes (int start, int end, byte[] data, int index)

Since: API Level 1

This method is deprecated.
Use getBytes() or getBytes(String)

Converts this string to a byte array, ignoring the high order bits of each character.

Parameters
start the starting offset of characters to copy.
end the ending offset of characters to copy.
data the destination byte array.
index the starting offset in the destination byte array.
Throws
NullPointerException if data is null.
IndexOutOfBoundsException if start < 0, end > length(), index < 0 or end - start > data.length - index.

public byte[] getBytes (String charsetName)

Since: API Level 1

Returns a new byte array containing the characters of this string encoded using the named charset.

The behavior when this string cannot be represented in the named charset is unspecified. Use CharsetEncoder for more control.

Throws
UnsupportedEncodingException if the charset is not supported

public byte[] getBytes (Charset charset)

Since: API Level 9

Returns a new byte array containing the characters of this string encoded using the given charset.

The behavior when this string cannot be represented in the given charset is to replace malformed input and unmappable characters with the charset's default replacement byte array. Use CharsetEncoder for more control.

public byte[] getBytes ()

Since: API Level 1

Returns a new byte array containing the characters of this string encoded using the system's default charset.

The behavior when this string cannot be represented in the system's default charset is unspecified. In practice, when the default charset is UTF-8 (as it is on Android), all strings can be encoded.

public void getChars (int start, int end, char[] buffer, int index)

Since: API Level 1

Copies the specified characters in this string to the character array starting at the specified offset in the character array.

Parameters
start the starting offset of characters to copy.
end the ending offset of characters to copy.
buffer the destination character array.
index the starting offset in the character array.
Throws
NullPointerException if buffer is null.
IndexOutOfBoundsException if start < 0, end > length(), start > end, index < 0, end - start > buffer.length - index

public int hashCode ()

Since: API Level 1

Returns an integer hash code for this object. By contract, any two objects for which equals(Object) returns true must return the same hash code value. This means that subclasses of Object usually override both methods or neither method.

Note that hash values must not change over time unless information used in equals comparisons also changes.

See Writing a correct hashCode method if you intend implementing your own hashCode method.

Returns
  • this object's hash code.

public int indexOf (int c)

Since: API Level 1

Searches in this string for the first index of the specified character. The search for the character starts at the beginning and moves towards the end of this string.

Parameters
c the character to find.
Returns
  • the index in this string of the specified character, -1 if the character isn't found.

public int indexOf (int c, int start)

Since: API Level 1

Searches in this string for the index of the specified character. The search for the character starts at the specified offset and moves towards the end of this string.

Parameters
c the character to find.
start the starting offset.
Returns
  • the index in this string of the specified character, -1 if the character isn't found.

public int indexOf (String subString, int start)

Since: API Level 1

Searches in this string for the index of the specified string. The search for the string starts at the specified offset and moves towards the end of this string.

Parameters
subString the string to find.
start the starting offset.
Returns
  • the index of the first character of the specified string in this string, -1 if the specified string is not a substring.
Throws
NullPointerException if subString is null.

public int indexOf (String string)

Since: API Level 1

Searches in this string for the first index of the specified string. The search for the string starts at the beginning and moves towards the end of this string.

Parameters
string the string to find.
Returns
  • the index of the first character of the specified string in this string, -1 if the specified string is not a substring.
Throws
NullPointerException if string is null.

public String intern ()

Since: API Level 1

Searches an internal table of strings for a string equal to this string. If the string is not in the table, it is added. Returns the string contained in the table which is equal to this string. The same string object is always returned for strings which are equal.

Returns
  • the interned string equal to this string.

public boolean isEmpty ()

Since: API Level 9

Returns true if the length of this string is 0.

public int lastIndexOf (String string)

Since: API Level 1

Searches in this string for the last index of the specified string. The search for the string starts at the end and moves towards the beginning of this string.

Parameters
string the string to find.
Returns
  • the index of the first character of the specified string in this string, -1 if the specified string is not a substring.
Throws
NullPointerException if string is null.

public int lastIndexOf (int c, int start)

Since: API Level 1

Searches in this string for the index of the specified character. The search for the character starts at the specified offset and moves towards the beginning of this string.

Parameters
c the character to find.
start the starting offset.
Returns
  • the index in this string of the specified character, -1 if the character isn't found.

public int lastIndexOf (int c)

Since: API Level 1

Searches in this string for the last index of the specified character. The search for the character starts at the end and moves towards the beginning of this string.

Parameters
c the character to find.
Returns
  • the index in this string of the specified character, -1 if the character isn't found.

public int lastIndexOf (String subString, int start)

Since: API Level 1

Searches in this string for the index of the specified string. The search for the string starts at the specified offset and moves towards the beginning of this string.

Parameters
subString the string to find.
start the starting offset.
Returns
  • the index of the first character of the specified string in this string , -1 if the specified string is not a substring.
Throws
NullPointerException if subString is null.

public int length ()

Since: API Level 1

Returns the size of this string.

Returns
  • the number of characters in this string.

public boolean matches (String regularExpression)

Since: API Level 1

Tests whether this string matches the given regularExpression. This method returns true only if the regular expression matches the entire input string. A common mistake is to assume that this method behaves like contains(CharSequence); if you want to match anywhere within the input string, you need to add .* to the beginning and end of your regular expression. See matches(String, CharSequence).

If the same regular expression is to be used for multiple operations, it may be more efficient to reuse a compiled Pattern.

Throws
if the syntax of the supplied regular expression is not valid.
NullPointerException if regularExpression == null

public int offsetByCodePoints (int index, int codePointOffset)

Since: API Level 1

Returns the index within this object that is offset from index by codePointOffset code points.

Parameters
index the index within this object to calculate the offset from.
codePointOffset the number of code points to count.
Returns
  • the index within this object that is the offset.
Throws
IndexOutOfBoundsException if index is negative or greater than length() or if there aren't enough code points before or after index to match codePointOffset.

public boolean regionMatches (boolean ignoreCase, int thisStart, String string, int start, int length)

Since: API Level 1

Compares the specified string to this string and compares the specified range of characters to determine if they are the same. When ignoreCase is true, the case of the characters is ignored during the comparison.

Parameters
ignoreCase specifies if case should be ignored.
thisStart the starting offset in this string.
string the string to compare.
start the starting offset in the specified string.
length the number of characters to compare.
Returns
  • true if the ranges of characters are equal, false otherwise.
Throws
NullPointerException if string is null.

public boolean regionMatches (int thisStart, String string, int start, int length)

Since: API Level 1

Compares the specified string to this string and compares the specified range of characters to determine if they are the same.

Parameters
thisStart the starting offset in this string.
string the string to compare.
start the starting offset in the specified string.
length the number of characters to compare.
Returns
  • true if the ranges of characters are equal, false otherwise
Throws
NullPointerException if string is null.

public String replace (CharSequence target, CharSequence replacement)

Since: API Level 1

Copies this string replacing occurrences of the specified target sequence with another sequence. The string is processed from the beginning to the end.

Parameters
target the sequence to replace.
replacement the replacement sequence.
Returns
  • the resulting string.
Throws
NullPointerException if target or replacement is null.

public String replace (char oldChar, char newChar)

Since: API Level 1

Copies this string replacing occurrences of the specified character with another character.

Parameters
oldChar the character to replace.
newChar the replacement character.
Returns
  • a new string with occurrences of oldChar replaced by newChar.

public String replaceAll (String regularExpression, String replacement)

Since: API Level 1

Replaces all matches for regularExpression within this string with the given replacement. See Pattern for regular expression syntax.

If the same regular expression is to be used for multiple operations, it may be more efficient to reuse a compiled Pattern.

Throws
if the syntax of the supplied regular expression is not valid.
NullPointerException if regularExpression == null
See Also

public String replaceFirst (String regularExpression, String replacement)

Since: API Level 1

Replaces the first match for regularExpression within this string with the given replacement. See Pattern for regular expression syntax.

If the same regular expression is to be used for multiple operations, it may be more efficient to reuse a compiled Pattern.

Throws
if the syntax of the supplied regular expression is not valid.
NullPointerException if regularExpression == null
See Also

public String[] split (String regularExpression)

Since: API Level 1

Splits this string using the supplied regularExpression. Equivalent to split(regularExpression, 0). See split(CharSequence, int) for an explanation of limit. See Pattern for regular expression syntax.

If the same regular expression is to be used for multiple operations, it may be more efficient to reuse a compiled Pattern.

Throws
NullPointerException if regularExpression == null
if the syntax of the supplied regular expression is not valid.
See Also

public String[] split (String regularExpression, int limit)

Since: API Level 1

Splits this string using the supplied regularExpression. See split(CharSequence, int) for an explanation of limit. See Pattern for regular expression syntax.

If the same regular expression is to be used for multiple operations, it may be more efficient to reuse a compiled Pattern.

Throws
NullPointerException if regularExpression == null
if the syntax of the supplied regular expression is not valid.

public boolean startsWith (String prefix)

Since: API Level 1

Compares the specified string to this string to determine if the specified string is a prefix.

Parameters
prefix the string to look for.
Returns
  • true if the specified string is a prefix of this string, false otherwise
Throws
NullPointerException if prefix is null.

public boolean startsWith (String prefix, int start)

Since: API Level 1

Compares the specified string to this string, starting at the specified offset, to determine if the specified string is a prefix.

Parameters
prefix the string to look for.
start the starting offset.
Returns
  • true if the specified string occurs in this string at the specified offset, false otherwise.
Throws
NullPointerException if prefix is null.

public CharSequence subSequence (int start, int end)

Since: API Level 1

Has the same result as the substring function, but is present so that string may implement the CharSequence interface.

Parameters
start the offset the first character.
end the offset of one past the last character to include.
Returns
  • the subsequence requested.
Throws
IndexOutOfBoundsException if start < 0, end < 0, start > end or end > length().
See Also

public String substring (int start)

Since: API Level 1

Returns a string containing a suffix of this string. The returned string shares this string's backing array.

Parameters
start the offset of the first character.
Returns
  • a new string containing the characters from start to the end of the string.
Throws
IndexOutOfBoundsException if start < 0 or start > length().

public String substring (int start, int end)

Since: API Level 1

Returns a string containing a subsequence of characters from this string. The returned string shares this string's backing array.

Parameters
start the offset of the first character.
end the offset one past the last character.
Returns
  • a new string containing the characters from start to end - 1
Throws
IndexOutOfBoundsException if start < 0, start > end or end > length().

public char[] toCharArray ()

Since: API Level 1

Copies the characters in this string to a character array.

Returns
  • a character array containing the characters of this string.

public String toLowerCase (Locale locale)

Since: API Level 1

Converts this string to lowercase, using the rules of locale.

Most case mappings are unaffected by the language of a Locale. Exceptions include dotted and dotless I in Azeri and Turkish locales, and dotted and dotless I and J in Lithuanian locales. On the other hand, it isn't necessary to provide a Greek locale to get correct case mapping of Greek characters: any locale will do.

See http://www.unicode.org/Public/UNIDATA/SpecialCasing.txt for full details of context- and language-specific special cases.

Returns
  • a new lowercase string, or this if it's already all-lowercase.

public String toLowerCase ()

Since: API Level 1

Converts this string to lowercase, using the rules of the user's default locale. See "Be wary of the default locale".

Returns
  • a new lowercase string, or this if it's already all-lowercase.

public String toString ()

Since: API Level 1

Returns this string.

Returns
  • this string.

public String toUpperCase (Locale locale)

Since: API Level 1

Converts this this string to uppercase, using the rules of locale.

Most case mappings are unaffected by the language of a Locale. Exceptions include dotted and dotless I in Azeri and Turkish locales, and dotted and dotless I and J in Lithuanian locales. On the other hand, it isn't necessary to provide a Greek locale to get correct case mapping of Greek characters: any locale will do.

See http://www.unicode.org/Public/UNIDATA/SpecialCasing.txt for full details of context- and language-specific special cases.

Returns
  • a new uppercase string, or this if it's already all-uppercase.

public String toUpperCase ()

Since: API Level 1

Converts this this string to uppercase, using the rules of the user's default locale. See "Be wary of the default locale".

Returns
  • a new uppercase string, or this if it's already all-uppercase.

public String trim ()

Since: API Level 1

Copies this string removing white space characters from the beginning and end of the string.

Returns
  • a new string with characters <= \\u0020 removed from the beginning and the end.

public static String valueOf (long value)

Since: API Level 1

Converts the specified long to its string representation.

Parameters
value the long.
Returns
  • the long converted to a string.

public static String valueOf (Object value)

Since: API Level 1

Converts the specified object to its string representation. If the object is null return the string "null", otherwise use toString() to get the string representation.

Parameters
value the object.
Returns
  • the object converted to a string, or the string "null".

public static String valueOf (char[] data)

Since: API Level 1

Creates a new string containing the characters in the specified character array. Modifying the character array after creating the string has no effect on the string.

Parameters
data the array of characters.
Returns
  • the new string.
Throws
NullPointerException if data is null.

public static String valueOf (double value)

Since: API Level 1

Converts the specified double to its string representation.

Parameters
value the double.
Returns
  • the double converted to a string.

public static String valueOf (int value)

Since: API Level 1

Converts the specified integer to its string representation.

Parameters
value the integer.
Returns
  • the integer converted to a string.

public static String valueOf (float value)

Since: API Level 1

Converts the specified float to its string representation.

Parameters
value the float.
Returns
  • the float converted to a string.

public static String valueOf (char[] data, int start, int length)

Since: API Level 1

Creates a new string containing the specified characters in the character array. Modifying the character array after creating the string has no effect on the string.

Parameters
data the array of characters.
start the starting offset in the character array.
length the number of characters to use.
Returns
  • the new string.
Throws
IndexOutOfBoundsException if length < 0, start < 0 or start + length > data.length
NullPointerException if data is null.

public static String valueOf (boolean value)

Since: API Level 1

Converts the specified boolean to its string representation. When the boolean is true return "true", otherwise return "false".

Parameters
value the boolean.
Returns
  • the boolean converted to a string.

public static String valueOf (char value)

Since: API Level 1

Converts the specified character to its string representation.

Parameters
value the character.
Returns
  • the character converted to a string.