Skip to content
Tutorials Center
My learning

Topics

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.

Java
byte[] bytes = "café".getBytes(StandardCharsets.UTF_8);
String back = new String(bytes, StandardCharsets.UTF_8);

Try it

Java Characters, bytes and mismatches

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.

Java Strict decoding and reading with a charset

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

Java
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_16 or 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.out uses stdout.encoding, which can differ.
  • Silent damage. getBytes and new String never complain about bad data. Use a CharsetDecoder/CharsetEncoder with REPORT when corruption must be detected.
  • UTF_16 writes a byte order mark and decodes big-endian by default; UTF_16BE and UTF_16LE write no BOM.
  • Length differs. String.length() counts UTF-16 units, not characters or bytes. Size limits (database columns, network protocols) are in bytes: measure getBytes(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 InputStream use ISO-8859-1; see Properties.