java.lang
クラス String

java.lang.Object
  java.lang.String

public final class String
extends Object

文字列を表すクラスです。 Java 言語によるソースコード内の"abc"などの文字列リテラルは全てこのオブジェクトとして表現されます。

このため、例えば

     String s = "abc";

という記述はコンパイラによって

     char[] c = { 'a', 'b', 'c' };
     String s = new String(c);

という処理と等価な内容に展開されます。

文字列は定数であり、値の作成後に内容を変更することはできません。 変更を伴う文字列処理は StringBuffer クラスによって行います。

String クラスには文字列の比較、パターンテスト、検索や文字列の一部抽出した内容を持つ新たなオブジェクトの生成、大文字小文字間変換の変換を行った新たなオブジェクトの生成などを行うメソッドが用意されています。

Java 言語では、文字列の連結を行う + 演算子および文字列以外のオブジェクトを文字列へ変換する特別なサポートを行います。 文字列の連結は StringBuffer クラスと、同クラスの append メソッドを使用したコードに展開されます。 文字列以外のオブジェクトを文字列へ変換する際には、Object クラスから各クラスが継承した toString メソッドを使用するように展開します。 詳しくは関連する言語仕様書に記述されています。

String

public String()

保持する文字シーケンスが空のオブジェクトを生成します。

String

public String(String value)

渡された文字列のコピーを保持するオブジェクトを生成します。 コピーを作成するため、元の文字列と新たなオブジェクトの間にはお互いに何ら影響を与えることはありません。

パラメータ:

value - コピーする文字列を渡します。

例外:

NullPointerException - value が null の場合に throw します。

String

public String(char[] value)

渡された char 配列を文字列とするオブジェクトを生成します。 内容のコピーをオブジェクト内に持つため、コピー元の配列が変更されても文字列に影響を与えることはありません。

パラメータ:

value - 文字列を構成するための char 配列を渡します。

例外:

NullPointerException - value が null の場合に throw します。

String

public String(char[] value,
              int offset,
              int count)

渡された char 配列の一部を使用し、それを文字列とオブジェクトを生成します。 コンストラクタはパラメータの offset から count 文字分をオブジェクトに設定します。 内容のコピーをオブジェクト内に持つため、コピー元の配列が変更されても文字列に影響を与えることはありません。

パラメータ:

value - 文字列を構成するための char 配列を渡します。

offset - char 配列から文字の取り出しを開始するオフセットを渡します。

count - char 配列から取り出す文字数を渡します。

例外:

IndexOutOfBoundsException - offset および count が char 配列の範囲外を指す場合に throw します。

NullPointerException - value が null の場合に throw します。

String

public String(byte[] value,
              int offset,
              int count,
              String enc)
       throws UnsupportedEncodingException

渡された byte 配列の一部を指定された文字エンコーディングで Unicode に変換し、それを文字列とするオブジェクトを生成します。 内容のコピーをオブジェクト内に持つため、コピー元の配列が変更されても文字列に影響を与えることはありません。

パラメータ:

value - 文字列へ変換する byte 配列を渡します。

offset - 変換を開始する byte 配列内のオフセットを渡します。

count - 変換する byte 配列の長さを渡します。

enc - 変換に使用する文字エンコーディングを渡します。

例外:

IndexOutOfBoundsException - offset および count が char 配列の範囲外を指す場合に throw します。

NullPointerException - value が null の場合に throw します。

UnsupportedEncodingException - 指定された文字エンコーディングをサポートしていない場合に throw します。

String

public String(byte[] value,
              String enc)
       throws UnsupportedEncodingException

渡された byte 配列を指定された文字エンコーディングで Unicode に変換し、それを文字列とするオブジェクトを生成します。 内容のコピーをオブジェクト内に持つため、コピー元の配列が変更されても文字列に影響を与えることはありません。

パラメータ:

value - 文字列へ変換する byte 配列を渡します。

enc - 変換に使用する文字エンコーディングを渡します。

例外:

NullPointerException - value が null の場合に throw します。

UnsupportedEncodingException - 指定された文字エンコーディングをサポートしていない場合に throw します。

String

public String(byte[] value,
              int offset,
              int count)

渡された byte 配列の一部をデフォルトの文字エンコーディングで Unicode に変換し、それを文字列とするオブジェクトを生成します。 内容のコピーをオブジェクト内に持つため、コピー元の配列が変更されても文字列に影響を与えることはありません。

Java2 Platform, Micro Edition ではデフォルトの文字エンコーディングがシステムプロパティに登録されています。 System クラスの System.getProperty(java.lang.String) メソッドに対してプロパティ名 microedition.encoding の値を取り出すとデフォルトの文字エンコーディングが文字列で取得できます。

パラメータ:

value - 文字列へ変換する byte 配列を渡します。

offset - 変換を開始する byte 配列内のオフセットを渡します。

count - 変換する byte 配列の長さを渡します。

例外:

IndexOutOfBoundsException - offset および count が char 配列の範囲外を指す場合に throw します。

NullPointerException - value が null の場合に throw します。

String

public String(byte[] value)

渡された byte 配列をデフォルトの文字エンコーディングで Unicode に変換し、それを文字列とするオブジェクトを生成します。 内容のコピーをオブジェクト内に持つため、コピー元の配列が変更されても文字列に影響を与えることはありません。

Java2 Platform, Micro Edition ではデフォルトの文字エンコーディングがシステムプロパティに登録されています。 System クラスの System.getProperty(java.lang.String) メソッドに対してプロパティ名 microedition.encoding の値を取り出すとデフォルトの文字エンコーディングが文字列で取得できます。

パラメータ:

value - 文字列へ変換する byte 配列を渡します。

例外:

NullPointerException - value が null の場合に throw します。

String

public String(StringBuffer sb)

渡された StringBuffer クラスに保持されている文字列をコピーしたオブジェクトを生成します。 内容のコピーをオブジェクト内に持つため、コピー元の StringBuffer オブジェクトに変化が生じても文字列に影響を与えることはありません。

パラメータ:

sb - 文字列へコピーする StringBuffer オブジェクトを渡します。

例外:

NullPointerException - sb が null の場合に throw します。

length

public int length()

文字列の長さを返します。 文字列の長さは文字数と等しくなります。

戻り値:

文字列の長さを返します。

charAt

public char charAt(int index)

文字列の中の指定された位置の文字を返します。 位置は 0 〜 length() - 1 までの間で指定します。 配列の指定と同様に 0 が最初の文字となります。

パラメータ:

index - 取り出す文字の位置を渡します。

戻り値:

指定された位置の文字を返します。

例外:

IndexOutOfBoundsException - パラメータ index が負数あるいは範囲外の場合に throw します。

getChars

public void getChars(int srcBegin,
                     int srcEnd,
                     char[] dst,
                     int dstBegin)

文字列の中の指定された一部分を char 配列へコピーします。 開始位置 srcBegin で指定された位置から終了位置 srcEnd - 1 までの内容をコピー先の char 配列 dst の dstBegin からの位置へコピーします。

配列中の位置を指定する srcBegin、srcEnd、dstBegin が不正な場合は IndexOutOfBoundsException を throw します。 不正と評価されるのは以下の場合です。

• srcBegin あるいは dstBegin が負数の場合。
• srcEnd が文字列の長さを超えている場合。
• dstBegin + (srcEnd - srcBegin) > dst.length となる場合。

パラメータ:

srcBegin - 文字列の中からコピーを開始する位置を渡します。

srcEnd - 文字列の中でコピーを終了する位置 + 1 を渡します。

dst - コピー先の char 配列を渡します。

dstBegin - char 配列内のコピー開始位置を渡します。

例外:

IndexOutOfBoundsException - 配列中の位置を示すパラメータが不正な場合に throw します。

NullPointerException - dst が null の場合に throw します。

getBytes

public byte[] getBytes(String enc)
                throws UnsupportedEncodingException

文字列を指定された文字列エンコーディングで byte 配列へ変換し、その結果を返します。

パラメータ:

enc - 使用するエンコーディング名を渡します。

戻り値:

変換した結果の byte 配列を返します。

例外:

UnsupportedEncodingException - 指定された文字エンコーディングをサポートしていない場合に throw します。

getBytes

public byte[] getBytes()

文字列をデフォルトの文字エンコーディングで byte 配列へ変換し、その結果を返します。

Java2 Platform, Micro Edition ではデフォルトの文字エンコーディングがシステムプロパティに登録されています。 System クラスの System.getProperty(java.lang.String) メソッドに対してプロパティ名 microedition.encoding の値を取り出すとデフォルトの文字エンコーディングが文字列で取得できます。

戻り値:

変換した結果の byte 配列を返します。

equals

public boolean equals(Object obj)

渡されたオブジェクトとインスタンスを比較します。 渡されたオブジェクトが String クラスであり、保持している文字列が同等である場合に true を返します。

オーバーライド:

クラス Object 内の equals

パラメータ:

obj - 比較対象のオブジェクトを渡します。

戻り値:

比較対象のオブジェクトと等しい場合に true、等しくない場合に false を返します。

関連項目:

compareTo(String)

compareTo

public int compareTo(String target)

渡された文字列と自分自身の文字列を比較し、その結果が大きいか、小さいかまたは等しいかを返します。 大小の判定は、

• 文字コードが大きいか小さいか。
• 文字数が大きいか小さいか。

という２つの条件で比較します。

最初に文字コードを先頭から１文字ずつ比較します。この結果、最初に異なる文字が検出された位置 (index) を、

     this.charAt(index) - target.charAt(index);

として計算した Unicode における文字コードの差を戻り値として返します。 どちらかの文字列の終了位置までの文字コードが等しい場合、

     this.length() - target.length();

で得られる長さの差が戻り値として返されます。

パラメータ:

target - 比較対象の文字列を渡します。

戻り値:

比較対象の文字列がこの文字列と等しい場合は 0 を、対象文字列がこの文字列よりも小さい場合はマイナス値が、逆に大きい場合はプラス値を返します。

例外:

NullPointerException - target が null の場合に throw します。

regionMatches

public boolean regionMatches(boolean type,
                             int moffset,
                             String target,
                             int toffset,
                             int len)

渡された文字列とこの文字列の一部を比較し、その結果が一致するかどうかを返します。 この際、大文字と小文字を同一視するか否かを指定することができます。

指定範囲の文字列が一致しないと判定されるのは、

• moffset あるいは toffset が負数の場合。
• moffset + len がこの文字列長よりも大きい場合。
• toffset + len が比較対象の文字列長よりも大きい場合。
• 比較開始位置から len 文字までの間に、
  • type が true の場合、Character.toLowerCase(char) および Character.toUpperCase(char) を通して比較した際に等しくない文字が存在した場合。
  • type が false の場合、一致しない文字コードが存在した場合。
  のいずれかの条件が成立した場合。

以上の条件のいずれかが成立する場合です。

パラメータ:

type - 比較時に大文字と小文字を同一視する場合は true を、そうでない場合は false を渡します。

moffset - この文字列の比較開始位置を渡します。

target - 比較対象の文字列を渡します。

toffset - 比較対象の文字列の比較開始位置を渡します。

len - 比較する文字数を指定します。

戻り値:

一致すると判定した場合は true を、そうでなければ false を返します。

startsWith

public boolean startsWith(String target,
                          int index)

この文字列内の指定位置からの文字列が、渡された文字列で始まるかどうかを判定します。 このメソッドの呼び出しは、

     this.substring(index).startsWith(target);

と記述するのと等しい結果を返します。

パラメータ:

target - 比較対象の文字列を渡します。

index - この文字列内の比較開始位置を渡します。

戻り値:

一致する場合は true を、一致しない場合は false を返します。

例外:

NullPointerException - target が null の場合に throw します。

startsWith

public boolean startsWith(String target)

この文字列が渡された文字列で開始するかどうかを判定します。 渡された文字列で開始する場合は true を、そうでない場合は false を返します。 渡された文字列が空の場合あるいは equals(java.lang.Object) の結果が true となる場合も true と判定します。

パラメータ:

target - 比較対象の文字列を渡します。

戻り値:

渡された文字列で開始する場合は true を、そうでない場合は false を返します。

例外:

NullPointerException - target が null の場合に throw します。

endsWith

public boolean endsWith(String target)

この文字列が渡された文字列で終了するかどうかを判定します。 渡された文字列で終了する場合は true を、そうでない場合は false を返します。 渡された文字列が空の場合あるいは equals(java.lang.Object) の結果が true となる場合も true と判定します。

パラメータ:

target - 比較対象の文字列を渡します。

戻り値:

渡された文字列で終了する場合は true を、そうでない場合は false を返します。

例外:

NullPointerException - target が null の場合に throw します。

hashCode

public int hashCode()

この文字列に対応するハッシュコードを返します。

文字列のハッシュコードは文字列に含まれる文字コードを元に、以下のようなロジックで計算します。

     int r = 0;
     int n = this.length();
     for(int i = 0; i < n; i++) {
         r += this.charAt[i] * 31 ^ (n - i - 1);
     }

この処理後の変数 r の値がハッシュコードになります。

オーバーライド:

クラス Object 内の hashCode

戻り値:

この文字列に対応するハッシュコードを返します。

indexOf

public int indexOf(int ch)

この文字列に渡された文字が存在する位置を返します。 対応する文字が文字列に存在しない場合は -1 を返します。 複数対応する文字がある場合は、最も先頭に近い文字の位置を返します。

例えば、

     "abcdefghijklmn".indexOf('d');

とした場合は 3 を返します。また、

     "a0a1a2a3a4a5a6".indexOf('a');

とした場合は 0 を返します。

パラメータ:

ch - 検索する文字を渡します。

戻り値:

対応する文字が存在する場合はその位置、存在しない場合は -1 を返します。

indexOf

public int indexOf(int ch,
                   int index)

この文字列の指定位置以降に、渡された文字が存在する位置を返します。 対応する文字が文字列に存在しない場合は -1 を返します。 複数対応する文字がある場合は、指定位置以降で最も先頭に近い文字の位置を返します。 検索位置として負数を渡した場合、0 が渡されたものとみなして処理を行います。

例えば、

     "abcdefabcdef".indexOf('d', 5);

とした場合は 9 を返します。また、

     "a0a1a2a3a4a5a6".indexOf('a', 5);

とした場合は 6 を返します。

パラメータ:

ch - 検索する文字を渡します。

index - 検索を開始する位置を渡します。

戻り値:

対応する文字が存在する場合はその位置、存在しない場合は -1 を返します。

lastIndexOf

public int lastIndexOf(int ch)

この文字列に渡された文字が最後に存在する位置（最も末尾に近い位置）を返します。 対応する文字が文字列に存在しない場合は -1 を返します。 複数対応する文字がある場合は、最も末尾に近い文字の位置を返します。

例えば、

     "abcdefghijklmn".lastIndexOf('d');

とした場合は 3 を返します。また、

     "a0a1a2a3a4a5a6".lastIndexOf('a');

とした場合は 12 を返します。

パラメータ:

ch - 検索する文字を渡します。

戻り値:

対応する文字が存在する場合はその位置、存在しない場合は -1 を返します。

lastIndexOf

public int lastIndexOf(int ch,
                       int index)

この文字列の指定された位置以前に、渡された文字が最後に存在する位置（指定された位置に最も近い位置）を返します。 対応する文字が文字列に存在しない場合は -1 を返します。 複数対応する文字がある場合は、指定された位置に最も近い位置を返します。

例えば、

     "abcdefabcdef".lastIndexOf('d', 5);

とした場合は 3 を返します。また、

     "a0a1a2a3a4a5a6".lastIndexOf('a', 5);

とした場合は 4 を返します。

パラメータ:

ch - 検索する文字を渡します。

戻り値:

対応する文字が存在する場合はその位置、存在しない場合は -1 を返します。

indexOf

public int indexOf(String target)

この文字列に渡された文字列が始めて現れる位置を返します。 渡された文字列がこの文字列に存在しない場合は -1 を返します。 文字列の一致不一致の判定は startsWith(java.lang.String, int) メソッドの判定に準じます。

パラメータ:

target - 検索する文字列を渡します。

戻り値:

対応する文字列が存在する場合はその位置、存在しない場合は -1 を返します。

例外:

NullPointerException - target が null の場合に throw します。

indexOf

public int indexOf(String target,
                   int index)

この文字列の指定された位置以降に、渡された文字列が始めて現れる位置を返します。 渡された文字列がこの文字列の指定位置以降に存在しない場合は -1 を返します。 文字列の一致不一致の判定は startsWith(java.lang.String, int) メソッドの判定に準じます。

パラメータ:

target - 検索する文字列を渡します。

index - 検索を開始するこの文字列内の位置を渡します。

戻り値:

対応する文字列が存在する場合はその位置、存在しない場合は -1 を返します。

例外:

NullPointerException - target が null の場合に throw します。

substring

public String substring(int index)

この文字列の指定された位置以降の内容を持つ新たな文字列を返します。 新たな文字列は指定された位置の文字を含む文字列にとなります。

例えば、

     "0123456789".substring(5);

の結果は"56789"を含む新たな文字列となります。

パラメータ:

index - 新たな文字列へ切り出す位置を渡します。

戻り値:

この文字列の指定位置以降の内容を持つ新たな文字列を返します。

例外:

IndexOutOfBoundsException - index が負数の場合あるいはこの文字列の長さよりも大きい場合に throw します。

substring

public String substring(int start,
                        int end)

この文字列の開始指定位置以降、終了指定位置までの内容を持つ新たな文字列を返します。 新たな文字列は指定された開始指定位置の文字を含み、なおかつ終了指定位置の手前の文字までの文字列となります。

例えば、

     "0123456789".substring(3, 8);

の結果は"34567"を含む新たな文字列となります。

パラメータ:

start - この文字列から新たな文字列へ切り出す開始位置を渡します。

end - この文字列から新たな文字列へ切り出す終了位置の次の位置を渡します。

戻り値:

この文字列のから指定された部分を持つ、新たな文字列を返します。

例外:

IndexOutOfBoundsException - 開始位置 start が負数の場合あるいは開始位置 start よりも終了位置 end が小さい場合および終了位置 end がこの文字列の長さよりも大きい場合に throw します。

concat

public String concat(String target)

この文字列と渡された文字列の内容を結合した、新たな文字列を返します。 ただし、渡された文字列が空の場合はこの文字列への参照がそのまま返されます。

パラメータ:

target - 結合する文字列を渡します。

戻り値:

この文字列と渡された文字列を結合した新たな文字列を返します。

replace

public String replace(char src,
                      char dest)

この文字列の中の指定された特定の文字を新たな文字に置き換えた、新たな文字列を返します。 ただし、置き換える対象の文字 src に対応する文字が無い場合はこの文字列への参照がそのまま返されます。

パラメータ:

src - 置き換える対象の文字を渡します。

dest - 置き換え後の文字を渡します。

戻り値:

置き換え後の結果を持つ、新たな文字列を返します。

toLowerCase

public String toLowerCase()

この文字列に含まれる文字を全て小文字に変換した、新たな文字列を返します（おそらく変更対象となる文字が無い場合はそのままの文字列への参照を返すでしょう）。

戻り値:

この文字列含まれる文字が全て小文字に変換された新たな文字列を返します。

toUpperCase

public String toUpperCase()

この文字列に含まれる文字を全て大文字にに変換した、新たな文字列を返します（おそらく変更対象となる文字が無い場合はそのままの文字列への参照を返すでしょう）。

戻り値:

この文字列含まれる文字が全て大文字に変換された新たな文字列を返します。

trim

public String trim()

この文字列の前後に含まれる制御コードを削除した、新たな文字列を返します。

制御コードは \u0020 未満のコードの文字を指します。 この文字列の両端が対象となる制御コードではない場合、この文字列への参照をそのまま返します。 また、この文字列に \u0020 以上のコードを持つ文字が存在しない場合は空の文字列を新たに生成して返します。

このメソッドによる削除対象には ' '(\u0020) 自体も含まれるため、前後の空白を削除するためにも使用することができます。 ただし、制御コードが含まれる場合はそれも削除対象となります。

戻り値:

前後の制御コードを削除した、新たな文字列を返します。

toString

public String toString()

この文字列自身をそのまま返します。 つまり、return this;が行われます。

オーバーライド:

クラス Object 内の toString

戻り値:

この文字列自身を返します。

toCharArray

public char[] toCharArray()

この文字列の内容を、新たに作成した char 配列へコピーして返します。

戻り値:

char 配列へ展開した文字列の内容を返します。

valueOf

public static String valueOf(Object obj)

渡されたオブジェクトの文字列表現を返します。 obj が null の場合は"null"を、それ以外の場合は obj.toString() の結果を返します。

パラメータ:

obj - 文字列表現を得たいオブジェクトを渡します。

戻り値:

渡されたオブジェクトの文字列表現を返します。

関連項目:

Object.toString()

valueOf

public static String valueOf(char[] value)

渡された char 配列の内容を持つ、新たな文字列を返します。 配列の内容は文字列内にコピーして保持されるため、コピー元の配列の内容変更によって新たなオブジェクトに影響を与えることはありません。

パラメータ:

value - 新たな文字列へ設定する char 配列を渡します。

戻り値:

渡された char 配列の内容を持った新たな文字列を返します。

valueOf

public static String valueOf(char[] value,
                             int offset,
                             int count)

渡された char 配列内容の指定部分の内容を持つ、新たな文字列を返します。 新たな文字列は char 配列の offset 位置から count 分の内容を持ちます。

配列の内容は文字列内にコピーして保持されるため、コピー元の配列の内容変更によって新たなオブジェクトに影響を与えることはありません。

パラメータ:

value - 新たな文字列へ設定する内容を持つ char 配列を渡します。

offset - 文字列へ設定する char 配列の内容開始位置を渡します。

count - 文字列へ設定する文字数を渡します。

戻り値:

渡された char 配列の指定部分の内容を持った新たな文字列を返します。

例外:

NullPointerException - value が null の場合に throw します。

IndexOutOfBoundsException - 文字数 count が負数の場合あるいは開始位置 offset と文字数 count を足した結果が char 配列 value.length よりも大きい場合に throw します。

valueOf

public static String valueOf(boolean b)

渡された boolean 値の文字列表現を返します。 このメソッドの実行は

     b ? "true" : "false";

と記述するのと等しい結果を返します。

パラメータ:

b - 文字列表現に変換する boolean 値を渡します。

戻り値:

b が true の場合"true"が、false の場合"false"を返します。

valueOf

public static String valueOf(char ch)

渡された char 値の文字列表現を返します。

パラメータ:

ch - 文字列表現に変換する char 値を渡します。

戻り値:

渡された文字 ch を保持した新たな文字列を返します。

valueOf

public static String valueOf(int value)

渡された int 値の文字列表現を返します。 このメソッドが返す内容は、Integer クラスの toString メソッドを呼び出して得られるのと同様の内容です。

パラメータ:

value - 文字列表現に変換する int 値を渡します。

戻り値:

パラメータ value を文字列表現した新たな文字列を返します。

関連項目:

Integer.toString(int)

valueOf

public static String valueOf(long value)

渡された long 値の文字列表現を返します。 このメソッドが返す内容は、Long クラスの toString メソッドを呼び出して得られるのと同様の内容です。

パラメータ:

value - 文字列表現に変換する long 値を渡します。

戻り値:

パラメータ value を文字列表現した新たな文字列を返します。

関連項目:

Long.toString(long)