モジュール java.base

パッケージ java.nio.charset

クラスCharset

java.lang.Object

java.nio.charset.Charset

すべての実装されたインタフェース:

Comparable<Charset>

public abstract class Charset extends Object implements Comparable<Charset>

16ビットUnicode コード単位のシーケンスとバイト・シーケンス間の指定マップです。 このクラスには、デコーダやエンコーダを作成するメソッドや、文字セットに関連付けられたさまざまな名前を取得するメソッドを定義します。 このクラスのインスタンスは不変です。

また、このクラスには、ある文字セットがサポートされているかどうかのチェック、名前による文字セットのインスタンスの検索、および現在のJava仮想マシンでサポートされているすべての文字セットを記載したマップの構築をするための静的メソッドも定義されています。 新しい文字セットを追加する場合は、CharsetProviderクラスに定義されているサービス・プロバイダ・インタフェースを使用します。

このクラスで定義されているすべてのメソッドは、複数の並行スレッドで安全に使用できます。

文字セット名

文字セット名は、次の文字を含む文字列で表されます。

• 大文字'A'から'Z' ('\u0041'から'\u005a')、
• 小文字'a'から'z' ('\u0061'から'\u007a')、
• 数字'0'から'9' ('\u0030'から'\u0039')
• ダッシュ文字'-' ('\u002d', HYPHEN-MINUS)、
• プラス文字'+' ('\u002b', 「プラス記号」)、
• ピリオド文字'.' ('\u002e', FULL STOP)、
• コロン文字':' ('\u003a', COLON)および
• アンダースコア文字'_' ('\u005f', LOW LINE)。

文字セット名の最初の文字は、必ずアルファベットか数字になります。 空の文字列は正当な文字セット名として認識されません。 文字セット名ではアルファベットの大文字と小文字が区別されないので、2つの文字セット名を比較する際、大文字と小文字の違いは無視されます。 通常、文字セット名はRFC 2278: IANA Charset Registration Proceduresの規則に準拠します。

すべての文字セットには正規名があります。このほかに、1つ以上の別名が存在する場合もあります。 このクラスのnameメソッドは正規名を返します。 通常、正規名はアルファベットの大文字で記述されます。 aliasesメソッドは文字セットの別名を返します。

一部の文字セットには、以前のバージョンのJavaプラットフォームとの互換性のために定義された履歴名があります。 文字セット履歴名は、標準名またはその別名のいずれかです。 履歴名は、InputStreamReaderおよびOutputStreamWriterクラスのgetEncoding()メソッドによって返されます。

IANA Charset Registryに記載されている文字セットをJavaプラットフォームの実装がサポートする場合、その文字セットの正規名はレジストリ内の名前になります。 文字セットの多くはレジストリ内に複数の名前を持っています。この場合、レジストリは、いずれかの名前をMIME優先とします。 このように、文字セットが複数のレジストリ名を持っている場合、MIME優先名が正規名となり、その他のレジストリ名は有効な別名となります。 サポートされている文字セットがIANAレジストリにリストされていない場合、正規名は"X-"または"x-"のいずれかの文字列で始める必要があります。

IANA文字セット・レジストリの内容は、時間の経過とともに変化します。これに伴い、文字セットの正規名や別名も変化します。 互換性を確保する必要がある場合は、文字セットの別名を削除しないこと、文字セットの正規名が変わった場合は元の正規名を別名として追加することをお薦めします。

標準文字セット

Javaプラットフォームを実装するたびに、次の標準文字セットをサポートする必要があります。 他の文字セットがサポートされているかどうかを確認するには、実装のリリース・ドキュメントを参照してください。 そうしたオプションの文字セットの動作は実装ごとに異なる可能性があります。

標準文字セットの説明

Charset	説明
US-ASCII	7ビットASCII ISO646-US、別名Unicode文字セットのBasic Latinブロック
ISO-8859-1	ISOラテン・アルファベットNo. 1 ISO-LATIN-1
UTF-8	8ビットUCS変換形式
UTF-16BE	16ビットUCS変換形式、ビッグエンディアン・バイト順
UTF-16LE	16ビットUCS変換形式、リトルエンディアン・バイト順
UTF-16	16ビットUCS変換形式、オプションのバイト順マークによって識別されるバイト順
UTF-32BE	32ビットUCS変換フォーマット、ビッグ・エンディアン・バイト順
UTF-32LE	32ビットUCS変換フォーマット、リトル・エンディアン・バイト順
UTF-32	32ビットUCS変換形式、オプションのバイト順序マークで識別されるバイト順序

UTF-8文字セットは、RFC 2279で指定されます。この文字セットが基づく変換形式は、ISO 10646-1で指定され、「Unicode標準」でも説明されています。

UTF-16文字セットは、RFC 2781で指定されます。変換形式は、ISO 10646-1で指定され、「Unicode標準」でも説明されています。

UTF-32文字セットは、ISO 10646-1で指定されている変換形式に基づいており、「Unicode標準」でも説明されています。

UTF-16およびUTF-32文字セットでは、それぞれ16ビットおよび32ビットの数量が使用されるため、バイト順序の影響を受けます。 これらのエンコーディングでは、ストリームのバイト順序は、Unicode文字U+FEFFで表される初期「バイト順マーク」で示されます。 バイト順マークの扱いは次のとおりです。

• デコード時に、UTF-16BE, UTF-16LE, UTF-32BEおよびUTF-32LE文字セットは、最初のバイト順序マークをZERO-WIDTH NON-BREAKING SPACEとして解釈します。エンコーディング時には、バイト順序マークは書き込まれません。

• デコード時に、UTF-16およびUTF-32文字セットは、入力ストリームの先頭にあるバイト順序マークを解釈して、ストリームのバイト順序を示しますが、バイト順序マークがない場合はデフォルトでビッグ・エンディアンになります。エンコーディング時には、ビッグ・エンディアン・バイト順序を使用し、ビッグ・エンディアン・バイト順序マークを書き込みます。

どちらの場合も、入力シーケンスの最初の要素の後に出現したバイト順マークは省略されません。これは、ZERO-WIDTH NON-BREAKING SPACEが同じコードで表現されるからです。

Java仮想マシンのすべてのインスタンスにはデフォルトの文字セットがあります。これは、実装固有の方法で変更されないかぎり、UTF-8です。 詳細は、defaultCharset()を参照してください。

StandardCharsetsクラスは、標準文字セットのそれぞれを表す定数を定義します。

用語

このクラスの名前は、RFC 2278で使用されている用語に由来しています。 このドキュメント内で、文字セットは1つ以上のコード化文字集合と文字エンコーディング方式の組み合わせとして定義されています。 (この定義はわかりにくいため、文字セットをコード化文字集合の同義語として定義するソフトウェア・システムもあります。)

コード化文字セットは、抽象文字のセットと整数のセット間のマッピングを表します。 コード化文字集合の例として、US-ASCII、ISO 8859-1、JIS X 0201、Unicodeなどがあります。

一部の標準は、文字セットを対応する割当て番号がない抽象文字の集合として定義しています。 このような文字セットの例として、アルファベットがあります。 ただし、文字セットとコード化文字集合の微妙な区別が実際に行われることはほとんどありません。Java APIも含めて、文字セットはコード化文字集合の短縮形になっています。

文字エンコーディング方式は、1つ以上のコード化文字集合とオクテット(8ビット・バイト)シーケンス間のマッピングです。 文字エンコーディング方式の例として、UTF-8、UTF-16、ISO 2022、EUCなどがあります。 エンコーディング方式は通常、特定のコード化文字セットに関連付けられます。たとえば、UTF-8は、Unicodeのエンコーディング専用です。 エンコーディング方式の中には、複数のコード化文字集合に関連付けられるものもあります。たとえば、EUCを使えば、アジア地域のさまざまなコード化文字集合の文字をエンコードできます。

コード化文字集合と文字エンコーディング方式とが1対1に対応している場合、通常はそのコード化文字集合の名前にちなんだ文字セット名が付けられます。それ以外の場合は通常、エンコーディング方式(とサポートするコード化文字集合のロケール)にちなんだ名前が付けられます。 したがって、US-ASCIIはコード化された文字セットの名前とそれをエンコードする文字セットの両方であり、EUC-JPは、日本語のJIS X 0201、JIS X 0208、およびJIS X 0212コード化された文字セットをエンコードする文字セットの名前です。

Javaプログラミング言語のネイティブの文字エンコーディング方式は、UTF-16です。 したがって、Javaプラットフォーム内の各文字セットは、16ビットのUTF-16コード単位のシーケンス(つまり、文字のシーケンス)とバイト・シーケンスとの間のマッピングを定義します。

導入されたバージョン:

1.4

外部仕様

• 文字セット
• RFC 2278: IANA文字セット登録手順
• RFC 2279: UTF-8 (ISO 10646の変換形式)
• RFC 2781: UTF-16 (ISO 10646のエンコーディング)

関連項目:

• CharsetDecoder
• CharsetEncoder
• CharsetProvider
• Character

コンストラクタのサマリー

コンストラクタ

修飾子	コンストラクタ	説明
protected	Charset(String canonicalName, String[] aliases)	正規名と別名のセットを使って、新しい文字セットを初期化します。

メソッドのサマリー

修飾子と型	メソッド	説明
final Set<String>	aliases()	この文字セットの別名が含まれるセットを返します。
static SortedMap<String,Charset>	availableCharsets()	正規文字セット名からCharsetオブジェクトへのソートされたマップを構築します。
boolean	canEncode()	この文字セットがエンコーディングをサポートするかどうかを判断します。
final int	compareTo(Charset that)	この文字セットと別の文字セットを比較します。
abstract boolean	contains(Charset cs)	この文字セットに指定の文字セットが含まれているかどうかを判断します。
final CharBuffer	decode(ByteBuffer bb)	この文字セットで表現されたバイトをUnicode文字にデコードする簡易メソッドです。
static Charset	defaultCharset()	このJava仮想マシンのデフォルトの文字セットを返します。
String	displayName()	デフォルト・ロケールにおける、この文字セットの名前(人間が読める形式)を返します。
String	displayName(Locale locale)	指定ロケールにおけるこの文字セットの名前(人間が読める形式)を返します。
final ByteBuffer	encode(String str)	文字列をこの文字セットで表現されたバイトにエンコードする簡易メソッドです。
final ByteBuffer	encode(CharBuffer cb)	Unicode文字をこの文字セットで表現されたバイトにエンコードする簡易メソッドです。
final boolean	equals(Object ob)	このオブジェクトが別のオブジェクトと等価であるかどうかを判断します。
static Charset	forName(String charsetName)	指定された文字セットのCharsetオブジェクトを返します。
static Charset	forName(String charsetName, Charset fallback)	指定された文字セットのCharsetオブジェクトを返します。
final int	hashCode()	この文字セット用のハッシュ・コードを返します。
final boolean	isRegistered()	この文字セットがIANA Charset Registryに登録されているかどうかを判別します。
static boolean	isSupported(String charsetName)	指定された文字セットがサポートされているかどうかを判断します。
final String	name()	この文字セットの正規名を返します。
abstract CharsetDecoder	newDecoder()	この文字セットの新しいデコーダを構築します。
abstract CharsetEncoder	newEncoder()	この文字セットの新しいエンコーダを構築します。
final String	toString()	この文字セットを説明する文字列を返します。

クラスjava.lang.Objectで宣言されたメソッド

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

コンストラクタの詳細

Charset

protected Charset(String canonicalName, String[] aliases)

正規名と別名のセットを使って、新しい文字セットを初期化します。

パラメータ:

canonicalName - この文字セットの正規名

aliases - この文字セットの別名から成る配列(別名がない場合はnull)

例外:

IllegalCharsetNameException - 正規名または別名が不正である場合

メソッドの詳細

isSupported

public static boolean isSupported(String charsetName)

指定された文字セットがサポートされているかどうかを判断します。

パラメータ:

charsetName - 要求された文字セットの名前。正規名か別名

戻り値:

指定された文字セットのサポートが現在のJava仮想マシンで使用可能な場合のみ、true

例外:

IllegalCharsetNameException - 指定された文字セットが不正である場合

IllegalArgumentException - 指定されたcharsetNameがnullの場合

forName

public static Charset forName(String charsetName)

指定された文字セットのCharsetオブジェクトを返します。

パラメータ:

charsetName - 要求された文字セットの名前。正規名か別名

戻り値:

指定された文字セットのCharsetオブジェクト

例外:

IllegalCharsetNameException - 指定された文字セットが不正である場合

IllegalArgumentException - 指定されたcharsetNameがnullの場合

UnsupportedCharsetException - 指定された文字セットが現在のJava仮想マシンでは利用できない場合

forName

public static Charset forName(String charsetName, Charset fallback)

指定された文字セットのCharsetオブジェクトを返します。 指定された文字セット用の文字セット・オブジェクトが使用できない場合、またはcharsetNameが有効な文字セット名でない場合は、fallbackが返されます。

パラメータ:

charsetName - 要求された文字セットの名前。正規名か別名

fallback - 指定された文字セット用の文字セット・オブジェクトが使用できないか、charsetNameが有効な文字セット名でない場合の代替文字セット。 nullも可

戻り値:

指定された文字セット用の文字セット・オブジェクト、または指定した文字セット用の文字セット・オブジェクトが使用できない場合、またはcharsetNameが有効な文字セット名でない場合のfallback

例外:

IllegalArgumentException - 指定されたcharsetNameがnullの場合

導入されたバージョン:

18

availableCharsets

public static SortedMap<String,Charset> availableCharsets()

正規文字セット名からCharsetオブジェクトへのソートされたマップを構築します。

このメソッドから返されるマップには、現在のJava仮想マシンでサポートされている各文字セットごとにエントリが1つずつ含まれます。 サポートされている文字セットのなかに同じ正規名を持つものが複数存在した場合、結果として得られるマップにはそのうちの1つだけが含まれます。ただし、どちらの文字セットが含まれるかは未定です。

このメソッドの呼び出しや、その結果として得られるマップを利用する際には、時間のかかるディスク入出力操作やネットワーク入出力操作が発生する可能性があります。 このメソッドは、ユーザーに文字セットを選択させる場合など、使用可能なすべての文字セットを列挙する必要があるアプリケーション用として提供されています。 forNameメソッドでは、このメソッドを使用せずに、効率の良い増分検索アルゴリズムを採用しています。

新しい文字セット・プロバイダが現在のJava仮想マシンに対して動的に利用可能になる場合、このメソッドは毎回異なった結果を返す可能性があります。 そうした変更が発生しない場合は、このメソッドから返される文字セットは、forNameメソッドから取得可能な文字セットとまったく同じになります。

戻り値:

文字セットの正規名とCharsetオブジェクトを対応付ける不変のマップ(アルファベットの大文字と小文字は区別されない)

defaultCharset

public static Charset defaultCharset()

このJava仮想マシンのデフォルトの文字セットを返します。

実装固有の方法で変更されないかぎり、デフォルトの文字セットはUTF-8です。

実装上のノート:

実装では、コマンドラインでシステム・プロパティfile.encodingを使用してデフォルトの文字セットをオーバーライドできます。 値がCOMPATの場合、デフォルトの文字セットはnative.encodingシステム・プロパティから導出されます。これは通常、基礎となるオペレーティング・システムのロケールおよび文字セットによって異なります。

戻り値:

デフォルトの文字セットのCharsetオブジェクト

導入されたバージョン:

1.5

関連項目:

• file.encoding
• native.encoding

name

public final String name()

この文字セットの正規名を返します。

戻り値:

この文字セットの正規名

aliases

public final Set<String> aliases()

この文字セットの別名が含まれるセットを返します。

戻り値:

この文字セットの別名が含まれる不変のセット

displayName

public String displayName()

デフォルト・ロケールにおける、この文字セットの名前(人間が読める形式)を返します。

このメソッドのデフォルト実装は、この文字セットの正規名だけを返します。 このクラスの具象サブクラスでこのメソッドをオーバーライドすれば、ローカライズされた表示名を提供できます。

戻り値:

デフォルト・ロケールにおけるこの文字セットの表示名

isRegistered

public final boolean isRegistered()

この文字セットがIANA Charset Registryに登録されているかどうかを判別します。

戻り値:

この文字セットが実装者によってIANAに登録されていることがわかった場合のみ、true

外部仕様

• 文字セット

displayName

public String displayName(Locale locale)

指定ロケールにおけるこの文字セットの名前(人間が読める形式)を返します。

このメソッドのデフォルト実装は、この文字セットの正規名だけを返します。 このクラスの具象サブクラスでこのメソッドをオーバーライドすれば、ローカライズされた表示名を提供できます。

パラメータ:

locale - 表示名を取得するロケール

戻り値:

指定ロケールにおけるこの文字セットの表示名

contains

public abstract boolean contains(Charset cs)

この文字セットに指定の文字セットが含まれているかどうかを判断します。

文字セットDで表現できるすべての文字を文字セットCでも表現できる場合に限り、文字セットCは文字セットDを含むと言うことができます。 この関係が成立している場合、文字セットDにエンコードできるすべての文字列は、文字の置換えを一切行うことなく、文字セットCにもエンコードできます。

文字セットCが文字セットDを「含む」と言っても、双方の文字セットが、個々の文字を表現するためにまったく同じバイト・シーケンスを使用しているとは限りません。

すべての文字セットは、自身を包含しています。

このメソッドは、包含関係の近似を計算: trueを返す場合、指定された文字セットはこの文字セットに含まれることがわかります。ただし、falseを返す場合、指定された文字セットがこの文字セットに含まれていないとは限りません。

パラメータ:

cs - 指定された文字セット

戻り値:

指定された文字セットがこの文字セットに含まれている場合、true

newDecoder

public abstract CharsetDecoder newDecoder()

この文字セットの新しいデコーダを構築します。

戻り値:

この文字セットの新しいデコーダ

newEncoder

public abstract CharsetEncoder newEncoder()

この文字セットの新しいエンコーダを構築します。

戻り値:

この文字セットの新しいエンコーダ

例外:

UnsupportedOperationException - この文字セットがエンコーディングをサポートしない場合

canEncode

public boolean canEncode()

この文字セットがエンコーディングをサポートするかどうかを判断します。

文字セットの大半はエンコードをサポートしていますが、例外もあります。 たとえば、特殊目的の自動検出文字セットなどです。この文字セットのデコーダは、入力バイト・シーケンスを調査することで、複数のエンコーディング方式のうちのどれが使用されているかを決定できます。 こうした文字セットはエンコードをサポートしません。出力時に使用すべきエンコーディング方式を特定できないためです。 このような文字セットを実装すると、このメソッドがオーバーライドされ、falseが返されます。

戻り値:

この文字セットがエンコーディングをサポートしている場合のみ、true

decode

public final CharBuffer decode(ByteBuffer bb)

この文字セットで表現されたバイトをUnicode文字にデコードする簡易メソッドです。

文字セットcsに対するこのメソッドの呼出しは、式と同じ結果を返します

    cs.newDecoder()
      .onMalformedInput(CodingErrorAction.REPLACE)
      .onUnmappableCharacter(CodingErrorAction.REPLACE)
      .decode(bb);

ただし、次の呼び出しまでの間にデコーダをキャッシュできるという点で、このメソッドのほうが効率的です。

このメソッドは、不正入力シーケンスやマップ不可文字シーケンスを、この文字セットのデフォルトの置換バイト配列で置き換えます。 そのようなシーケンスを検出するには、CharsetDecoder.decode(java.nio.ByteBuffer)メソッドを直接使用してください。

パラメータ:

bb - デコードされるbyteバッファ

戻り値:

デコードされた文字を格納する文字バッファ

encode

public final ByteBuffer encode(CharBuffer cb)

Unicode文字をこの文字セットで表現されたバイトにエンコードする簡易メソッドです。

文字セットcsに対するこのメソッドの呼出しは、式と同じ結果を返します

    cs.newEncoder()
      .onMalformedInput(CodingErrorAction.REPLACE)
      .onUnmappableCharacter(CodingErrorAction.REPLACE)
      .encode(bb);

ただし、次の呼び出しまでの間にエンコーダをキャッシュできるという点で、このメソッドのほうが効率的です。

このメソッドは、不正入力シーケンスやマップ不可文字シーケンスを、この文字セットのデフォルトの置換文字列で置き換えます。 そのようなシーケンスを検出するには、CharsetEncoder.encode(java.nio.CharBuffer)メソッドを直接使用してください。

パラメータ:

cb - エンコードされるcharバッファ

戻り値:

エンコードされた文字を格納するbyteバッファ

encode

public final ByteBuffer encode(String str)

文字列をこの文字セットで表現されたバイトにエンコードする簡易メソッドです。

文字セットcsに対するこのメソッドの呼出しは、式と同じ結果を返します

    cs.encode(CharBuffer.wrap(s));

パラメータ:

str - エンコードされる文字列

戻り値:

エンコードされた文字を格納するbyteバッファ

compareTo

public final int compareTo(Charset that)

この文字セットと別の文字セットを比較します。

文字セットは正規名順に並べられます(アルファベットの大文字と小文字は区別されない)。

定義:

compareTo、インタフェースComparable<Charset>

パラメータ:

that - この文字セットと比較する文字セット

戻り値:

この文字セットが指定された文字セットより小さい場合は負の整数、等しい場合はゼロ、大きい場合は正の整数

hashCode

public final int hashCode()

この文字セット用のハッシュ・コードを返します。

オーバーライド:

hashCode、クラスObject

戻り値:

この文字セット用のハッシュ・コード

関連項目:

• Object.equals(java.lang.Object)
• System.identityHashCode(java.lang.Object)

equals

public final boolean equals(Object ob)

このオブジェクトが別のオブジェクトと等価であるかどうかを判断します。

2つの文字セットは、同じ正規名を持っている場合に限り等価です。 文字セットがほかの型のオブジェクトと等価になることはありません。

オーバーライド:

equals、クラスObject

パラメータ:

ob - 比較対象の参照オブジェクト。

戻り値:

この文字セットが指定されたオブジェクトと等しい場合にのみtrue

関連項目:

• Object.hashCode()
• HashMap

toString

public final String toString()

この文字セットを説明する文字列を返します。

オーバーライド:

toString、クラスObject

戻り値:

この文字セットを記述する文字列