DthingApi: java.lang.String Class Reference

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 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: StringBuffer; StringBuilder; Charset

Since: 1.0

Constructor & Destructor Documentation

◆ String() [1/9]

java.lang.String.String ( )

inline

Creates an empty string.

◆ String() [2/9]

java.lang.String.String ( byte [] data )

inline

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

◆ String() [3/9]

java.lang.String.String	(	byte []	data,
		int	offset,
		int	byteCount
	)

inline

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

Exceptions

NullPointerException	if data == null .
IndexOutOfBoundsException	if byteCount < 0 \|\| offset < 0 \|\| offset + byteCount > data.length .

◆ String() [4/9]

java.lang.String.String	(	byte []	data,
		int	offset,
		int	byteCount,
		String	charsetName
	)		throws UnsupportedEncodingException

inline

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 java.nio.charset.CharsetDecoder for more control.

Exceptions

NullPointerException	if data == null .
IndexOutOfBoundsException	if byteCount < 0 \|\| offset < 0 \|\| offset + byteCount > data.length .
UnsupportedEncodingException	if the named charset is not supported.

◆ String() [5/9]

java.lang.String.String	(	byte []	data,
		String	charsetName
	)		throws UnsupportedEncodingException

inline

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 java.nio.charset.CharsetDecoder for more control.

Exceptions

NullPointerException	if data == null .
UnsupportedEncodingException	if charsetName is not supported.

◆ String() [6/9]

java.lang.String.String ( char [] data )

inline

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.

Exceptions

if

data == null

◆ String() [7/9]

java.lang.String.String	(	char []	data,
		int	offset,
		int	charCount
	)

inline

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.

Exceptions

NullPointerException	if data == null .
IndexOutOfBoundsException	if charCount < 0 \|\| offset < 0 \|\| offset + charCount > data.length

◆ String() [8/9]

java.lang.String.String ( String toCopy )

inline

Constructs a new string with the same sequence of characters as

toCopy

. The returned string's backing array is no larger than necessary.

◆ String() [9/9]

java.lang.String.String ( StringBuffer stringBuffer )

inline

Creates a

from the contents of the specified

StringBuffer

.

Member Function Documentation

◆ charAt()

char java.lang.String.charAt ( int index )

inline

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.

Exceptions

if

index < 0

or

index >= length()

.

Implements java.lang.CharSequence.

◆ compareTo()

int java.lang.String.compareTo ( String string )

inline

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.

Exceptions

if

string

is

null

.

◆ compareToIgnoreCase()

int java.lang.String.compareToIgnoreCase ( String string )

inline

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.

Exceptions

if

string

is

null

.

◆ concat()

String java.lang.String.concat ( String string )

inline

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.

◆ contains()

boolean java.lang.String.contains ( CharSequence cs )

inline

Determines if this

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
.

Since: 1.5

◆ contentEquals() [1/2]

boolean java.lang.String.contentEquals ( StringBuffer strbuf )

inline

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.

Exceptions

if

strbuf

is

null

.

Since: 1.4

◆ contentEquals() [2/2]

boolean java.lang.String.contentEquals ( CharSequence cs )

inline

Compares a

CharSequence

to this

to determine if their contents are equal.

Parameters

cs	the character sequence to compare to.

Returns: true
if equal, otherwise
false

Since: 1.5

◆ copyValueOf() [1/2]

static String java.lang.String.copyValueOf ( char [] data )

inlinestatic

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.

Exceptions

if

data

is

null

.

◆ copyValueOf() [2/2]

static String java.lang.String.copyValueOf	(	char []	data,
		int	start,
		int	length
	)

inlinestatic

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.

Exceptions

NullPointerException	if data is null .
IndexOutOfBoundsException	if length < 0, start < 0 or start + length > data.length .

◆ endsWith()

boolean java.lang.String.endsWith ( String suffix )

inline

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.

Exceptions

if

suffix

is

null

.

◆ equals()

boolean java.lang.String.equals ( Object object )

inline

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: #hashCode

◆ equalsIgnoreCase()

boolean java.lang.String.equalsIgnoreCase ( String string )

inline

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.

◆ getBytes() [1/2]

byte [] java.lang.String.getBytes ( )

inline

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.

◆ getBytes() [2/2]

byte [] java.lang.String.getBytes ( String charsetName ) throws UnsupportedEncodingException

inline

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 java.nio.charset.CharsetEncoder for more control.

Exceptions

UnsupportedEncodingException if the charset is not supported

◆ getChars()

void java.lang.String.getChars	(	int	start,
		int	end,
		char []	buffer,
		int	index
	)

inline

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.

Exceptions

NullPointerException	if buffer is null .
IndexOutOfBoundsException	if start < 0 , end > length() , start > end , index < 0 , end - start > buffer.length - index

◆ hashCode()

int java.lang.String.hashCode ( )

inline

Returns a hashcode for this string. The hashcode for a String object is computed as

s[0]*31^(n-1) + s[1]*31^(n-2) + ... + s[n-1]

using int arithmetic, where s[i] is the ith character of the string, n is the length of the string, and ^ indicates exponentiation. (The hash value of the empty string is zero.)

Returns: a hash code value for this object.

◆ indexOf() [1/4]

int java.lang.String.indexOf ( int c )

inline

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.

◆ indexOf() [2/4]

int java.lang.String.indexOf	(	int	c,
		int	start
	)

inline

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.

◆ indexOf() [3/4]

int java.lang.String.indexOf ( String string )

inline

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.

Exceptions

if

string

is

null

.

◆ indexOf() [4/4]

int java.lang.String.indexOf	(	String	subString,
		int	start
	)

inline

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.

Exceptions

if

subString

is

null

.

◆ intern()

native String java.lang.String.intern ( )

Returns an interned string equal to this string. The VM maintains an internal set of unique strings. All string literals found in loaded classes' constant pools are automatically interned. Manually-interned strings are only weakly referenced, so calling

intern

won't lead to unwanted retention.

Interning is typically used because it guarantees that for interned strings

a

and

b

,

a.equals(b)

can be simplified to

a == b

. (This is not true of non-interned strings.)

Many applications find it simpler and more convenient to use an explicit java.util.HashMap to implement their own pools.

◆ lastIndexOf() [1/4]

int java.lang.String.lastIndexOf ( int c )

inline

Returns the last index of the code point

c

, or -1. The search for the character starts at the end and moves towards the beginning of this string.

◆ lastIndexOf() [2/4]

int java.lang.String.lastIndexOf	(	int	c,
		int	start
	)

inline

Returns the last index of the code point

c

, or -1. The search for the character starts at offset

start

and moves towards the beginning of this string.

◆ lastIndexOf() [3/4]

int java.lang.String.lastIndexOf ( String string )

inline

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.

Exceptions

if

string

is

null

.

◆ lastIndexOf() [4/4]

int java.lang.String.lastIndexOf	(	String	subString,
		int	start
	)

inline

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.

Exceptions

if

subString

is

null

.

◆ length()

int java.lang.String.length ( )

inline

Returns the size of this string.

Returns: the number of characters in this string.

Implements java.lang.CharSequence.

◆ regionMatches() [1/2]

boolean java.lang.String.regionMatches	(	int	thisStart,
		String	string,
		int	start,
		int	length
	)

inline

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

Exceptions

if

string

is

null

.

◆ regionMatches() [2/2]

boolean java.lang.String.regionMatches	(	boolean	ignoreCase,
		int	thisStart,
		String	string,
		int	start,
		int	length
	)

inline

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.

Exceptions

if

string

is

null

.

◆ replace() [1/2]

String java.lang.String.replace	(	char	oldChar,
		char	newChar
	)

inline

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.

◆ replace() [2/2]

String java.lang.String.replace	(	CharSequence	target,
		CharSequence	replacement
	)

inline

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.

Exceptions

if

target

or

replacement

is

null

.

◆ startsWith() [1/2]

boolean java.lang.String.startsWith ( String prefix )

inline

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

Exceptions

if

prefix

is

null

.

◆ startsWith() [2/2]

boolean java.lang.String.startsWith	(	String	prefix,
		int	start
	)

inline

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.

Exceptions

if

prefix

is

null

.

◆ subSequence()

CharSequence java.lang.String.subSequence	(	int	start,
		int	end
	)

inline

Returns a

CharSequence

from the

start

index (inclusive) to the

end

index (exclusive) of this sequence.

Parameters

start	the start offset of the sub-sequence. It is inclusive, that is, the index of the first character that is included in the sub-sequence.
end	the end offset of the sub-sequence. It is exclusive, that is, the index of the first character after those that are included in the sub-sequence

Returns: the requested sub-sequence.

Exceptions

if

start < 0

,

end < 0

,

start > end

, or if

start

or

end

are greater than the length of this sequence.

Implements java.lang.CharSequence.

◆ substring() [1/2]

String java.lang.String.substring ( int start )

inline

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.

Exceptions

if

start < 0

or

start > length()

.

◆ substring() [2/2]

String java.lang.String.substring	(	int	start,
		int	end
	)

inline

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

Exceptions

if

start < 0

,

start > end

or

end >

length()

.

◆ toCharArray()

char [] java.lang.String.toCharArray ( )

inline

Copies the characters in this string to a character array.

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

◆ toLowerCase()

String java.lang.String.toLowerCase ( )

inline

Converts this string to lower case, using the rules of the user's default locale. See "<a href="../util/Locale.html::default_locale">Be wary of the default locale</a>".

Returns: a new lower case string, or
this
if it's already all lower case.

◆ toString()

String java.lang.String.toString ( )

inline

Returns this string.

Implements java.lang.CharSequence.

◆ toUpperCase()

String java.lang.String.toUpperCase ( )

inline

Converts this this string to upper case, using the rules of the user's default locale. See "<a href="../util/Locale.html::default_locale">Be wary of the default locale</a>".

Returns: a new upper case string, or
this
if it's already all upper case.

◆ trim()

String java.lang.String.trim ( )

inline

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.

◆ valueOf() [1/9]

static String java.lang.String.valueOf ( char [] data )

inlinestatic

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.

Exceptions