Represents a DateTime which is ambiguous due to timezone rules.

ambiguity-1-non-existent-times

Ambiguity #1 - Non-existent times

Let's use American daylight savings time rules as our example here, using America/Chicago as our example. Central Standard Time for that zone ends at 2:00 AM, but Central Daylight Time does not begin until 3:00 AM, this is because at 2:00 AM, our clocks "spring forward" - which is just an easy way of remembering that the offset goes from -6 from UTC, to -5 from UTC. Since there is no timezone period associated with the hours of 2-3 AM in the America/Chicago zone (it's neither CST nor CDT during that hour), one has to decide what the intent is. Timex makes the call that shifting to the next period (i.e. "spring forward" using our example above) makes the most logical sense when working with non-existent time periods.

TL;DR - Timex will "spring forward" or "fall back", depending on what the zone change happens to be for the non-existent time. Using America/Chicago as an example, if you try to create a DateTime for 2 AM on March 13, 2016, Timex will give you back 3 AM on March 13, 2016, because the zone is in the middle of changing from CST to CDT, and the earliest representable time in CDT is 3 AM.

ambiguity-2-times-with-more-than-one-valid-zone-period

Ambiguity #2 - Times with more than one valid zone period

This one is the reason why this module exists. There are times, though rare, where more than one zone applies to a given date and time. For example, Asia/Taipei, on December 31st, 1895, from 23:54:00 to 23:59:59, two timezone periods are active LMT, and JWST, because that locale was switching to JWST from LMT. Because of this, it's impossible to know programmatically which zone is desired. The programmer must make a choice on which zone they want to use.

For this use case, Timex will return an AmbiguousDateTime any time you try to create a DateTime, or shift a DateTime, to an ambiguous time period. It has two fields, :before, containing a DateTime configured in the timezone occurring before the ambiguous period, and :after, containing a DateTime configured in the timezone occurring after the ambiguous period. It is up to you as the programmer to decide which DateTime is the one to use, but my recommendation is to choose :after, unless you have a specific reason to use :before.