Skip to content

Time Intervals

Jump to bottom Edit New page
Mike Bostock edited this page Nov 6, 2013 · 27 revisions

Wiki ▸ API Reference ▸ Time ▸ Time Intervals

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.

Interval

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

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

# interval.round(date)

Rounds up or down the specified date, returning the closest time interval to 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)

Rounds up the specified date, returning the earliest time interval after or equal to date. For example, d3.time.day.ceil(new Date()) returns midnight (12:00 AM) on the following day, in local time (unless you happen to run this code at exactly midnight, in which case it returns the current 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. For example, d3.time.day.range(start, stop) returns local time days between start and stop, while d3.time.day.utc.range(start, stop) returns UTC days between start and stop.

Intervals

# d3.time.second

Seconds (e.g., 01:23:45.0000 AM). Always 1,000 milliseconds long.

# d3.time.minute

Minutes (e.g., 01:02:00 AM). Most browsers do not support leap seconds, so minutes are almost always 60 seconds (6e4 milliseconds) long.

# d3.time.hour

Hours (e.g., 01:00 AM). 60 minutes long (36e5 milliseconds). Note that advancing time by one hour can return the same hour number, or skip an hour number, due to Daylight Savings Time.

# d3.time.day

Days (e.g., February 7, 2012 at 12:00 AM). Most days are 24 hours long (864e5 milliseconds); however, with Daylight Savings Time, a day may be 23 or 25 hours long.

# d3.time.week

Alias for d3.time.sunday. A week is always 7 days, but ranges between 167 and 169 hours depending on Daylight Savings Time.

# d3.time.sunday

Sunday-based weeks (e.g., February 5, 2012 at 12:00 AM).

# d3.time.monday

Monday-based weeks (e.g., February 6, 2012 at 12:00 AM).

# d3.time.tuesday

Tuesday-based weeks (e.g., February 7, 2012 at 12:00 AM).

# d3.time.wednesday

Wednesday-based weeks (e.g., February 8, 2012 at 12:00 AM).

# d3.time.thursday

Thursday-based weeks (e.g., February 9, 2012 at 12:00 AM).

# d3.time.friday

Friday-based weeks (e.g., February 10, 2012 at 12:00 AM).

# d3.time.saturday

Saturday-based weeks (e.g., February 11, 2012 at 12:00 AM).

# d3.time.month

Months (e.g., February 1, 2012 at 12:00 AM). Ranges between 28 and 31 days.

# d3.time.year

Years (e.g., January 1, 2012 at 12:00 AM). Normal years are 365 days long; leap years are 366.

Aliases

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

Alias for d3.time.second.range. 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.minutes(start, stop[, step])

Alias for d3.time.minute.range. 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.hours(start, stop[, step])

Alias for d3.time.hour.range. 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.days(start, stop[, step])

Alias for d3.time.day.range. 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.weeks(start, stop[, step])
# d3.time.sundays(start, stop[, step])
# d3.time.mondays(start, stop[, step])
# d3.time.tuesdays(start, stop[, step])
# d3.time.wednesdays(start, stop[, step])
# d3.time.thursdays(start, stop[, step])
# d3.time.fridays(start, stop[, step])
# d3.time.saturdays(start, stop[, step])

Aliases for d3.time.interval.range etc. 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.months(start, stop[, step])

Alias for d3.time.month.range. 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.years(start, stop[, step])

Alias for d3.time.year.range. 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.

Counting

# d3.time.dayOfYear(date)

Returns the day number for the given date. The first day of the year (January 1) is always the 0th day. Unlike the d3.time.format's %j directive, dayOfYear is 0-based rather than 1-based.

# d3.time.weekOfYear(date)
# d3.time.sundayOfYear(date)
# d3.time.mondayOfYear(date)
# d3.time.tuesdayOfYear(date)
# d3.time.wednesdayOfYear(date)
# d3.time.thursdayOfYear(date)
# d3.time.fridayOfYear(date)
# d3.time.saturdayOfYear(date)

Returns the week number for the given date, where weeks start with the given day. The first day of the year (January 1) is always the 0th week. weekOfYear is an alias for sundayOfYear, which is equivalent to d3.time.format's %U directive. mondayOfYear is equivalent to d3.time.format's %W directive.

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