Readwyn 0.1.0

How Readwyn reads calibre published dates in any time zone

When Readwyn imports a calibre library, each book’s published date comes over as the date you entered in calibre. Readwyn stores it as a calendar day with no time attached, so a Mac in Tokyo and a Mac in New York show the same day.

Why a date can move by a day

A date kept as a moment in time, at midnight, belongs to one time zone. To the west of that zone, the same moment is still the evening before. Read it in the wrong zone and 29 April turns into 28 April.

calibre keeps a published date as a moment at midnight, and which midnight depends on where the date came from: a date read from a book file is local midnight on the computer that read it, and a date set with calibredb is midnight UTC.

What the import does

The import checks which midnight each date is stored at:

Stored timeDay that Readwyn keeps
Local midnight of this MacThe local date
Midnight UTCThe UTC date
Any other timeThe local date

Say a book’s published date is 29 April 2003, set with calibredb, so it’s stored as midnight UTC. On a Mac in New York that moment is 8 pm on 28 April, but Readwyn sees that it’s midnight UTC and keeps 29 April.

What the library stores

Once imported, the published date has no time at all. It can be a year, a month and a year, or a full date, stored as YYYY, YYYY-MM or YYYY-MM-DD, and nothing about it depends on the clock of the Mac that shows it.

On the book screen the year comes first in the line under the author: “1871 · ~880 pages · English · EPUB, 1.8 MB”.

The book screen of Middlemarch: under the author, 1871, about 880 pages, English and EPUB
The published year, 1871, first in the line under the author

Reader apps that browse your library over OPDS see that same day as the book’s publication date.

Correcting a date by hand

If a date was already wrong in calibre, fix it in Readwyn:

  1. Open the book and choose “Edit details” (or press ⌘E).
  2. Type the date into the published date field. It accepts a year (“1871”), a month and a year (“Apr 2003”), or a full date (“29 Apr 2003”).
  3. Choose “Save 1 change”, or press Return. Until you do, the field shows “Was” with the old date struck through, and “Undo”.

Dates of finished reads

Finished reads follow a similar rule. calibre, Goodreads and a Kobo record when you finished a book as a date, not a time. Reading stats take a read that finished at exactly 00:00:00 UTC to be one of those dates, and count it on its UTC date wherever you are. Without that rule, a book finished on 1 January would land in the previous year for anyone west of UTC. A read with a real time counts on its local day.