diff --git a/README.md b/README.md index c15ce7d..6f1d918 100644 --- a/README.md +++ b/README.md @@ -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 + + +``` + +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 -# format(specifier) +# d3_time_format.format(specifier) 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. -# utcFormat(specifier) +# d3_time_format.utcFormat(specifier) 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. -# isoFormat +# d3_time_format.isoFormat 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"); ``` # locale.format(specifier) @@ -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" @@ -131,7 +138,7 @@ Returns this format’s specifier. ### Locales -# locale(definition) +# d3_time_format.locale(definition) 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: @@ -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). -# localeCaEs +# d3_time_format.localeCaEs [Catalan (Spain)](https://github.com/d3/d3-time-format/tree/master/src/locale/ca-ES.js) -# localeDeCh +# d3_time_format.localeDeCh [German (Switzerland)](https://github.com/d3/d3-time-format/tree/master/src/locale/de-CH.js) -# localeDeDe +# d3_time_format.localeDeDe [German (Germany)](https://github.com/d3/d3-time-format/tree/master/src/locale/de-DE.js) -# localeEnCa +# d3_time_format.localeEnCa [English (Canada)](https://github.com/d3/d3-time-format/tree/master/src/locale/en-CA.js) -# localeEnGb +# d3_time_format.localeEnGb [English (United Kingdom)](https://github.com/d3/d3-time-format/tree/master/src/locale/en-GB.js) -# localeEnUs +# d3_time_format.localeEnUs [English (United States)](https://github.com/d3/d3-time-format/tree/master/src/locale/en-US.js) -# localeEsEs +# d3_time_format.localeEsEs [Spanish (Spain)](https://github.com/d3/d3-time-format/tree/master/src/locale/es-ES.js) -# localeFiFi +# d3_time_format.localeFiFi [Finnish (Finland)](https://github.com/d3/d3-time-format/tree/master/src/locale/fi-FI.js) -# localeFrCa +# d3_time_format.localeFrCa [French (Canada)](https://github.com/d3/d3-time-format/tree/master/src/locale/fr-CA.js) -# localeFrFr +# d3_time_format.localeFrFr [French (France)](https://github.com/d3/d3-time-format/tree/master/src/locale/fr-FR.js) -# localeHeIl +# d3_time_format.localeHeIl [Hebrew (Israel)](https://github.com/d3/d3-time-format/tree/master/src/locale/he-IL.js) -# localeHuHu +# d3_time_format.localeHuHu [Hungarian (Hungary)](https://github.com/d3/d3-time-format/tree/master/src/locale/hu-HU.js) -# localeItIt +# d3_time_format.localeItIt [Italian (Italy)](https://github.com/d3/d3-time-format/tree/master/src/locale/it-IT.js) -# localeJaJp +# d3_time_format.localeJaJp [Japanese (Japan)](https://github.com/d3/d3-time-format/tree/master/src/locale/ja-JP.js) -# localeKoKr +# d3_time_format.localeKoKr [Korean (South Korea)](https://github.com/d3/d3-time-format/tree/master/src/locale/ko-KR.js) -# localeMkMk +# d3_time_format.localeMkMk [Macedonian (Macedonia)](https://github.com/d3/d3-time-format/tree/master/src/locale/mk-MK.js) -# localeNlNl +# d3_time_format.localeNlNl [Dutch (Netherlands)](https://github.com/d3/d3-time-format/tree/master/src/locale/nl-NL.js) -# localePlPl +# d3_time_format.localePlPl [Polish (Poland)](https://github.com/d3/d3-time-format/tree/master/src/locale/pl-PL.js) -# localePtBr +# d3_time_format.localePtBr [Portuguese (Brazil)](https://github.com/d3/d3-time-format/tree/master/src/locale/pt-BR.js) -# localeRuRu +# d3_time_format.localeRuRu [Russian (Russia)](https://github.com/d3/d3-time-format/tree/master/src/locale/ru-RU.js) -# localeSvSe +# d3_time_format.localeSvSe [Swedish (Sweden)](https://github.com/d3/d3-time-format/tree/master/src/locale/sv-SE.js) -# localeZhCn +# d3_time_format.localeZhCn [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. diff --git a/package.json b/package.json index 980b645..6574d14 100644 --- a/package.json +++ b/package.json @@ -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", @@ -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",