FormidableLabs/d3-time-format

Name: d3-time-format

Owner: Formidable

Description: A JavaScript time formatter and parser inspired by strftime and strptime.

Forked from: d3/d3-time-format

Created: 2015-08-11 00:22:25.0

Updated: 2015-08-11 00:22:26.0

Pushed: 2015-08-11 01:20:12.0

Homepage:

Size: 120

Language: JavaScript

GitHub Committers

UserMost Recent Commit# Commits

Other Committers

UserEmailMost Recent Commit# Commits

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 format function from a format specifier (a string with the desired format directives, indicated by %); then pass a date to the format function, which returns a string. For example, to convert the current date to a human-readable string:

f = format("%B %d, %Y");
w Date); // "June 30, 2015"

Format functions also support parsing as format.parse, so to convert a string back to a date:

f = format("%B %d, %Y");
rse("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:

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

tion multiFormat(date) {
turn (second(date) < date ? formatMillisecond
  : minute(date) < date ? formatSecond
  : hour(date) < date ? formatMinute
  : day(date) < date ? formatHour
  : month(date) < date ? (week(date) < date ? formatDay : formatWeek)
  : year(date) < date ? formatMonth
  : formatYear)(date);

This format is used by D3?s time scale to generate human-readable ticks.

Installing

If you use NPM, npm install d3-time-format. Otherwise, download the latest release.

API Reference

# format(specifier)

An alias for locale.format on the default U.S. English locale. Use localeFormat for a different built-in locale or to define a new locale.

# utcFormat(specifier)

An alias for locale.utcFormat on the default U.S. English locale. Use localeFormat for a different built-in locale or to define a new locale.

# isoFormat

The full ISO 8601 UTC time format function. Where available, this method will use Date.toISOString to format and 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 format:

isoFormat = utcFormat("%Y-%m-%dT%H:%M:%S.%LZ");

# locale.format(specifier)

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

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.

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

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

# locale.utcFormat(specifier)

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

# format(date)

Formats the specified date, returning the corresponding string.

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

atMonth(date); // "May"
atDay(date); // "Thursday"

# format.parse(string)

Parses the 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.

The %d and %e directives are considered equivalent for parsing.

# format.toString()

Returns this format?s specifier.

# localeFormat(definition)

Returns a locale object for the specified definition with locale.format and locale.utcFormat methods. If definition is a string, it is the name of a built-in locale:

Otherwise, the locale definition must include the following properties:

Changes from D3 3.x:
This work is supported by the National Institutes of Health's National Center for Advancing Translational Sciences, Grant Number U24TR002306. This work is solely the responsibility of the creators and does not necessarily represent the official views of the National Institutes of Health.