d4_time library

A calculator for humanity’s peculiar conventions of time.

When visualizing time series data, analyzing temporal patterns, or working with time in general, the irregularities of conventional time units quickly become apparent. In the Gregorian calendar, for example, most months have 31 days but some have 28, 29 or 30; most years have 365 days but leap years have 366; and with daylight saving, most days have 24 hours but some have 23 or 25. Adding to complexity, daylight saving conventions vary around the world.

As a result of these temporal peculiarities, it can be difficult to perform seemingly-trivial tasks. For example, if you want to compute the number of days that have passed between two dates, you can’t simply subtract and divide by 24 hours (86,400,000 ms):

final start = DateTime(2015, 3, 01); // 2015-03-01T00:00
final end = new Date(2015, 4, 01); // 2015-04-01T00:00
final days = (end - start) / 864e5; // 30.958333333333332, oops! 🤯

You can, however, use timeDay.count:

timeDay.count(start, end) // 31 😌

The day interval is one of several provided by d4_time. Each interval represents a conventional unit of time — hours, weeks, months, etc. — and has methods to calculate boundary dates. For example, timeDay computes midnight (typically 12:00 AM local time) of the corresponding day. In addition to rounding and counting, intervals can also be used to generate lists of boundary dates. For example, to compute each Sunday in the current month:

final start = timeMonth.floor(DateTime(2015, 1, 15)); // 2015-01-01T00:00
final stop = timeMonth.ceil(DateTime(2015, 1, 15)); // 2015-02-01T00:00
final weeks = timeWeek.range(start, stop); // [2015-01-04T00:00, 2015-01-11T00:00, 2015-01-18T00:00, 2015-01-25T00:00]

The d4_time package does not implement its own calendaring system; it merely implements a convenient API for calendar math on top of DateTime. Thus, it ignores leap seconds and can only work with the local time zone and Coordinated Universal Time (UTC).

This package is used by D4’s time scales to generate sensible ticks, by D4’s time format, and can also be used directly to do things like calendar layouts.

Classes

TimeInterval
Time intervals provide a convenient and flexible API for date calculations based on conventional or custom units of time on top of DateTime.

Properties

timeDay → TimeInterval
Days (e.g., February 7, 2012 at 12:00 AM); typically 24 hours. Days in local time may range from 23 to 25 hours due to daylight saving.
final
timeDays → List<DateTime> Function(DateTime start, DateTime stop, [num step = 1])
Alias for timeDay.range.
final
timeFriday → TimeInterval
Friday-based weeks (e.g., February 10, 2012 at 12:00 AM).
final
timeFridays → List<DateTime> Function(DateTime start, DateTime stop, [num step = 1])
Alias for timeFridays.range.
final
timeHour → TimeInterval
Hours (e.g., 01:00 AM); 60 minutes. Note that advancing time by one hour in local time can return the same hour or skip an hour due to daylight saving.
final
timeHours → List<DateTime> Function(DateTime start, DateTime stop, [num step = 1])
Alias for timeHour.range.
final
timeMillisecond → _TimeMillisecond
Milliseconds; the shortest available time unit.
final
timeMilliseconds → List<DateTime> Function(DateTime start, DateTime stop, [num step = 1])
Alias for timeMillisecond.range.
final
timeMinute → TimeInterval
Minutes (e.g., 01:02:00 AM); 60 seconds. Note that DateTime class ignores leap seconds.
final
timeMinutes → List<DateTime> Function(DateTime start, DateTime stop, [num step = 1])
Alias for timeMinute.range.
final
timeMonday → TimeInterval
Monday-based weeks (e.g., February 6, 2012 at 12:00 AM).
final
timeMondays → List<DateTime> Function(DateTime start, DateTime stop, [num step = 1])
Alias for timeMondays.range.
final
timeMonth → TimeInterval
Months (e.g., February 1, 2012 at 12:00 AM); ranges from 28 to 31 days.
final
timeMonths → List<DateTime> Function(DateTime start, DateTime stop, [num step = 1])
Alias for timeMonth.range.
final
timeSaturday → TimeInterval
Saturday-based weeks (e.g., February 11, 2012 at 12:00 AM).
final
timeSaturdays → List<DateTime> Function(DateTime start, DateTime stop, [num step = 1])
Alias for timeSaturdays.range.
final
timeSecond → TimeInterval
Seconds in local time (e.g., 01:23:45.0000 AM); 1,000 milliseconds.
final
timeSeconds → List<DateTime> Function(DateTime start, DateTime stop, [num step = 1])
Alias for timeSecond.range.
final
timeSunday → TimeInterval
Sunday-based weeks (e.g., February 5, 2012 at 12:00 AM).
final
timeSundays → List<DateTime> Function(DateTime start, DateTime stop, [num step = 1])
Alias for timeSundays.range.
final
timeThursday → TimeInterval
Thursday-based weeks (e.g., February 9, 2012 at 12:00 AM).
final
timeThursdays → List<DateTime> Function(DateTime start, DateTime stop, [num step = 1])
Alias for timeThursdays.range.
final
timeTuesday → TimeInterval
Tuesday-based weeks (e.g., February 7, 2012 at 12:00 AM).
final
timeTuesdays → List<DateTime> Function(DateTime start, DateTime stop, [num step = 1])
Alias for timeTuesdays.range.
final
timeWednesday → TimeInterval
Wednesday-based weeks (e.g., February 8, 2012 at 12:00 AM).
final
timeWednesdays → List<DateTime> Function(DateTime start, DateTime stop, [num step = 1])
Alias for timeWednesdays.range.
final
timeWeek → TimeInterval
Alias for timeSunday; 7 days and typically 168 hours. Weeks in local time may range from 167 to 169 hours due to daylight saving.
final
timeWeeks → List<DateTime> Function(DateTime start, DateTime stop, [num step = 1])
Alias for timeWeeks.range.
final
timeYear → _TimeYear
Years (e.g., January 1, 2012 at 12:00 AM); ranges from 365 to 366 days.
final
timeYears → List<DateTime> Function(DateTime start, DateTime stop, [num step = 1])
Alias for timeYear.range.
final

Functions

timeRange(DateTime start, DateTime stop, TimeInterval interval) → List<DateTime>
Equivalent to timeTicks, but takes a time interval instead of count.
timeTickInterval(DateTime start, DateTime stop, num count) → TimeInterval?
Returns the time interval that would be used by timeTicks given the same arguments.
timeTicks(DateTime start, DateTime stop, num count) → List<DateTime>
Returns an list of approximately count dates at regular intervals between start and stop (inclusive).