Module paper32 

Paper32: bytes as rows of base-32 characters a person writes down and types back, with parity that repairs a slip and refuses a row it cannot repair.

The alphabet is Crockford’s base 32, 0-9 and the letters without I, L, O and U, one character per five bits. The decoder takes either case and reads O as 0 and I or L as 1, since those are what a hand writes for them; a ? is a character the person could not read, an erasure, and so is a U, which stands for one character but not which. Spaces and separators between groups are ignored; any other character is refused where it stands.

The characters go in rows of 32: 28 of data and 4 of parity, the last row shorter and still ending in its 4 parity characters. Each row is a Reed-Solomon codeword over GF(32): the data characters fix a polynomial of degree below their count, evaluated at the first points of a fixed order of the 32 field elements, and the parity characters are that polynomial at the last four points. Any four characters of a row determine the other 28, so a row repairs one wrong character or two unreadable ones and still has two characters of parity to check the repair against. Beyond that it is refused by name: a row that cannot be trusted is one the person reads again, not one the code guesses.

A correct sheet decodes without any of this: drop the last four characters of each row and read the rest as base 32.

Structs

Decoded

What decode read.

Repair

A repair made to one row.

RowRead

What read_row read.

Enums

RepairKind

What a row needed.

RowError

Why rows did not read back.

Constants

ROW_DATA

Data characters in a full row.

ROW_LEN

Characters in a full row.

ROW_PARITY

Parity characters closing every row.

Functions

decode

Read rows back. The result carries the bytes and what was repaired, so the person can be told which rows needed it.

encode

Write bytes as rows, one string with no separators. Grouping for the eye is the caller’s, since it does not take part in the encoding.

read_row

One row as typed, read on its own, for a frontend that takes a value a row at a time and says at once which row needs another look. decode reads the whole value; this checks a row the same way. row is the row’s number from 1, for the repair and the error to name.