Java Reference · I/O and Files
Reading and writing with charsets
Reference for Java character encodings: StandardCharsets, String.getBytes, InputStreamReader, malformed input handling, and the UTF-8 default since Java 18.
A charset maps characters to bytes and back. Java strings hold UTF-16 text in memory, but files, sockets and byte arrays hold bytes, so every conversion between the two needs a charset. If you do not name one, Java picks a default, which is how programs end up showing é instead of é on someone else's computer.
Always pass a Charset explicitly. The constants in java.nio.charset.StandardCharsets (UTF_8, UTF_16, ISO_8859_1, US_ASCII, UTF_16BE, UTF_16LE) cannot fail, so no UnsupportedEncodingException appears. Since Java 18 the default charset for APIs is UTF-8 on all platforms (JEP 400, see Java 18 to 21), but System.out and the console may still use another one.
byte[] bytes = "café".getBytes(StandardCharsets.UTF_8); String back = new String(bytes, StandardCharsets.UTF_8);
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> static Charset forName(String name) static Charset defaultCharset() static boolean isSupported(String name) CharsetEncoder newEncoder() CharsetDecoder newDecoder()
| API | Description |
|---|---|
String.getBytes(Charset) / new String(byte[], Charset) |
Convert; malformed or unmappable data is replaced silently (? when encoding, U+FFFD when decoding). |
new InputStreamReader(in, cs) / new OutputStreamWriter(out, cs) |
Bridge from byte streams to character streams. |
Files.readString(path, cs), Files.writeString(path, text, cs), Files.newBufferedReader(path, cs) |
NIO.2 methods; default UTF-8. |
CharsetDecoder.onMalformedInput(CodingErrorAction) |
REPORT throws, REPLACE substitutes, IGNORE drops. |
StandardCharsets.UTF_8 etc. |
The six charsets every JVM must support. |
Throws: UnsupportedCharsetException and IllegalCharsetNameException from forName, MalformedInputException / UnmappableCharacterException (both CharacterCodingException) from strict decoders and from Files.readString.
Usage notes
- UTF-8 is the answer for new data. It is compact for ASCII, can encode every code point and is the standard on the web. Use
UTF_16or others only when a format demands them. - The default changed in Java 18.
Charset.defaultCharset()is UTF-8 unless you set-Dfile.encoding=COMPAT. Older runtimes use the operating system's charset (for example windows-1252).System.outusesstdout.encoding, which can differ. - Silent damage.
getBytesandnew Stringnever complain about bad data. Use aCharsetDecoder/CharsetEncoderwithREPORTwhen corruption must be detected. UTF_16writes a byte order mark and decodes big-endian by default;UTF_16BEandUTF_16LEwrite no BOM.- Length differs.
String.length()counts UTF-16 units, not characters or bytes. Size limits (database columns, network protocols) are in bytes: measuregetBytes(UTF_8).length. - Mojibake repair works only if the wrong decoding was lossless, as with ISO-8859-1. Decoding as US-ASCII or UTF-8 loses information that cannot be recovered.
- Names are case-insensitive aliases:
Charset.forName("utf8")and"UTF-8"both work. Prefer the constants. - BOM. Java's UTF-8 decoder does not strip a leading BOM (U+FEFF); remove it yourself when reading files written by Windows tools.
- Properties files read through an
InputStreamuse ISO-8859-1; seeProperties.