java.nio.charset.Charset

All Implemented Interfaces:: Comparable<Charset>

public abstract class Charset
extends Object
implements Comparable<Charset>

A charset is a named mapping between Unicode characters and byte sequences. Every Charset can decode, converting a byte sequence into a sequence of characters, and some can also encode, converting a sequence of characters into a byte sequence. Use the method canEncode() to find out whether a charset supports both.

Characters

In the context of this class, character always refers to a Java character: a Unicode code point in the range U+0000 to U+FFFF. (Java represents supplementary characters using surrogates.) Not all byte sequences will represent a character, and not all characters can necessarily be represented by a given charset. The method contains(java.nio.charset.Charset) can be used to determine whether every character representable by one charset can also be represented by another (meaning that a lossless transformation is possible from the contained to the container).

Encodings

There are many possible ways to represent Unicode characters as byte sequences. See UTR#17: Unicode Character Encoding Model for detailed discussion.

The most important mappings capable of representing every character are the Unicode Transformation Format (UTF) charsets. Of those, UTF-8 and the UTF-16 family are the most common. UTF-8 (described in RFC 3629) encodes a character using 1 to 4 bytes. UTF-16 uses exactly 2 bytes per character (potentially wasting space, but allowing efficient random access into BMP text), and UTF-32 uses exactly 4 bytes per character (trading off even more space for efficient random access into text that includes supplementary characters).

UTF-16 and UTF-32 encode characters directly, using their code point as a two- or four-byte integer. This means that any given UTF-16 or UTF-32 byte sequence is either big- or little-endian. To assist decoders, Unicode includes a special byte order mark (BOM) character U+FEFF used to determine the endianness of a sequence. The corresponding byte-swapped code point U+FFFE is guaranteed never to be assigned. If a UTF-16 decoder sees 0xfe, 0xff, for example, it knows it's reading a big-endian byte sequence, while 0xff, 0xfe, would indicate a little-endian byte sequence.

UTF-8 can contain a BOM, but since the UTF-8 encoding of a character always uses the same byte sequence, there is no information about endianness to convey. Seeing the bytes corresponding to the UTF-8 encoding of U+FEFF (0xef, 0xbb, 0xbf) would only serve to suggest that you're reading UTF-8. Note that BOMs are decoded as the U+FEFF character, and will appear in the output character sequence. This means that a disadvantage to including a BOM in UTF-8 is that most applications that use UTF-8 do not expect to see a BOM. (This is also a reason to prefer UTF-8: it's one less complication to worry about.)

Because a BOM indicates how the data that follows should be interpreted, a BOM should occur as the first character in a character sequence.

See the Byte Order Mark (BOM) FAQ for more about dealing with BOMs.

Endianness and BOM behavior

The following tables show the endianness and BOM behavior of the UTF-16 variants.

This table shows what the encoder writes. "BE" means that the byte sequence is big-endian, "LE" means little-endian. "BE BOM" means a big-endian BOM (that is, 0xfe, 0xff).

Charset	Encoder writes
UTF-16BE	BE, no BOM
UTF-16LE	LE, no BOM
UTF-16	BE, with BE BOM

The next table shows how each variant's decoder behaves when reading a byte sequence. The exact meaning of "failure" in the table is dependent on the CodingErrorAction supplied to CharsetDecoder.malformedInputAction, so "BE, failure" means "the byte sequence is treated as big-endian, and a little-endian BOM triggers the malformedInputAction".

The phrase "includes BOM" means that the output includes the U+FEFF byte order mark character.

Charset	BE BOM	LE BOM	No BOM
UTF-16BE	BE, includes BOM	BE, failure	BE
UTF-16LE	LE, failure	LE, includes BOM	LE
UTF-16	BE	LE	BE

Charset names

A charset has a canonical name, returned by name(). Most charsets will also have one or more aliases, returned by aliases(). A charset can be looked up by canonical name or any of its aliases using forName(java.lang.String).

Guaranteed-available charsets

The following charsets are available on every Java implementation:

ISO-8859-1
US-ASCII
UTF-16
UTF-16BE
UTF-16LE
UTF-8

All of these charsets support both decoding and encoding. The charsets whose names begin "UTF" can represent all characters, as mentioned above. The "ISO-8859-1" and "US-ASCII" charsets can only represent small subsets of these characters. Except when required to do otherwise for compatibility, new code should use one of the UTF charsets listed above. The platform's default charset is UTF-8. (This is in contrast to some older implementations, where the default charset depended on the user's locale.)

Most implementations will support hundreds of charsets. Use availableCharsets() or isSupported(java.lang.String) to see what's available. If you intend to use the charset if it's available, just call forName(java.lang.String) and catch the exceptions it throws if the charset isn't available.

Additional charsets can be made available by configuring one or more charset providers through provider configuration files. Such files are always named as "java.nio.charset.spi.CharsetProvider" and located in the "META-INF/services" directory of one or more classpaths. The files should be encoded in "UTF-8". Each line of their content specifies the class name of a charset provider which extends CharsetProvider. A line should end with '\r', '\n' or '\r\n'. Leading and trailing whitespace is trimmed. Blank lines, and lines (after trimming) starting with "#" which are regarded as comments, are both ignored. Duplicates of names already found are also ignored. Both the configuration files and the provider classes will be loaded using the thread context class loader.

Although class is thread-safe, the CharsetDecoder and CharsetEncoder instances it returns are inherently stateful.

Constructor Summary

Constructors

Modifier Constructor Description

protected Charset(String canonicalName, String[] aliases)
Constructs a Charset object.

Method Summary

Modifier and Type	Method	Description
`Set<String>`	`aliases()`	Returns an unmodifiable set of this charset's aliases.
`static SortedMap<String,Charset>`	`availableCharsets()`	Returns an immutable case-insensitive map from canonical names to `Charset` instances.
`boolean`	`canEncode()`	Returns true if this charset supports encoding, false otherwise.
`int`	`compareTo(Charset charset)`	Compares this charset with the given charset.
`abstract boolean`	`contains(Charset charset)`	Determines whether this charset is a superset of the given charset.
`CharBuffer`	`decode(ByteBuffer buffer)`	Returns a new `CharBuffer` containing the characters decoded from `buffer`.
`static Charset`	`defaultCharset()`	Returns the system's default charset.
`String`	`displayName()`	Returns the name of this charset for the default locale.
`String`	`displayName(Locale l)`	Returns the name of this charset for the specified locale.
`ByteBuffer`	`encode(String s)`	Returns a new `ByteBuffer` containing the bytes encoding the characters from `s`.
`ByteBuffer`	`encode(CharBuffer buffer)`	Returns a new `ByteBuffer` containing the bytes encoding the characters from `buffer`.
`boolean`	`equals(Object obj)`	Determines whether this charset equals to the given object.
`static Charset`	`forName(String charsetName)`	Returns a `Charset` instance for the named charset.
`static Charset`	`forNameUEE(String charsetName)`	Equivalent to `forName` but only throws `UnsupportedEncodingException`, which is all pre-nio code claims to throw.
`int`	`hashCode()`	Gets the hash code of this charset.
`boolean`	`isRegistered()`	Returns true if this charset is known to be registered in the IANA Charset Registry.
`static boolean`	`isSupported(String charsetName)`	Determines whether the specified charset is supported by this runtime.
`String`	`name()`	Returns the canonical name of this charset.
`abstract CharsetDecoder`	`newDecoder()`	Returns a new instance of a decoder for this charset.
`abstract CharsetEncoder`	`newEncoder()`	Returns a new instance of an encoder for this charset.
`String`	`toString()`	Gets a string representation of this charset.

Methods inherited from class java.lang.Object

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

Constructor Details
- Charset
  
  protected Charset(String canonicalName, String[] aliases)
  
  Constructs a Charset object. Duplicated aliases are ignored.
  
  Parameters:
  
  canonicalName - the canonical name of the charset.
  
  aliases - an array containing all aliases of the charset. May be null.
  
  Throws:
  
  IllegalCharsetNameException - on an illegal value being supplied for either canonicalName or for any element of aliases.
Method Details
- availableCharsets
  
  public static SortedMap<String,Charset> availableCharsets()
  
  Returns an immutable case-insensitive map from canonical names to Charset instances. If multiple charsets have the same canonical name, it is unspecified which is returned in the map. This method may be slow. If you know which charset you're looking for, use forName(java.lang.String).
- forName
  
  public static Charset forName(String charsetName)
  
  Returns a Charset instance for the named charset.
  
  Parameters:
  
  charsetName - a charset name (either canonical or an alias)
  
  Throws:
  
  IllegalCharsetNameException - if the specified charset name is illegal.
  
  UnsupportedCharsetException - if the desired charset is not supported by this runtime.
- forNameUEE
  
  public static Charset forNameUEE(String charsetName) throws UnsupportedEncodingException
  
  Equivalent to forName but only throws UnsupportedEncodingException, which is all pre-nio code claims to throw.
  
  Throws:
  
  UnsupportedEncodingException
- isSupported
  
  public static boolean isSupported(String charsetName)
  
  Determines whether the specified charset is supported by this runtime.
  
  Parameters:
  
  charsetName - the name of the charset.
  
  Returns:
  
  true if the specified charset is supported, otherwise false.
  
  Throws:
  
  IllegalCharsetNameException - if the specified charset name is illegal.
- contains
  
  public abstract boolean contains(Charset charset)
  
  Determines whether this charset is a superset of the given charset. A charset C1 contains charset C2 if every character representable by C2 is also representable by C1. This means that lossless conversion is possible from C2 to C1 (but not necessarily the other way round). It does not imply that the two charsets use the same byte sequences for the characters they share.
  Note that this method is allowed to be conservative, and some implementations may return false when this charset does contain the other charset. Android's implementation is precise, and will always return true in such cases.
  
  Parameters:
  
  charset - a given charset.
  
  Returns:
  
  true if this charset is a super set of the given charset, false if it's unknown or this charset is not a superset of the given charset.
- newEncoder
  
  public abstract CharsetEncoder newEncoder()
  
  Returns a new instance of an encoder for this charset.
- newDecoder
  
  public abstract CharsetDecoder newDecoder()
  
  Returns a new instance of a decoder for this charset.
- name
  
  public final String name()
  
  Returns the canonical name of this charset.
  If a charset is in the IANA registry, this will be the MIME-preferred name (a charset may have multiple IANA-registered names). Otherwise the canonical name will begin with "x-" or "X-".
- aliases
  
  public final Set<String> aliases()
  
  Returns an unmodifiable set of this charset's aliases.
- displayName
  
  public String displayName()
  
  Returns the name of this charset for the default locale.
  The default implementation returns the canonical name of this charset. Subclasses may return a localized display name.
- displayName
  
  public String displayName(Locale l)
  
  Returns the name of this charset for the specified locale.
  The default implementation returns the canonical name of this charset. Subclasses may return a localized display name.
- isRegistered
  
  public final boolean isRegistered()
  
  Returns true if this charset is known to be registered in the IANA Charset Registry.
- canEncode
  
  public boolean canEncode()
  
  Returns true if this charset supports encoding, false otherwise.
- encode
  
  public final ByteBuffer encode(CharBuffer buffer)
  
  Returns a new ByteBuffer containing the bytes encoding the characters from buffer. This method uses CodingErrorAction.REPLACE.
  Applications should generally create a CharsetEncoder using newEncoder() for performance.
  
  Parameters:
  
  buffer - the character buffer containing the content to be encoded.
  
  Returns:
  
  the result of the encoding.
- encode
  
  public final ByteBuffer encode(String s)
  
  Returns a new ByteBuffer containing the bytes encoding the characters from s. This method uses CodingErrorAction.REPLACE.
  Applications should generally create a CharsetEncoder using newEncoder() for performance.
  
  Parameters:
  
  s - the string to be encoded.
  
  Returns:
  
  the result of the encoding.
- decode
  
  public final CharBuffer decode(ByteBuffer buffer)
  
  Returns a new CharBuffer containing the characters decoded from buffer. This method uses CodingErrorAction.REPLACE.
  Applications should generally create a CharsetDecoder using newDecoder() for performance.
  
  Parameters:
  
  buffer - the byte buffer containing the content to be decoded.
  
  Returns:
  
  a character buffer containing the output of the decoding.
- compareTo
  
  public final int compareTo(Charset charset)
  
  Compares this charset with the given charset. This comparison is based on the case insensitive canonical names of the charsets.
  
  Specified by:
  
  compareTo in interface Comparable<Charset>
  
  Parameters:
  
  charset - the given object to be compared with.
  
  Returns:
  
  a negative integer if less than the given object, a positive integer if larger than it, or 0 if equal to it.
- equals
  
  public final boolean equals(Object obj)
  
  Determines whether this charset equals to the given object. They are considered to be equal if they have the same canonical name.
  
  Overrides:
  
  equals in class Object
  
  Parameters:
  
  obj - the given object to be compared with.
  
  Returns:
  
  true if they have the same canonical name, otherwise false.
  
  See Also:
  
  Object.hashCode()
- hashCode
  
  public final int hashCode()
  
  Gets the hash code of this charset.
  
  Overrides:
  
  hashCode in class Object
  
  Returns:
  
  the hash code of this charset.
  
  See Also:
  
  Object.equals(java.lang.Object)
- toString
  
  public final String toString()
  
  Gets a string representation of this charset. Usually this contains the canonical name of the charset.
  
  Overrides:
  
  toString in class Object
  
  Returns:
  
  a string representation of this charset.
- defaultCharset
  
  public static Charset defaultCharset()
  
  Returns the system's default charset. This is determined during VM startup, and will not change thereafter. On Android, the default charset is UTF-8.

Class Charset

Characters

Encodings

Endianness and BOM behavior

Charset names

Guaranteed-available charsets

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Details

Charset

Method Details

availableCharsets

forName

forNameUEE

isSupported

contains

newEncoder

newDecoder

name

aliases

displayName

displayName

isRegistered

canEncode

encode

encode

decode

compareTo

equals

hashCode

toString

defaultCharset