java.nio.charset
類別 Charset

java.lang.Object
  java.nio.charset.Charset

所有已實作的介面：

Comparable<Charset>

public abstract class Charset
extends Object
implements Comparable<Charset>

16 位的 Unicode 程式碼單元序列和位元組序列之間的指定映射關係。此類別定義了用於創建解碼器和編碼器以及獲取與 charset 關聯的各種名稱的方法。此類別的實例是不可變的。

此類別也定義了用於測試是否支持特定 charset 的靜態方法、通過名稱尋找 charset 實例的靜態方法，以及建構一個套件含目前 Java 虛擬機器支持的每個 charset 的映射靜態方法。通過類別 CharsetProvider 中定義的服務提供者介面可以添加對新 charset 的支持。

此類別中定義的所有方法用於多個共時執行緒是安全的。

Charset 名稱

通過以下字元所組成的字元串來命名 Charset：

• 大寫字母 'A' 到 'Z'（'\u0041' 到 '\u005a'），
• 小寫字母 'a' 到 'z'（'=pos; 到 ' apos;），
• 數字 '0' 到 '9'（'\u0030' 到 '\u0039'），
• 短劃線字元 '-'（'\u002d'，連詞符號），
• 句點字元 '.'('\u002e'，句點），
• 冒號字元 ':'('\u003a'，冒號），和
• 下劃線字元 '_'（'\u005f'，下劃線）。

Charset 名稱必須以字母或數字開頭。空字元串不是合法的 charset 名稱。Charset 名稱是大小寫不敏感的，也就是當比較 charset 名稱時總是忽略大小寫。Charset 名稱通常遵循 RFC2278:IANA Charset Registration Procedures 中所記錄的約定。

每個 charset 有一個規範名稱，也可能有一個或多個別名。規範名稱由此類別的 name 方法返回。根據約定，規範名稱通常是大寫的。charset 的別名由 aliases 方法返回。

一些 charset 有一個歷史名稱，定義這個名稱是為了和以前版本的 Java 平臺相容。charset 的歷史名稱既可以是它的規範名稱，也可以是它的某個別名。歷史名稱由 InputStreamReader 和 OutputStreamWriter 類別的 getEncoding() 方法返回。

如果 Java 平臺的實作支持列於 IANA Charset Registry 中的 charset，那麼它的規範名稱必須是註冊表中列出的名字。很多 charset 在註冊表中給出不止一個名稱，在這種情況下註冊表將某個名稱標識為 MIME 首選的。如果 charset 有多個註冊表名稱，那麼它的規範名稱必須是 MIME 首選的名稱，並且註冊表中的其他名稱必須是合法的別名。如果支持的 charset 沒有列在 IANA 註冊表中，那麼它的規範名稱必須以字元串 "X-" 或 "x-" 中的一個開頭。

IANA charset 註冊表不斷進行更改，所以特定 charset 的規範名稱和別名也會隨之更改。為了確保相容性，推薦不要刪除 charset 的別名，如果更改了 charset 的規範名稱，那麼可將以前的規範名稱作為別名。

標準 charset

Java 平臺的每一種實作都需要支持以下標準 charset。請參考該實作的版本文檔，查看是否支持其他 charset。這些可選 charset 的行為在不同的實作之間可能有所不同。

Charset	描述
US-ASCII	7 位 ASCII 字元，也叫作 ISO646-US、Unicode 字元集的基本拉丁塊
ISO-8859-1	ISO 拉丁字母表 No.1，也叫作 ISO-LATIN-1
UTF-8	8 位 UCS 轉換格式
UTF-16BE	16 位 UCS 轉換格式，Big Endian（最低位址存放高位位元組）位元組順序
UTF-16LE	16 位 UCS 轉換格式，Little-endian（最高位址存放低位位元組）位元組順序
UTF-16	16 位 UCS 轉換格式，位元組順序由可選的位元組順序標記來標識

UTF-8 charset 在 RFC 2279 中指定；它所基於的轉換格式在 ISO 10646-1 的 Amendment 2 中指定，並在 Unicode Standard 中也有所描述。

UTF-16 charset 在 RFC 2781 中指定；它們基於的轉換格式在 ISO10646-1 的 Amendment 1 中指定，並在 Unicode Standard 中也有所描述。

UTF-16 charset 使用 16 位量，因此對位元組順序敏感。在這些編碼中，串流的位元組順序可以由 Unicode 字元 'FF' 所表示的初始位元組順序標記 來指示。按以下方式處理位元組順序標記：

• 進行解碼時，UTF-16BE 和 UTF-16LE charset 忽略位元組順序標記；進行編碼時，不寫入位元組順序標記。

• 進行解碼時，UTF-16 charset 解釋位元組順序標記，以指示串流的位元組順序，但是如果沒有位元組順序標記，則預設使用 Big Endian；進行編碼時，使用 Big Endian 位元組順序並寫入 Big Endian 位元組順序標記。

在任何情況中，在解碼操作的開始讀取位元組順序標記時，將在結果字元序列中忽略該標記。位元組順序標記出現在輸入序列的第一個元素之後時，由於使用相同的程式碼表示零寬度不間斷空格，所以不忽略該標記。

Java 虛擬機器的每個實例都有預設的 charset，它可能是也可能不是某個標準 charset。預設 charset 在虛擬機器啟動時決定，通常根據語言環境和底層作業系統使用的 charset 來確定。

術語

此類別的名稱取自 RFC 2278 中使用的術語。在該文檔中，charset 被定義為編碼字元集和字元編碼方案的組合。

編碼字元集 是抽象字元集合和整數集合之間的映射關係。US-ASCII、ISO 8859-1、JIS X 0201 和與 ISO 10646-1 相同的完整 Unicode 都是編碼字元集範例。

字元編碼方案 是編碼字元集和八位組（八位位元組）序列集合之間的映射關係。UTF-8、UCS-2、UTF-16、ISO 2022 和 EUC 是一些字元編碼方案範例。編碼方案通常與特定的編碼字元集相關聯；例如，UTF-8 只用來編碼 Unicode。但是，一些方案與多個字元集相關聯；例如，EUC 可用於編碼各種亞洲字元集中的字元。

當編碼字元集專門用於一個字元編碼方案時，相應的 charset 通常使用字元集合命名；否則 charset 使用編碼方案命名，很有可能使用它所支持的字元集的語言環境來命名。因此 US-ASCII 是 US-ASCII charset 名稱，而 EUC-JP 是編碼 JIS X 0201、JIS X 0208 和 JIS X 0212 字元集的 charset 名稱。

Java 程式語言的本機字元編碼方案是 UTF-16。因此 Java 平臺的 charset 定義了 16 位 UTF-16 程式碼單元序列和位元組序列之間的映射關係。

從以下版本開始：

1.4

另請參見：

CharsetDecoder, CharsetEncoder, CharsetProvider, Character

建構子摘要

protected

Charset(String canonicalName, String[] aliases) 使用給定的規範名稱和別名集合初始化新 charset。

方法摘要

Set<String>	aliases() 返回包含此 charset 各個別名的集合。
static SortedMap<String,Charset>	availableCharsets() 建構從規範 charset 名稱到 charset 物件的有序映射。
boolean	canEncode() 通知此 charset 是否支持編碼。
int	compareTo(Charset that) 比較此 charset 與其他 charset。
abstract boolean	contains(Charset cs) 通知此 charset 是否包含給定的 charset。
CharBuffer	decode(ByteBuffer bb) 將此 charset 中的位元組解碼成 Unicode 字元的便捷方法。
static Charset	defaultCharset() 返回此 Java 虛擬機器的預設 charset。
String	displayName() 返回此 charset 用於預設語言環境的可讀名稱。
String	displayName(Locale locale) 返回此 charset 用於給定語言環境的可讀名稱。
ByteBuffer	encode(CharBuffer cb) 將此 charset 中的 Unicode 字元編碼成位元組的便捷方法。
ByteBuffer	encode(String str) 將此 charset 中的字元串編碼成位元組的便捷方法。
boolean	equals(Object ob) 通知此物件是否和其他物件相等。
static Charset	forName(String charsetName) 返回指定 charset 的 charset 物件。
int	hashCode() 計算此 charset 的雜湊碼。
boolean	isRegistered() 通知此 charset 是否已在 IANA Charset Registry 中註冊。
static boolean	isSupported(String charsetName) 通知是否支持指定的 charset。
String	name() 返回此 charset 的規範名稱。
abstract CharsetDecoder	newDecoder() 為此 charset 建構新的解碼器。
abstract CharsetEncoder	newEncoder() 為此 charset 建構新的編碼器。
String	toString() 返回描述此 charset 的字元串。

從類別 java.lang.Object 繼承的方法

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

建構子詳細資訊

Charset

protected Charset(String canonicalName,
                  String[] aliases)

使用給定的規範名稱和別名集合初始化新 charset。

參數：

canonicalName - 此 charset 的規範名稱

aliases - 此 charset 別名的陣列，如果沒有別名則為 null

拋出：

IllegalCharsetNameException - 如果規範名稱和任何一個別名非法

方法詳細資訊

isSupported

public static boolean isSupported(String charsetName)

通知是否支持指定的 charset。

參數：

charsetName - 請求的 charset 名稱；可能是規範名稱或別名

返回：

當且僅當當前 Java 虛擬機器支持指定的 charset 時才返回 true

拋出：

IllegalCharsetNameException - 如果給定的 charset 名稱是非法的

IllegalArgumentException - 如果給定的 charsetName 為 null

forName

public static Charset forName(String charsetName)

返回指定 charset 的 charset 物件。

參數：

charsetName - 請求的 charset 名稱；可能是規範名稱或別名

返回：

指定 charset 的 charset 物件

拋出：

IllegalCharsetNameException - 如果給定的 charset 名稱是非法的

IllegalArgumentException - 如果給定的 charsetName 為 null

UnsupportedCharsetException - 如果此 Java 虛擬機器的實例不支持指定 charset

availableCharsets

public static SortedMap<String,Charset> availableCharsets()

建構從規範 charset 名稱到 charset 物件的有序映射。

此方法返回的映射對每個 charset 都有一項，當前 Java 虛擬機器是支持這些 charset 的。如果所支持的兩個或多個 charset 具有相同的規範名稱，則結果映射中只包含它們中的一個；包含哪一個沒有指定。

對此方法的調用，以及對結果映射的後續使用可能導致出現耗時的磁碟或網路 I/O 操作。為需要列舉所有可用 charset 的應用程序提供此方法，例如允許使用者選擇 charset。forName 方法不使用此方法，而是使用一種高效的增量尋找演算法。

如果新的 charset 提供者可供當前 Java 虛擬機器動態使用，則此方法可能在不同的時間返回不同的結果。如果沒有這種改變，則此方法返回的 charset 恰好是那些可以通過 forName 方法獲取的 charset。

返回：

規範 charset 名稱到 charset 物件的不可變的、大小寫不敏感的映射

defaultCharset

public static Charset defaultCharset()

返回此 Java 虛擬機器的預設 charset。

預設 charset 在虛擬機器啟動時決定，通常根據語言環境和底層作業系統的 charset 來確定。

返回：

預設 charset 的 charset 物件

從以下版本開始：

1.5

name

public final String name()

返回此 charset 的規範名稱。

返回：

此 charset 的規範名稱

aliases

public final Set<String> aliases()

返回包含此 charset 各個別名的集合。

返回：

此 charset 不可變的別名集合

displayName

public String displayName()

返回此 charset 用於預設語言環境的可讀名稱。

此方法的預設實作只返回此 charset 的規範名稱。為了提供本地化的顯示名稱，此類別的具體子類別可以覆寫此方法。

返回：

預設語言環境下此 charset 的顯示名稱

isRegistered

public final boolean isRegistered()

通知此 charset 是否已在 IANA Charset Registry 中註冊。

返回：

當且僅當此 charset 的實作程序知道此 charset 已向 IANA 註冊時才返回 true

displayName

public String displayName(Locale locale)

返回此 charset 用於給定語言環境的可讀名稱。

此方法的預設實作只返回此 charset 的規範名稱。為了提供本地化的顯示名稱，此類別的具體子類別可以覆寫此方法。

參數：

locale - 要為其獲取顯示名稱的語言環境

返回：

給定語言環境下此 charset 的顯示名稱

contains

public abstract boolean contains(Charset cs)

通知此 charset 是否包含給定的 charset。

當且僅當在 charset D 中可表示的每個字元，在字元集 C 中也是可表示的時，才能說 C 包含 D。如果存在這種關係，就能保證可在 D 進行編碼的所有字元串不用執行任何替換就可在 C 中進行編碼。

C 套件含 D 不表示 C 中以特定位元組序列可表示的每個字元在 D 中也以相同的位元組序列表示，儘管有時是這種情況。

每個 charset 套件含其自身。

此方法計算近似的套件含關係：如果返回 true，則已知給定的 charset 套件含在此 charset 中；但是如果返回 false，則不一定說明給定的 charset 不包含在此 charset 中。

返回：

如果給定的 charset 套件含在此 charset 中，則返回 true

newDecoder

public abstract CharsetDecoder newDecoder()

為此 charset 建構新的解碼器。

返回：

此 charset 的新解碼器

newEncoder

public abstract CharsetEncoder newEncoder()

為此 charset 建構新的編碼器。

返回：

此 charset 的新編碼器

拋出：

UnsupportedOperationException - 如果此 charset 不支持編碼

canEncode

public boolean canEncode()

通知此 charset 是否支持編碼。

幾乎所有的 charset 都支持編碼。常見的例外是專用的自動檢測 charset，它的解碼器通過檢查輸入位元組序列，就能夠確定正在使用多個可能編碼方案中的哪一個。此類別 charset 不支持編碼是由於無法確定輸出時應該使用哪種編碼。此類別 charset 的實作應該覆寫此方法以返回 false。

返回：

當且僅當此 charset 支持編碼時才返回 true

decode

public final CharBuffer decode(ByteBuffer bb)

將此 charset 中的位元組解碼成 Unicode 字元的便捷方法。

在 charset cs 上調用此方法，會返回和下面表達式相同的結果

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

除此之外它可能更為高效，因為它能在兩次連續的調用之間快取記憶體解碼器。

此方法總是用此 charset 的預設替換 byte 陣列替換錯誤輸入和不可映射的字元序列。為了檢測此種序列，可直接使用 CharsetDecoder.decode(java.nio.ByteBuffer) 方法。

參數：

bb - 要解碼的 byte 緩衝區

返回：

包含已解碼字元的 char 緩衝區

encode

public final ByteBuffer encode(CharBuffer cb)

將此 charset 中的 Unicode 字元編碼成位元組的便捷方法。

在 charset cs 上調用此方法，會返回和下面表達式相同的結果

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

除此之外它可能更為高效，因為它能在兩次連續的調用之間快取記憶體編碼器。

此方法總是用此 charset 的預設替換字元串替換錯誤輸入和不可映射的字元序列。為了檢測此種序列，可直接使用 CharsetEncoder.encode(java.nio.CharBuffer) 方法。

參數：

cb - 要編碼的 char 緩衝區

返回：

包含已編碼字元的 byte 緩衝區

encode

public final ByteBuffer encode(String str)

將此 charset 中的字元串編碼成位元組的便捷方法。

在 charset cs 上調用此方法，會返回和下面表達式相同的結果

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

參數：

str - 要編碼的字元串

返回：

包含已編碼字元的 byte 緩衝區

compareTo

public final int compareTo(Charset that)

比較此 charset 與其他 charset。

charset 根據它們的規範名稱排序，而不考慮大小寫。

指定者：

介面 Comparable<Charset> 中的 compareTo

參數：

that - 和此 charset 進行比較的 charset

返回：

如果此 charset 小於、等於或大於指定的 charset，則分別返回負整數、零或正整數

hashCode

public final int hashCode()

計算此 charset 的雜湊碼。

覆寫：

類別 Object 中的 hashCode

返回：

整數雜湊碼

另請參見：

Object.equals(java.lang.Object), Hashtable

equals

public final boolean equals(Object ob)

通知此物件是否和其他物件相等。

當且僅當兩個 charset 具有相同的規範名稱時它們才相等。一個 charset 從來不和任何其他型別的物件相等。

覆寫：

類別 Object 中的 equals

參數：

ob - 要與之比較的參考物件。

返回：

當且僅當此 charset 等於給定物件時才返回 true

另請參見：

Object.hashCode(), Hashtable

toString

public final String toString()

返回描述此 charset 的字元串。

覆寫：

類別 Object 中的 toString

返回：

描述此 charset 的字元串