Skip to content

Commit

Permalink
Update README.
Browse files Browse the repository at this point in the history
  • Loading branch information
@mbostock
mbostock committed Dec 18, 2015
1 parent 5056e3d commit 4957581
Show file tree
Hide file tree
Showing 2 changed files with 56 additions and 57 deletions.
109 changes: 54 additions & 55 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,62 +3,69 @@
This module provides a JavaScript implementation of the venerable [strptime](http://pubs.opengroup.org/onlinepubs/009695399/functions/strptime.html) and [strftime](http://pubs.opengroup.org/onlinepubs/007908799/xsh/strftime.html) functions from the C standard library, and can be used to parse or format [dates](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) in a variety of locale-specific representations. To format a date, create a [*format* function](#_format) from a [format specifier](#locale_format) (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:

```js
var f = format("%B %d, %Y");
var f = d3_time_format.format("%B %d, %Y");
f(new Date); // "June 30, 2015"
```

Format functions also support parsing as [*format*.parse](#format_parse), so to convert a string back to a date:

```js
var f = format("%B %d, %Y");
var f = d3_time_format.format("%B %d, %Y");
f.parse("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](http://bl.ocks.org/mbostock/4149176) using [time intervals](https://github.com/d3/d3-time):

```js
var 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");
var formatMillisecond = d3_time_format.format(".%L"),
formatSecond = d3_time_format.format(":%S"),
formatMinute = d3_time_format.format("%I:%M"),
formatHour = d3_time_format.format("%I %p"),
formatDay = d3_time_format.format("%a %d"),
formatWeek = d3_time_format.format("%b %d"),
formatMonth = d3_time_format.format("%B"),
formatYear = d3_time_format.format("%Y");

function multiFormat(date) {
return (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
return (d3_time.second(date) < date ? formatMillisecond
: d3_time.minute(date) < date ? formatSecond
: d3_time.hour(date) < date ? formatMinute
: d3_time.day(date) < date ? formatHour
: d3_time.month(date) < date ? (d3_time.week(date) < date ? formatDay : formatWeek)
: d3_time.year(date) < date ? formatMonth
: formatYear)(date);
}
```

This format is used by D3’s time scale to generate human-readable ticks.
This module is used by D3 [time scales](https://github.com/d3/d3-scales#time-scales) to generate human-readable ticks.

## Installing

If you use NPM, `npm install d3-time-format`. Otherwise, download the [latest release](https://github.com/d3/d3-time-format/releases/latest).
If you use NPM, `npm install d3-time-format`. Otherwise, download the [latest release](https://github.com/d3/d3-time-format/releases/latest). The released bundle supports AMD, CommonJS, and vanilla environments. Create a custom build using [Rollup](https://github.com/rollup/rollup) or your preferred bundler. You can also load directly from [d3js.org](https://d3js.org):

```html
<script src="https://d3js.org/d3-time.v0.1.min.js"></script>
<script src="https://d3js.org/d3-time-format.v0.2.min.js"></script>
```

In a vanilla environment, a `d3_time_format` global is exported. [Try d3-time-format in your browser.](https://tonicdev.com/npm/d3-time-format)

## API Reference

<a name="format" href="#format">#</a> <b>format</b>(<i>specifier</i>)
<a name="format" href="#format">#</a> d3_time_format.<b>format</b>(<i>specifier</i>)

An alias for [*locale*.format](#locale_format) on the [U.S. English locale](#localeEnUs). See the other [locales](#locales), or use [locale](#locale) to define a new locale.

<a name="utcFormat" href="#utcFormat">#</a> <b>utcFormat</b>(<i>specifier</i>)
<a name="utcFormat" href="#utcFormat">#</a> d3_time_format.<b>utcFormat</b>(<i>specifier</i>)

An alias for [*locale*.utcFormat](#locale_utcFormat) on the [U.S. English locale](#localeEnUs). See the other [locales](#locales), or use [locale](#locale) to define a new locale.

<a name="isoFormat" href="#isoFormat">#</a> <b>isoFormat</b>
<a name="isoFormat" href="#isoFormat">#</a> d3_time_format.<b>isoFormat</b>

The full [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) UTC time [*format* function](#_format). Where available, this method will use [Date.toISOString](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Date/toISOString) to format and the [Date constructor](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Date) to parse strings. If you depend on strict validation of the input format according to ISO 8601, you should construct a [UTC format](#utcFormat):

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

<a name="locale_format" href="#locale_format">#</a> <i>locale</i>.<b>format</b>(<i>specifier</i>)
Expand Down Expand Up @@ -109,8 +116,8 @@ Equivalent to [*locale*.format](#locale_format), except all directives are inter
Formats the specified *[date](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date)*, returning the corresponding string.

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

formatMonth(date); // "May"
Expand All @@ -131,7 +138,7 @@ Returns this format’s specifier.

### Locales

<a name="locale" href="#locale">#</a> <b>locale</b>(<i>definition</i>)
<a name="locale" href="#locale">#</a> d3_time_format.<b>locale</b>(<i>definition</i>)

Returns a *locale* object for the specified *definition* with [*locale*.format](#locale_format) and [*locale*.utcFormat](#locale_utcFormat) methods. The *definition* must include the following properties:

Expand All @@ -144,98 +151,90 @@ Returns a *locale* object for the specified *definition* with [*locale*.format](
* `months` - the full names of the months (starting with January).
* `shortMonths` - the abbreviated names of the months (starting with January).

<a name="localeCaEs" href="#localeCaEs">#</a> <b>localeCaEs</b>
<a name="localeCaEs" href="#localeCaEs">#</a> d3_time_format.<b>localeCaEs</b>

[Catalan (Spain)](https://github.com/d3/d3-time-format/tree/master/src/locale/ca-ES.js)

<a name="localeDeCh" href="#localeDeCh">#</a> <b>localeDeCh</b>
<a name="localeDeCh" href="#localeDeCh">#</a> d3_time_format.<b>localeDeCh</b>

[German (Switzerland)](https://github.com/d3/d3-time-format/tree/master/src/locale/de-CH.js)

<a name="localeDeDe" href="#localeDeDe">#</a> <b>localeDeDe</b>
<a name="localeDeDe" href="#localeDeDe">#</a> d3_time_format.<b>localeDeDe</b>

[German (Germany)](https://github.com/d3/d3-time-format/tree/master/src/locale/de-DE.js)

<a name="localeEnCa" href="#localeEnCa">#</a> <b>localeEnCa</b>
<a name="localeEnCa" href="#localeEnCa">#</a> d3_time_format.<b>localeEnCa</b>

[English (Canada)](https://github.com/d3/d3-time-format/tree/master/src/locale/en-CA.js)

<a name="localeEnGb" href="#localeEnGb">#</a> <b>localeEnGb</b>
<a name="localeEnGb" href="#localeEnGb">#</a> d3_time_format.<b>localeEnGb</b>

[English (United Kingdom)](https://github.com/d3/d3-time-format/tree/master/src/locale/en-GB.js)

<a name="localeEnUs" href="#localeEnUs">#</a> <b>localeEnUs</b>
<a name="localeEnUs" href="#localeEnUs">#</a> d3_time_format.<b>localeEnUs</b>

[English (United States)](https://github.com/d3/d3-time-format/tree/master/src/locale/en-US.js)

<a name="localeEsEs" href="#localeEsEs">#</a> <b>localeEsEs</b>
<a name="localeEsEs" href="#localeEsEs">#</a> d3_time_format.<b>localeEsEs</b>

[Spanish (Spain)](https://github.com/d3/d3-time-format/tree/master/src/locale/es-ES.js)

<a name="localeFiFi" href="#localeFiFi">#</a> <b>localeFiFi</b>
<a name="localeFiFi" href="#localeFiFi">#</a> d3_time_format.<b>localeFiFi</b>

[Finnish (Finland)](https://github.com/d3/d3-time-format/tree/master/src/locale/fi-FI.js)

<a name="localeFrCa" href="#localeFrCa">#</a> <b>localeFrCa</b>
<a name="localeFrCa" href="#localeFrCa">#</a> d3_time_format.<b>localeFrCa</b>

[French (Canada)](https://github.com/d3/d3-time-format/tree/master/src/locale/fr-CA.js)

<a name="localeFrFr" href="#localeFrFr">#</a> <b>localeFrFr</b>
<a name="localeFrFr" href="#localeFrFr">#</a> d3_time_format.<b>localeFrFr</b>

[French (France)](https://github.com/d3/d3-time-format/tree/master/src/locale/fr-FR.js)

<a name="localeHeIl" href="#localeHeIl">#</a> <b>localeHeIl</b>
<a name="localeHeIl" href="#localeHeIl">#</a> d3_time_format.<b>localeHeIl</b>

[Hebrew (Israel)](https://github.com/d3/d3-time-format/tree/master/src/locale/he-IL.js)

<a name="localeHuHu" href="#localeHuHu">#</a> <b>localeHuHu</b>
<a name="localeHuHu" href="#localeHuHu">#</a> d3_time_format.<b>localeHuHu</b>

[Hungarian (Hungary)](https://github.com/d3/d3-time-format/tree/master/src/locale/hu-HU.js)

<a name="localeItIt" href="#localeItIt">#</a> <b>localeItIt</b>
<a name="localeItIt" href="#localeItIt">#</a> d3_time_format.<b>localeItIt</b>

[Italian (Italy)](https://github.com/d3/d3-time-format/tree/master/src/locale/it-IT.js)

<a name="localeJaJp" href="#localeJaJp">#</a> <b>localeJaJp</b>
<a name="localeJaJp" href="#localeJaJp">#</a> d3_time_format.<b>localeJaJp</b>

[Japanese (Japan)](https://github.com/d3/d3-time-format/tree/master/src/locale/ja-JP.js)

<a name="localeKoKr" href="#localeKoKr">#</a> <b>localeKoKr</b>
<a name="localeKoKr" href="#localeKoKr">#</a> d3_time_format.<b>localeKoKr</b>

[Korean (South Korea)](https://github.com/d3/d3-time-format/tree/master/src/locale/ko-KR.js)

<a name="localeMkMk" href="#localeMkMk">#</a> <b>localeMkMk</b>
<a name="localeMkMk" href="#localeMkMk">#</a> d3_time_format.<b>localeMkMk</b>

[Macedonian (Macedonia)](https://github.com/d3/d3-time-format/tree/master/src/locale/mk-MK.js)

<a name="localeNlNl" href="#localeNlNl">#</a> <b>localeNlNl</b>
<a name="localeNlNl" href="#localeNlNl">#</a> d3_time_format.<b>localeNlNl</b>

[Dutch (Netherlands)](https://github.com/d3/d3-time-format/tree/master/src/locale/nl-NL.js)

<a name="localePlPl" href="#localePlPl">#</a> <b>localePlPl</b>
<a name="localePlPl" href="#localePlPl">#</a> d3_time_format.<b>localePlPl</b>

[Polish (Poland)](https://github.com/d3/d3-time-format/tree/master/src/locale/pl-PL.js)

<a name="localePtBr" href="#localePtBr">#</a> <b>localePtBr</b>
<a name="localePtBr" href="#localePtBr">#</a> d3_time_format.<b>localePtBr</b>

[Portuguese (Brazil)](https://github.com/d3/d3-time-format/tree/master/src/locale/pt-BR.js)

<a name="localeRuRu" href="#localeRuRu">#</a> <b>localeRuRu</b>
<a name="localeRuRu" href="#localeRuRu">#</a> d3_time_format.<b>localeRuRu</b>

[Russian (Russia)](https://github.com/d3/d3-time-format/tree/master/src/locale/ru-RU.js)

<a name="localeSvSe" href="#localeSvSe">#</a> <b>localeSvSe</b>
<a name="localeSvSe" href="#localeSvSe">#</a> d3_time_format.<b>localeSvSe</b>

[Swedish (Sweden)](https://github.com/d3/d3-time-format/tree/master/src/locale/sv-SE.js)

<a name="localeZhCn" href="#localeZhCn">#</a> <b>localeZhCn</b>
<a name="localeZhCn" href="#localeZhCn">#</a> d3_time_format.<b>localeZhCn</b>

[Chinese (China)](https://github.com/d3/d3-time-format/tree/master/src/locale/zh-CN.js)

## Changes from D3 3.x:

* Exposed built-in locales.

* Removed format.multi.

* Renamed format.utc to utcFormat and format.iso to isoFormat.
4 changes: 2 additions & 2 deletions package.json
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "d3-time-format",
"version": "0.2.0",
"version": "0.2.1",
"description": "A JavaScript time formatter and parser inspired by strftime and strptime.",
"keywords": [
"d3",
Expand All @@ -27,7 +27,7 @@
"prepublish": "npm run test && uglifyjs build/d3-time-format.js -c -m -o build/d3-time-format.min.js && rm -f build/d3-time-format.zip && zip -j build/d3-time-format.zip -- LICENSE README.md build/d3-time-format.js build/d3-time-format.min.js"
},
"dependencies": {
"d3-time": "~0.0.7"
"d3-time": "~0.1.1"
},
"devDependencies": {
"faucet": "0.0",
Expand Down

0 comments on commit 4957581

Please sign in to comment.