Java Reference · Text, Formatting and Regex
Charset and StandardCharsets
Reference for java.nio.charset.Charset and StandardCharsets: converting between String and bytes, UTF-8 vs ISO-8859-1, malformed input and the default charset.
A java.nio.charset.Charset is a mapping between characters and bytes. Java strings are sequences of UTF-16 code units in memory, but files, sockets and databases store bytes, so every conversion between the two needs a charset. StandardCharsets holds constants for the six charsets every Java platform must support, so you can write StandardCharsets.UTF_8 instead of the string "UTF-8" and avoid a checked exception.
Since Java 18 (JEP 400) the default charset is UTF-8 on every platform, so new String(bytes) and getBytes() no longer depend on the operating system. Even so, passing the charset explicitly makes code self-documenting and keeps it correct when read from older code or other tools.
byte[] data = "héllo".getBytes(StandardCharsets.UTF_8); String text = new String(data, StandardCharsets.UTF_8); Charset cs = Charset.forName("windows-1252");
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input · what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input · what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.
Syntax
public abstract class Charset implements Comparable<Charset> public final class StandardCharsets // constants only
| Member | Description |
|---|---|
StandardCharsets.UTF_8 |
Variable-width Unicode encoding (1 to 4 bytes per code point). The right default for almost everything. |
StandardCharsets.UTF_16, UTF_16BE, UTF_16LE |
Two or four bytes per code point. UTF_16 writes a byte order mark when encoding and honors one when decoding. |
StandardCharsets.ISO_8859_1 |
Latin-1: one byte per character, code points 0 to 255 only. |
StandardCharsets.US_ASCII |
Seven-bit ASCII. |
Charset.forName(String) |
Looks up a charset by name or alias. Throws UnsupportedCharsetException or IllegalCharsetNameException. |
Charset.isSupported(String) |
Tests whether a name is available. |
Charset.defaultCharset() |
The JVM default (UTF-8 since Java 18). |
name(), aliases() |
Canonical name and alternative names. |
newEncoder(), newDecoder() |
Configurable converters with explicit error handling. |
encode(String), decode(ByteBuffer) |
Convenience conversions that always replace bad input. |
Throws: forName throws IllegalCharsetNameException for an illegal name (such as one containing spaces) and UnsupportedCharsetException for a legal name that the JVM does not know.
Usage notes
- Always pass a charset to
String.getBytes,new String(bytes, cs),Files.readString,InputStreamReader,PrintWriterand similar APIs when the data crosses a boundary. The overloads without a charset are fine only when you really mean the default. - Prefer the
Charsetoverloads over name strings.getBytes("UTF-8")forces you to handleUnsupportedEncodingException;getBytes(StandardCharsets.UTF_8)cannot fail that way. - Lenient by default.
new String(bytes, cs)andgetBytes(cs)silently substitute a replacement character (U+FFFDwhen decoding,?or the encoder's replacement when encoding). UsenewDecoder().onMalformedInput(CodingErrorAction.REPORT)when bad data must be an error. - Lossy encodings. Encoding
éor€asUS_ASCIIgives?.ISO_8859_1cannot represent€at all. - Length changes. The byte count of a string depends on the charset:
"€".getBytes(UTF_8).lengthis 3, inUTF_16BEit is 2. - Default charset history. Before Java 18 the default came from the OS (often windows-1252 on Windows). Code that relied on it may read old files differently.
System.outandstdout.encodingare a separate setting. - Instances are immutable and thread-safe; encoders and decoders are not, so create one per use.
- Optional charsets such as
windows-1252orShift_JISlive in thejdk.charsetsmodule and are normally present in a full JDK.