Time Intervals

API Reference ▸ Time

Time intervals are irregular! For example, there are 60 seconds in a minute, but 24 hours in a day. Even more confusing, some days have 23 or 25 hours due to daylight saving time, and the standard Gregorian calendar uses months of differing lengths. And then there are leap years and leap seconds!

To simplify manipulation of and iteration over time intervals, D3 provides a handful of time utilities in addition to the time scale and format. The utilities support both local time and UTC time. Local time is determined by the browser's JavaScript runtime; arbitrary time zone support would be nice, but requires access to the Olson zoneinfo files.

# d3.time.day(date)
# d3.time.day.utc(date)

Returns the latest day boundary (midnight) before or equal to date.

# d3.time.days(start, stop[, step])
# d3.time.days.utc(start, stop[, step])

Returns the day boundaries (midnight) after or equal to start and before stop. If step is specified, then every step'th date will be returned, based on the day of the month. For example, a step of 2 will return the 1st, 3rd, 5th etc. of the month.

# d3.time.hour(date)
# d3.time.hour.utc(date)

Returns the latest hour boundary (e.g., 01 AM) before or equal to date.

# d3.time.hours(start, stop[, step])
# d3.time.hours.utc(start, stop[, step])

Returns the hour boundaries (e.g., 01 AM) after or equal to start and before stop. If step is specified, then every step'th hour will be returned, based on the hour of the day. For example, a step of 3 will return 9 PM, 12 AM, 3 AM, etc.

# d3.time.minute(date)
# d3.time.minute.utc(date)

Returns the latest minute boundary (e.g., 01:23 AM) before or equal to date.

# d3.time.minutes(start, stop[, step])
# d3.time.minutes.utc(start, stop[, step])

Returns the minute boundaries (e.g., 01:23 AM) after or equal to start and before stop. If step is specified, then every step'th minute will be returned, based on the minute of the hour. For example, a step of 15 will return 9:45 PM, 10:00 PM, 10:15 PM, etc.

# d3.time.month(date)
# d3.time.month.utc(date)

Returns the latest month boundary (e.g., January 01) before or equal to date.

# d3.time.months(start, stop[, step])
# d3.time.months.utc(start, stop[, step])

Returns the month boundaries (e.g., January 01) after or equal to start and before stop. If step is specified, then every step'th month will be returned, based on the month of the year. For example, a step of 3 will return January, April, July, etc.

# d3.time.second(date)
# d3.time.second.utc(date)

Returns the latest second boundary (e.g., 01:23:45 AM) before or equal to date.

# d3.time.seconds(start, stop[, step])
# d3.time.seconds.utc(start, stop[, step])

Returns the second boundaries (e.g., 01:23:45 AM) after or equal to start and before stop. If step is specified, then every step'th second will be returned, based on the second of the minute. For example, a step of 15 will return 9:01:45 PM, 9:02:00 PM, 9:02:15 PM, etc.

# d3.time.week(date)
# d3.time.week.utc(date)

Returns the latest week boundary (midnight Sunday) before or equal to date.

# d3.time.weeks(start, stop[, step])
# d3.time.weeks.utc(start, stop[, step])

Returns the week boundaries (midnight Sunday) after or equal to start and before stop. If step is specified, then every step'th week will be returned, based on the week of the year. For example, a step of 4 will return January 2, January 30, February 27, etc.

# d3.time.year(date)
# d3.time.year.utc(date)

Returns the latest year boundary (midnight January 1st) before or equal to date.

# d3.time.years(start, stop[, step])
# d3.time.years.utc(start, stop[, step])

Returns the year boundaries (midnight January 1st) after or equal to start and before stop. If step is specified, then every step'th year will be returned. For example, a step of 5 will return 2010, 2015, 2020, etc.