date

Parses numbers and strings into valid JavaScript Date objects, supporting years, quarters, months, and ISO 8601 formats.

Basic example

Turns the loose date values found in data files into Date objects: a bare year, a quarter in either order (Q3 2019 or 2019 Q3), a year-month, a MM/DD/YYYY string, an ISO string, or a millisecond timestamp (any integer longer than five digits). Charts run every time value through this before building a time axis.

import {date} from "@d3plus/dom";

date("2020"); // Wed Jan 01 2020
date("Q3 2019"); // Mon Jul 01 2019
date("2019-03"); // Fri Mar 01 2019
date("03/15/2019"); // Fri Mar 15 2019
date("2019-03-15T12:30:00"); // Fri Mar 15 2019
date(1577836800000); // Tue Dec 31 2019

Negative years

Years before zero are kept rather than being mangled by the native Date parser, so BCE timelines work: the year is read out of the string and set explicitly after parsing.

import {date} from "@d3plus/dom";

date("-500"); // getFullYear() → -500
date("1/1/-200"); // getFullYear() → -200
date("Q1 -44"); // getFullYear() → -44

Parameters

import {date} from "@d3plus/dom";

drequiredstring | number | false | undefined

The date value to parse (number, string, or Date).