D3 · all subjects

d3-time-format

20 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Time formatting and parsing API

d3.timeFormat creates a time formatter (alias for locale.format on default locale). d3.timeParse creates a time parser (alias for locale.parse on default locale). d3.utcFormat creates a UTC formatter (alias for locale.utcFormat on default locale). d3.utcParse creates a UTC parser (alias for locale.utcParse on default locale). d3.isoFormat is an ISO 8601 UTC formatter. d3.isoParse is an ISO 8601 UTC parser.

Locale formatting and parsing methods

A locale object has methods: locale.format(specifier) creates a time formatter, locale.parse(specifier) creates a time parser, locale.utcFormat(specifier) creates a UTC formatter, locale.utcParse(specifier) creates a UTC parser. d3.timeFormatLocale(definition) defines a custom locale. d3.timeFormatDefaultLocale(definition) defines the default locale.

d3.timeFormat() function signature

d3.timeFormat(specifier) creates a formatter from a format specifier string and returns a function that formats a Date object to a string. It is an alias for locale.format() on the default locale. Example: d3.timeFormat("%b %d") returns a formatter function.

d3.timeParse() function signature

d3.timeParse(specifier) creates a parser from a format specifier string and returns a function that parses a string to a Date object or null. It is an alias for locale.parse() on the default locale. Example: d3.timeParse("%b %d") returns a parser function.

d3.utcParse() function signature

d3.utcParse(specifier) creates a UTC parser from a format specifier string and returns a function that parses a string to a Date object or null using UTC interpretation of all directives. It is an alias for locale.utcParse() on the default locale. Example: d3.utcParse("%b %d") returns a UTC parser function.

d3.isoFormat() function

d3.isoFormat(date) formats a Date as a full ISO 8601 UTC time string. Example: d3.isoFormat(new Date()) returns "2023-05-31T18:17:36.788Z". Uses Date.toISOString() where available.

d3.isoParse() function

d3.isoParse(string) parses a full ISO 8601 UTC time string and returns a Date object. Example: d3.isoParse("2023-05-31T18:17:36.788Z") returns a Date. Uses the Date constructor where available. For strict ISO 8601 validation, use d3.utcParse("%Y-%m-%dT%H:%M:%S.%LZ").

Time format directives

Format directives in d3-time-format: %a (abbreviated weekday name), %A (full weekday name), %b (abbreviated month name), %B (full month name), %c (locale date and time), %d (zero-padded day [01,31]), %e (space-padded day [ 1,31]), %f (microseconds [000000,999999]), %g (ISO week-based year without century [00,99]), %G (ISO week-based year with century), %H (24-hour [00,23]), %I (12-hour [01,12]), %j (day of year [001,366]), %m (month [01,12]), %M (minute [00,59]), %L (milliseconds [000,999]), %p (AM or PM), %q (quarter [1,4]), %Q (milliseconds since UNIX epoch), %s (seconds since UNIX epoch), %S (seconds [00,61]), %u (Monday-based weekday [1,7]), %U (Sunday-based week [00,53]), %V (ISO 8601 week [01,53]), %w (Sunday-based weekday [0,6]), %W (Monday-based week [00,53]), %x (locale date), %X (locale time), %y (year without century [00,99]), %Y (year with century), %Z (time zone offset), %% (literal percent).

Time format padding modifiers

Padding modifiers may follow the % sign in format directives: 0 (zero-padding), _ (space-padding), - (disable padding). Default is 0 for all directives except %e which defaults to _ (space-padding).

locale.format() method signature

locale.format(specifier) returns a new formatter function for the given format specifier string. The returned function takes a Date object and returns a formatted string. Example: const formatMonth = d3.timeFormat("%B"); formatMonth(new Date(2014, 4, 1)) returns "May".

locale.parse() method signature

locale.parse(specifier) returns a new parser function for the given format specifier string. The returned function takes a string and returns a Date object or null. Parsing is strict: the string must exactly match the specifier format. %d and %e directives are considered equivalent for parsing.

locale.utcFormat() method signature

locale.utcFormat(specifier) returns a new UTC formatter function equivalent to locale.format(), except all directives are interpreted as Coordinated Universal Time (UTC) rather than local time.

locale.utcParse() method signature

locale.utcParse(specifier) returns a new UTC parser function equivalent to locale.parse(), except all directives are interpreted as Coordinated Universal Time (UTC) rather than local time.

d3.timeFormatLocale() function signature

d3.timeFormatLocale(definition) returns a locale object with format, parse, utcFormat, and utcParse methods. The definition object must include: dateTime (date and time %c format), date (%x format), time (%X format), periods (AM/PM array), days (full weekday names starting with Sunday), shortDays (abbreviated weekday names starting with Sunday), months (full month names starting with January), shortMonths (abbreviated month names starting with January).

d3.timeFormatDefaultLocale() function signature

d3.timeFormatDefaultLocale(definition) is equivalent to d3.timeFormatLocale() but also redefines d3.timeFormat, d3.timeParse, d3.utcFormat, and d3.utcParse to use the new locale's methods. The definition object requires the same properties as timeFormatLocale. Defaults to U.S. English if not set.

Time format locale definition object structure

A locale definition object for d3.timeFormatLocale() or d3.timeFormatDefaultLocale() must contain: dateTime (string, format specifier for %c), date (string, format specifier for %x), time (string, format specifier for %X), periods (array of 2 strings for AM/PM equivalents), days (array of 7 strings for full weekday names starting with Sunday), shortDays (array of 7 strings for abbreviated weekday names starting with Sunday), months (array of 12 strings for full month names starting with January), shortMonths (array of 12 strings for abbreviated month names starting with January).

Locale-affected directives in time format

Directives marked with an asterisk are affected by the locale definition: %a, %A, %b, %B, %c, %p, %x, %X. These are the weekday names, month names, AM/PM labels, and locale-specific date/time formats.

Multi-scale time format example

Example of conditional time formatting by scale using d3-time intervals: const formatMillisecond = d3.utcFormat(".%L"), formatSecond = d3.utcFormat(":%S"), formatMinute = d3.utcFormat("%I:%M"), formatHour = d3.utcFormat("%I %p"), formatDay = d3.utcFormat("%a %d"), formatWeek = d3.utcFormat("%b %d"), formatMonth = d3.utcFormat("%B"), formatYear = d3.utcFormat("%Y"); function multiFormat(date) { return (d3.utcSecond(date) < date ? formatMillisecond : d3.utcMinute(date) < date ? formatSecond : d3.utcHour(date) < date ? formatMinute : d3.utcDay(date) < date ? formatHour : d3.utcMonth(date) < date ? (d3.utcWeek(date) < date ? formatDay : formatWeek) : d3.utcYear(date) < date ? formatMonth : formatYear)(date); }

Basic timeFormat and timeParse example

Example of formatting and parsing dates: const formatTime = d3.utcFormat("%B %d, %Y"); formatTime(new Date()); // "May 31, 2023" const parseTime = d3.utcParse("%B %d, %Y"); parseTime("June 30, 2015"); // Date object

Parse strictness rule

Time parsing is strict. If the specified string does not exactly match the associated specifier, parse returns null. For example, with specifier "%Y-%m-%dT%H:%M:%SZ", the string "2011-07-01T19:15:28Z" parses correctly, but "2011-07-01T19:15:28", "2011-07-01 19:15:28", or "2011-07-01" all return null.

Give your agent this brain