Module date_format 

How a source spells a day — the format a design states, read once and handed to every engine as a list rather than as text.

One import arrives with 1/1/2015 in one column and 2015-01-01T00:00:00Z in the next, and a warehouse that converts either of them by asking the engine to guess gets a different answer on every engine and on some of them a different answer on a different server. So the design says the spelling, and this is what the spelling is.

Why a list and not a string

No two engines share a pattern language. %m/%d/%Y is MM/DD/YYYY on one family, MM/dd/yyyy on another, and a style number on a third. Handing the authored text through to an engine would mean each engine parsing it again, each one accepting a slightly different set of directives, and a directive nobody supports arriving at the database rather than at the door. Reading it once, here, gives every engine the same list to translate directive by directive — and gives a directive an engine cannot spell a refusal that names it.

The two patterns

Some engines answer nothing for a value they cannot read; some read it anyway and hand back the wrong day. For the second kind a guard has to be written beside the parse, and it has to come from the same list, or the guard and the parse would be two opinions about one spelling. DateFormat::shape_pattern is that guard, and DateFormat::capture_pattern reads one field back out of the value so a parse can be checked against what was written.

Structs

DateFormat

A source’s spelling, read once.

Enums

DateFormatError

What is wrong with a format, in the words the refusal uses.

FormatDirective

One thing a format says, in the strftime family’s own vocabulary.

FormatPart

One piece of a format: something the source writes literally, or one of the things the format says.