TextEncoding

Turns bytes into text when nobody can be trusted about the encoding.

EPUB says UTF-8 or UTF-16 and nothing else. Real books ship Windows-1252 anyway, sometimes while declaring UTF-8, which is why the declaration is treated as a hint rather than an answer.

The order of evidence, strongest first:

1. A byte order mark.

2. UTF-16 without one, spotted by the NUL pattern of an ASCII opener.

3. A declaration in the bytes: <?xml encoding=...?>, <meta charset>, or the legacy <meta http-equiv="Content-Type">.

4. The caller's hint, e.g. an HTTP Content-Type.

5. Valid UTF-8 stays UTF-8; anything else is decoded as Windows-1252, which never fails and covers the Western-European mojibake case.

val html = TextEncoding.decode(zip.read("chapter1.xhtml")!!)