d3-time-format

What is d3-time-format?

The d3-time-format package is a JavaScript library for parsing and formatting dates. It is part of the D3.js collection of tools for data visualization, but it can be used independently for dealing with date and time formatting. It provides a way to specify custom formats for dates and times, as well as parse strings into date objects based on these formats.

What are d3-time-format's main functionalities?

Formatting Dates

This feature allows you to format a JavaScript Date object into a string based on a specifier string. The specifier controls how various parts of the date are displayed.

"%Y-%m-%d".format(new Date())

Parsing Dates

This feature enables you to parse a string representing a date into a JavaScript Date object using a format specifier that matches the format of the string.

d3.timeParse("%Y-%m-%d")("2023-04-01")

Locale Support

This feature allows you to use locale-specific date and time formatting. You can define your own locale with custom time formatting symbols, or use predefined locales.

d3.timeFormatLocale(locale).format("%c")(new Date())

Other packages similar to d3-time-format

moment

Moment.js is a legacy package for date and time manipulation and formatting. It offers a wide range of functionalities similar to d3-time-format but is no longer recommended for new projects due to its size and the availability of more modern alternatives.

date-fns

date-fns provides a collection of simple, pure functions for manipulating JavaScript dates. It is modular and has a similar scope to d3-time-format, but it is designed to be more lightweight and with a functional programming approach.

luxon

Luxon is a powerful, modern library for working with dates and times. It offers a fluent API and comprehensive time zone support. Compared to d3-time-format, Luxon provides more extensive functionality around date arithmetic, parsing, and internationalization.

dayjs

Day.js is a minimalist library that parses, validates, manipulates, and displays dates and times for modern browsers with a largely Moment.js-compatible API. It is lightweight and can be a good alternative to d3-time-format for simple date formatting and parsing tasks.

README

d3-time-format

This module provides a JavaScript implementation of the venerable strptime and strftime functions from the C standard library, and can be used to parse or format dates in a variety of locale-specific representations. To format a date, create a formatter from a specifier (a string with the desired format directives, indicated by %); then pass a date to the formatter, which returns a string. For example, to convert the current date to a human-readable string:

var formatTime = d3.timeFormat("%B %d, %Y");
formatTime(new Date); // "June 30, 2015"

Likewise, to convert a string back to a date, create a parser:

var parseTime = d3.timeParse("%B %d, %Y");
parseTime("June 30, 2015"); // Tue Jun 30 2015 00:00:00 GMT-0700 (PDT)

You can implement more elaborate conditional time formats, too. For example, here’s a multi-scale time format using time intervals:

var formatMillisecond = d3.timeFormat(".%L"),
    formatSecond = d3.timeFormat(":%S"),
    formatMinute = d3.timeFormat("%I:%M"),
    formatHour = d3.timeFormat("%I %p"),
    formatDay = d3.timeFormat("%a %d"),
    formatWeek = d3.timeFormat("%b %d"),
    formatMonth = d3.timeFormat("%B"),
    formatYear = d3.timeFormat("%Y");

function multiFormat(date) {
  return (d3.timeSecond(date) < date ? formatMillisecond
      : d3.timeMinute(date) < date ? formatSecond
      : d3.timeHour(date) < date ? formatMinute
      : d3.timeDay(date) < date ? formatHour
      : d3.timeMonth(date) < date ? (d3.timeWeek(date) < date ? formatDay : formatWeek)
      : d3.timeYear(date) < date ? formatMonth
      : formatYear)(date);
}

This module is used by D3 time scales to generate human-readable ticks.

Installing

If you use NPM, npm install d3-time-format. Otherwise, download the latest release. You can also load directly from d3js.org, either as a standalone library or as part of D3. AMD, CommonJS, and vanilla environments are supported. In vanilla, a d3 global is exported:

<script src="https://d3js.org/d3-time.v1.min.js"></script>
<script src="https://d3js.org/d3-time-format.v2.min.js"></script>
<script>

var format = d3.timeFormat("%x");

</script>

Locale files are published to npm and can be loaded using d3.json. For example, to set Russian as the default locale:

d3.json("https://cdn.jsdelivr.net/npm/d3-time-format@2/locale/ru-RU.json", function(error, locale) {
  if (error) throw error;

  d3.timeFormatDefaultLocale(locale);

  var format = d3.timeFormat("%c");

  console.log(format(new Date)); // понедельник,  5 декабря 2016 г. 10:31:59
});

API Reference

# d3.timeFormat(specifier) <>

An alias for locale.format on the default locale.

# d3.timeParse(specifier) <>

An alias for locale.parse on the default locale.

# d3.utcFormat(specifier) <>

An alias for locale.utcFormat on the default locale.

# d3.utcParse(specifier) <>

An alias for locale.utcParse on the default locale.

# d3.isoFormat <>

The full ISO 8601 UTC time formatter. Where available, this method will use Date.toISOString to format.

# d3.isoParse <>

The full ISO 8601 UTC time parser. Where available, this method will use the Date constructor to parse strings. If you depend on strict validation of the input format according to ISO 8601, you should construct a UTC parser function:

var strictIsoParse = d3.utcParse("%Y-%m-%dT%H:%M:%S.%LZ");

# locale.format(specifier) <>

Returns a new formatter for the given string specifier. The specifier string may contain the following directives:

• %a - abbreviated weekday name.*
• %A - full weekday name.*
• %b - abbreviated month name.*
• %B - full month name.*
• %c - the locale’s date and time, such as %x, %X.*
• %d - zero-padded day of the month as a decimal number [01,31].
• %e - space-padded day of the month as a decimal number [ 1,31]; equivalent to %_d.
• %f - microseconds as a decimal number [000000, 999999].
• %H - hour (24-hour clock) as a decimal number [00,23].
• %I - hour (12-hour clock) as a decimal number [01,12].
• %j - day of the year as a decimal number [001,366].
• %m - month as a decimal number [01,12].
• %M - minute as a decimal number [00,59].
• %L - milliseconds as a decimal number [000, 999].
• %p - either AM or PM.*
• %q - quarter of the year as a decimal number [1,4].
• %Q - milliseconds since UNIX epoch.
• %s - seconds since UNIX epoch.
• %S - second as a decimal number [00,61].
• %u - Monday-based (ISO 8601) weekday as a decimal number [1,7].
• %U - Sunday-based week of the year as a decimal number [00,53].
• %V - ISO 8601 week of the year as a decimal number [01, 53].
• %w - Sunday-based weekday as a decimal number [0,6].
• %W - Monday-based week of the year as a decimal number [00,53].
• %x - the locale’s date, such as %-m/%-d/%Y.*
• %X - the locale’s time, such as %-I:%M:%S %p.*
• %y - year without century as a decimal number [00,99].
• %Y - year with century as a decimal number, such as 1999.
• %Z - time zone offset, such as -0700, -07:00, -07, or Z.
• %% - a literal percent sign (%).

Directives marked with an asterisk (*) may be affected by the locale definition.

For %U, all days in a new year preceding the first Sunday are considered to be in week 0. For %W, all days in a new year preceding the first Monday are considered to be in week 0. Week numbers are computed using interval.count. For example, 2015-52 and 2016-00 represent Monday, December 28, 2015, while 2015-53 and 2016-01 represent Monday, January 4, 2016. This differs from the ISO week date specification (%V), which uses a more complicated definition!

For %V, per the strftime man page:

In this system, weeks start on a Monday, and are numbered from 01, for the first week, up to 52 or 53, for the last week. Week 1 is the first week where four or more days fall within the new year (or, synonymously, week 01 is: the first week of the year that contains a Thursday; or, the week that has 4 January in it).

The % sign indicating a directive may be immediately followed by a padding modifier:

• 0 - zero-padding
• _ - space-padding
• - - disable padding

If no padding modifier is specified, the default is 0 for all directives except %e, which defaults to _. (In some implementations of strftime and strptime, a directive may include an optional field width or precision; this feature is not yet implemented.)

The returned function formats a specified date, returning the corresponding string.

var formatMonth = d3.timeFormat("%B"),
    formatDay = d3.timeFormat("%A"),
    date = new Date(2014, 4, 1); // Thu May 01 2014 00:00:00 GMT-0700 (PDT)

formatMonth(date); // "May"
formatDay(date); // "Thursday"

# locale.parse(specifier) <>

Returns a new parser for the given string specifier. The specifier string may contain the same directives as locale.format. The %d and %e directives are considered equivalent for parsing.

The returned function parses a specified string, returning the corresponding date or null if the string could not be parsed according to this format’s specifier. Parsing is strict: if the specified string does not exactly match the associated specifier, this method returns null. For example, if the associated specifier is %Y-%m-%dT%H:%M:%SZ, then the string "2011-07-01T19:15:28Z" will be parsed as expected, but "2011-07-01T19:15:28", "2011-07-01 19:15:28" and "2011-07-01" will return null. (Note that the literal Z here is different from the time zone offset directive %Z.) If a more flexible parser is desired, try multiple formats sequentially until one returns non-null.

# locale.utcFormat(specifier) <>

Equivalent to locale.format, except all directives are interpreted as Coordinated Universal Time (UTC) rather than local time.

# locale.utcParse(specifier) <>

Equivalent to locale.parse, except all directives are interpreted as Coordinated Universal Time (UTC) rather than local time.

Locales

# d3.timeFormatLocale(definition) <>

Returns a locale object for the specified definition with locale.format, locale.parse, locale.utcFormat, locale.utcParse methods. The definition must include the following properties:

• dateTime - the date and time (%c) format specifier (e.g., "%a %b %e %X %Y").
• date - the date (%x) format specifier (e.g., "%m/%d/%Y").
• time - the time (%X) format specifier (e.g., "%H:%M:%S").
• periods - the A.M. and P.M. equivalents (e.g., ["AM", "PM"]).
• days - the full names of the weekdays, starting with Sunday.
• shortDays - the abbreviated names of the weekdays, starting with Sunday.
• months - the full names of the months (starting with January).
• shortMonths - the abbreviated names of the months (starting with January).

For an example, see Localized Time Axis II.

# d3.timeFormatDefaultLocale(definition) <>

Equivalent to d3.timeFormatLocale, except it also redefines d3.timeFormat, d3.timeParse, d3.utcFormat and d3.utcParse to the new locale’s locale.format, locale.parse, locale.utcFormat and locale.utcParse. If you do not set a default locale, it defaults to U.S. English.

For an example, see Localized Time Axis.