dk.simongray.id3.text — dk.simongray/id3-clj 0.1.1

The text in ID3v2 frames: its four encodings, and strings that end in a terminator.

A frame with text names its encoding in its first byte. ID3v2.4 has four encodings: ISO-8859-1, UTF-16 with a byte order mark, UTF-16BE and UTF-8. ID3v2.3 has only the first two. A string ends at a terminator, which is a zero byte, or two for UTF-16, or else at the end of the frame.

The functions that read a frame take a reading context from diagnostics/context, for the quirks of text that breaks the spec. The functions that write one throw for text that the frame can't hold.

decode clj/s

(decode b encoding)

The text of the bytes b in encoding: :latin1, :utf8, :utf16le or :utf16be. A byte order mark stays. Bytes that aren't UTF-8 become U+FFFD, and so does an odd byte at the end of UTF-16, on both platforms.

encode clj/s

(encode s encoding)

The bytes of the text s in encoding: :latin1, :utf8, :utf16le, :utf16be, or :utf16, which is UTF-16LE after a byte order mark. It throws when the encoding is ISO-8859-1 and s doesn't fit it.

encode-string clj/s

(encode-string s encoding)

The bytes of the string s in the ID3 encoding, without a terminator. It throws when s isn't a string, when it holds a null character, which would end it, or when the encoding can't hold it.

encode-terminated clj/s

(encode-terminated s encoding)

The bytes of the string s in the ID3 encoding, with its terminator.

encoding-byte clj/s

(encoding-byte encoding)

The byte that names encoding in a frame.

encoding-for clj/s

(encoding-for version requested strings)

The encoding to write the strings of a frame of version in: the requested one, when the version has it and it can hold the strings.

Otherwise, it's ISO-8859-1 when that can hold the strings, unless one of them would look like UTF-8 to a reader. Failing that, it's UTF-8 for ID3v2.4 and UTF-16 for 2.3.

encodings clj/s

The text encoding of each encoding byte.

latin1? clj/s

(latin1? s)

Whether ISO-8859-1 can hold each character of the text s.

string-at clj/s

(string-at ctx b start end encoding)

The string in the ID3 encoding at start in b, up to its terminator or end, read in the context ctx. It returns a pair of the string and where what follows it starts.

strings clj/s

(strings ctx b start end encoding)

The strings in the ID3 encoding in b from start to end, read in the context ctx, which ID3v2.4 separates with terminators.

It leaves out empty strings at the end, since some writers end the last string with one or more terminators. When that leaves none, it returns one empty string. The :max-strings limit of the context counts the strings after the first of each frame, and past the limit, it stops.

terminator clj/s

(terminator b start end width)

Where the string at start in b ends: at its first terminator of width zero bytes, aligned for UTF-16, or at end when there's none before it.

text-encoding clj/s

(text-encoding ctx b)

The text encoding named by the first byte of b, the content of a frame, read in the context ctx.

With the quirk :id3/text-encoding, a byte that names none of ID3's encodings means ISO-8859-1. Without the quirk it throws, as it does for a frame without content.

utf8? clj/s

(utf8? b start end)

Whether the bytes of b from start to end are UTF-8 with one or more characters outside ASCII.

Bytes like these are almost certainly UTF-8, even when a frame declares another encoding.

version-encodings clj/s

The text encodings of each version that a writer can use.

width clj/s

(width encoding)

The width in bytes of the terminator of a string in encoding.