Skip to content

Time Intervals

Jump to bottom Edit New page
mbostock edited this page Feb 25, 2012 · 27 revisions

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.interval

Returns the specified interval. The following intervals are supported:

# interval(date)

Alias for interval.floor(date). For example, d3.time.day(new Date()) returns midnight (12:00 AM) on the current day, in local time.

# interval.floor(date)

Returns the latest time interval before or equal to the specified date. For example, d3.time.day.floor(new Date()) returns midnight (12:00 AM) on the current day, in local time.

# interval.round(date)

Returns the closest time interval to the specified date. For example, d3.time.day.round(new Date()) returns midnight (12:00 AM) on the current day if it is on or before noon, and midnight of the following day if it is after noon.

# interval.ceil(date)

Returns the earliest time interval after the specified date. For example, d3.time.day.ceil(new Date()) returns midnight (12:00 AM) on the following day, in local time.

# interval.range(start, stop[, step])

Returns every time interval after or equal to start and before stop. If step is specified, then every step'th interval will be returned, based on the interval number (such as day of month for d3.time.day). For example, a step of 2 will return the 1st, 3rd, 5th etc. of the month with d3.time.day.

# interval.offset(date, step)

Returns a new date equal to date plus step intervals. If step is negative, then the returned date will be before the specified date; if step is zero, then a copy of the specified date is returned. This method does not round the specified date to the interval. For example, if it is currently 5:34 PM, then d3.time.day.offset(new Date(), 1) returns 5:34 PM tomorrow (even if Daylight Savings Time changes!).

# interval.utc

Returns a corresponding time interval in UTC rather than local time.

# 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.

Add a custom footer
Add a custom sidebar
Clone this wiki locally