From 61a5e8a64af9d1857efb229d80f5b1225d981035 Mon Sep 17 00:00:00 2001 From: Mike Bostock Date: Thu, 7 Jan 2016 13:48:20 -0800 Subject: [PATCH] =?UTF-8?q?Prefix=20exported=20symbols=20with=20=E2=80=9Cf?= =?UTF-8?q?ormat=E2=80=9D.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 124 ++++++++++++++++++------------------- index.js | 48 +++++++------- package.json | 2 +- test/format-type-c-test.js | 2 +- test/locale-test.js | 30 ++++----- test/localeEnUs-test.js | 4 +- test/localeFrFr-test.js | 4 +- 7 files changed, 107 insertions(+), 107 deletions(-) diff --git a/README.md b/README.md index 3ed3366..0c3aae0 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ Yet rounding error is not the only reason to customize number formatting. A tabl Formatting numbers for human consumption is the purpose of d3-format, which is modeled after Python 3’s [format specification mini-language](https://docs.python.org/3/library/string.html#format-specification-mini-language) ([PEP 3101](https://www.python.org/dev/peps/pep-3101/)). Revisiting the example above: ```js -var f = d3_format.format(".1f"); +var f = d3.format(".1f"); for (var i = 0; i < 10; i++) { console.log(f(0.1 * i)); } @@ -54,13 +54,13 @@ Now you get this: But d3-format is much more than an alias for [number.toFixed](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toFixed)! A few more examples: ```js -d3_format.format(".0%")(0.123); // rounded percentage, "12%" -d3_format.format("($.2f")(-3.5); // localized fixed-point currency, "(£3.50)" -d3_format.format("+20")(42); // space-filled and signed, " +42" -d3_format.format(".^20")(42); // dot-filled and centered, ".........42........." -d3_format.format(".2s")(42e6); // SI-prefix with two significant digits, "42M" -d3_format.format("#x")(48879); // prefixed lowercase hexadecimal, "0xbeef" -d3_format.format(",.2r")(4223); // grouped thousands with two significant digits, "4,200" +d3.format(".0%")(0.123); // rounded percentage, "12%" +d3.format("($.2f")(-3.5); // localized fixed-point currency, "(£3.50)" +d3.format("+20")(42); // space-filled and signed, " +42" +d3.format(".^20")(42); // dot-filled and centered, ".........42........." +d3.format(".2s")(42e6); // SI-prefix with two significant digits, "42M" +d3.format("#x")(48879); // prefixed lowercase hexadecimal, "0xbeef" +d3.format(",.2r")(4223); // grouped thousands with two significant digits, "4,200" ``` See [*locale*.format](#locale_format) for a detailed specification, and try running [formatSpecifier](#formatSpecifier) on the above formats to decode their meaning. @@ -70,20 +70,20 @@ See [*locale*.format](#locale_format) for a detailed specification, and try runn If you use NPM, `npm install d3-format`. Otherwise, download the [latest release](https://github.com/d3/d3-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_format` global is exported. [Try d3-format in your browser.](https://tonicdev.com/npm/d3-format) ## API Reference -# d3_format.format(specifier) +# d3.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. +An alias for [*locale*.format](#locale_format) on the [U.S. English locale](#formatEnUs). See the other [locales](#locales), or use [formatLocale](#formatLocale) to define a new locale. -# d3_format.formatPrefix(specifier, value) +# d3.formatPrefix(specifier, value) -An alias for [*locale*.formatPrefix](#locale_formatPrefix) on the [U.S. English locale](#localeEnUs). See the other [locales](#locales), or use [locale](#locale) to define a new locale. +An alias for [*locale*.formatPrefix](#locale_formatPrefix) on the [U.S. English locale](#formatEnUs). See the other [locales](#locales), or use [formatLocale](#formatLocale) to define a new locale. # locale.format(specifier) @@ -136,10 +136,10 @@ The available *type* values are: The type `n` is also supported as shorthand for `,g`. For the `g`, `n` and `​` (none) types, decimal notation is used if the resulting string would have *precision* or fewer digits; otherwise, exponent notation is used. For example: ```js -d3_format.format(".2")(42); // "42" -d3_format.format(".2")(4.2); // "4.2" -d3_format.format(".1")(42); // "4e+1" -d3_format.format(".1")(4.2); // "4" +d3.format(".2")(42); // "42" +d3.format(".2")(4.2); // "4.2" +d3.format(".1")(42); // "4e+1" +d3.format(".1")(4.2); // "4" ``` # locale.formatPrefix(specifier, value) @@ -167,14 +167,14 @@ Equivalent to [*locale*.format](#locale_format), except the returned function wi Unlike [*locale*.format](#locale_format) with the `s` format type, this method returns a formatter with a consistent SI prefix, rather than computing the prefix dynamically for each number. In addition, the *precision* for the given *specifier* represents the number of digits past the decimal point (as with `f` fixed point notation), not the number of significant digits. For example: ```js -var f = d3_format.formatPrefix(",.0", 1e-6); +var f = d3.formatPrefix(",.0", 1e-6); f(0.00042); // "420µ" f(0.0042); // "4,200µ" ``` This method is useful when formatting multiple numbers in the same units for easy comparison. See [precisionPrefix](#precisionPrefix) for help picking an appropriate precision, and [bl.ocks.org/9764126](http://bl.ocks.org/mbostock/9764126) for an example. -# d3_format.formatSpecifier(specifier) +# d3.formatSpecifier(specifier) Parses the specified *specifier*, returning an object with exposed fields that correspond to the [format specification mini-language](#locale_format) and a toString method that reconstructs the specifier. For example, `formatSpecifier("s")` returns: @@ -195,19 +195,19 @@ Parses the specified *specifier*, returning an object with exposed fields that c This method is useful for understanding how format specifiers are parsed and for deriving new specifiers. For example, you might compute an appropriate precision based on the numbers you want to format using [precisionFixed](#precisionFixed) and then create a new format: ```js -var s = d3_format.formatSpecifier("f"); +var s = d3.formatSpecifier("f"); s.precision = precisionFixed(0.01); -var f = d3_format.format(s); +var f = d3.format(s); f(42); // "42.00"; ``` -# d3_format.precisionFixed(step) +# d3.precisionFixed(step) Returns a suggested decimal precision for fixed point notation given the specified numeric *step* value. The *step* represents the minimum absolute difference between values that will be formatted. (This assumes that the values to be formatted are also multiples of *step*.) For example, given the numbers 1, 1.5, and 2, the *step* should be 0.5 and the suggested precision is 1: ```js -var p = d3_format.precisionFixed(0.5), - f = d3_format.format("." + p + "f"); +var p = d3.precisionFixed(0.5), + f = d3.format("." + p + "f"); f(1); // "1.0" f(1.5); // "1.5" f(2); // "2.0" @@ -216,8 +216,8 @@ f(2); // "2.0" Whereas for the numbers 1, 2 and 3, the *step* should be 1 and the suggested precision is 0: ```js -var p = d3_format.precisionFixed(1), - f = d3_format.format("." + p + "f"); +var p = d3.precisionFixed(1), + f = d3.format("." + p + "f"); f(1); // "1" f(2); // "2" f(3); // "3" @@ -226,32 +226,32 @@ f(3); // "3" Note: for the `%` format type, subtract two: ```js -var p = Math.max(0, d3_format.precisionFixed(0.05) - 2), - f = d3_format.format("." + p + "%"); +var p = Math.max(0, d3.precisionFixed(0.05) - 2), + f = d3.format("." + p + "%"); f(0.45); // "45%" f(0.50); // "50%" f(0.55); // "55%" ``` -# d3_format.precisionPrefix(step, value) +# d3.precisionPrefix(step, value) Returns a suggested decimal precision for use with [*locale*.formatPrefix](#locale_formatPrefix) given the specified numeric *step* and reference *value*. The *step* represents the minimum absolute difference between values that will be formatted, and *value* determines which SI prefix will be used. (This assumes that the values to be formatted are also multiples of *step*.) For example, given the numbers 1.1e6, 1.2e6, and 1.3e6, the *step* should be 1e5, the *value* could be 1.3e6, and the suggested precision is 1: ```js -var p = d3_format.precisionPrefix(1e5, 1.3e6), - f = d3_format.formatPrefix("." + p, 1.3e6); +var p = d3.precisionPrefix(1e5, 1.3e6), + f = d3.formatPrefix("." + p, 1.3e6); f(1.1e6); // "1.1M" f(1.2e6); // "1.2M" f(1.3e6); // "1.3M" ``` -# d3_format.precisionRound(step, max) +# d3.precisionRound(step, max) Returns a suggested decimal precision for format types that round to significant digits given the specified numeric *step* and *max* values. The *step* represents the minimum absolute difference between values that will be formatted, and the *max* represents the largest absolute value that will be formatted. (This assumes that the values to be formatted are also multiples of *step*.) For example, given the numbers 0.99, 1.0, and 1.01, the *step* should be 0.01, the *max* should be 1.01, and the suggested precision is 3: ```js -var p = d3_format.precisionRound(0.01, 1.01), - f = d3_format.format("." + p + "r"); +var p = d3.precisionRound(0.01, 1.01), + f = d3.format("." + p + "r"); f(0.99); // "0.990" f(1.0); // "1.00" f(1.01); // "1.01" @@ -260,8 +260,8 @@ f(1.01); // "1.01" Whereas for the numbers 0.9, 1.0, and 1.1, the *step* should be 0.1, the *max* should be 1.1, and the suggested precision is 2: ```js -var p = d3_format.precisionRound(0.1, 1.1), - f = d3_format.format("." + p + "r"); +var p = d3.precisionRound(0.1, 1.1), + f = d3.format("." + p + "r"); f(0.9); // "0.90" f(1.0); // "1.0" f(1.1); // "1.1" @@ -270,15 +270,15 @@ f(1.1); // "1.1" Note: for the `e` format type, subtract one: ```js -var p = Math.max(0, d3_format.precisionRound(0.01, 1.01) - 1), - f = d3_format.format("." + p + "e"); +var p = Math.max(0, d3.precisionRound(0.01, 1.01) - 1), + f = d3.format("." + p + "e"); f(0.01); // "1.00e-2" f(1.01); // "1.01e+0" ``` ### Locales -# d3_format.locale(definition) +# d3.formatLocale(definition) Returns a *locale* object for the specified *definition* with [*locale*.format](#locale_format) and [*locale*.formatPrefix](#locale_formatPrefix) methods. The *definition* must include the following properties: @@ -289,94 +289,94 @@ Returns a *locale* object for the specified *definition* with [*locale*.format]( Note that the *thousands* property is a misnomer, as the grouping definition allows groups other than thousands. -# d3_format.localeCaEs +# d3.formatCaEs [Catalan (Spain)](https://github.com/d3/d3-format/tree/master/src/locale/ca-ES.js) -# d3_format.localeCsCz +# d3.formatCsCz [Czech (Czech Republic)](https://github.com/d3/d3-format/tree/master/src/locale/cs-CZ.js) -# d3_format.localeDeCh +# d3.formatDeCh [German (Switzerland)](https://github.com/d3/d3-format/tree/master/src/locale/de-CH.js) -# d3_format.localeDeDe +# d3.formatDeDe [German (Germany)](https://github.com/d3/d3-format/tree/master/src/locale/de-DE.js) -# d3_format.localeEnCa +# d3.formatEnCa [English (Canada)](https://github.com/d3/d3-format/tree/master/src/locale/en-CA.js) -# d3_format.localeEnGb +# d3.formatEnGb [English (United Kingdom)](https://github.com/d3/d3-format/tree/master/src/locale/en-GB.js) -# d3_format.localeEnUs +# d3.formatEnUs [English (United States)](https://github.com/d3/d3-format/tree/master/src/locale/en-US.js) -# d3_format.localeEsEs +# d3.formatEsEs [Spanish (Spain)](https://github.com/d3/d3-format/tree/master/src/locale/es-ES.js) -# d3_format.localeFiFi +# d3.formatFiFi [Finnish (Finland)](https://github.com/d3/d3-format/tree/master/src/locale/fi-FI.js) -# d3_format.localeFrCa +# d3.formatFrCa [French (Canada)](https://github.com/d3/d3-format/tree/master/src/locale/fr-CA.js) -# d3_format.localeFrFr +# d3.formatFrFr [French (France)](https://github.com/d3/d3-format/tree/master/src/locale/fr-FR.js) -# d3_format.localeHeIl +# d3.formatHeIl [Hebrew (Israel)](https://github.com/d3/d3-format/tree/master/src/locale/he-IL.js) -# d3_format.localeHuHu +# d3.formatHuHu [Hungarian (Hungary)](https://github.com/d3/d3-format/tree/master/src/locale/hu-HU.js) -# d3_format.localeItIt +# d3.formatItIt [Italian (Italy)](https://github.com/d3/d3-format/tree/master/src/locale/it-IT.js) -# d3_format.localeJaJp +# d3.formatJaJp [Japanese (Japan)](https://github.com/d3/d3-format/tree/master/src/locale/ja-JP.js) -# d3_format.localeKoKr +# d3.formatKoKr [Korean (South Korea)](https://github.com/d3/d3-format/tree/master/src/locale/ko-KR.js) -# d3_format.localeMkMk +# d3.formatMkMk [Macedonian (Macedonia)](https://github.com/d3/d3-format/tree/master/src/locale/mk-MK.js) -# d3_format.localeNlNl +# d3.formatNlNl [Dutch (Netherlands)](https://github.com/d3/d3-format/tree/master/src/locale/nl-NL.js) -# d3_format.localePlPl +# d3.formatPlPl [Polish (Poland)](https://github.com/d3/d3-format/tree/master/src/locale/pl-PL.js) -# d3_format.localePtBr +# d3.formatPtBr [Portuguese (Brazil)](https://github.com/d3/d3-format/tree/master/src/locale/pt-BR.js) -# d3_format.localeRuRu +# d3.formatRuRu [Russian (Russia)](https://github.com/d3/d3-format/tree/master/src/locale/ru-RU.js) -# d3_format.localeSvSe +# d3.formatSvSe [Swedish (Sweden)](https://github.com/d3/d3-format/tree/master/src/locale/sv-SE.js) -# d3_format.localeZhCn +# d3.formatZhCn [Chinese (China)](https://github.com/d3/d3-format/tree/master/src/locale/zh-CN.js) diff --git a/index.js b/index.js index 9d6c476..9036f0e 100644 --- a/index.js +++ b/index.js @@ -1,28 +1,28 @@ import defaultLocale from "./src/locale/en-US"; -export {default as locale} from "./src/locale"; -export {default as localeCaEs} from "./src/locale/ca-ES"; -export {default as localeCsCz} from "./src/locale/cs-CZ"; -export {default as localeDeCh} from "./src/locale/de-CH"; -export {default as localeDeDe} from "./src/locale/de-DE"; -export {default as localeEnCa} from "./src/locale/en-CA"; -export {default as localeEnGb} from "./src/locale/en-GB"; -export {default as localeEnUs} from "./src/locale/en-US"; -export {default as localeEsEs} from "./src/locale/es-ES"; -export {default as localeFiFi} from "./src/locale/fi-FI"; -export {default as localeFrCa} from "./src/locale/fr-CA"; -export {default as localeFrFr} from "./src/locale/fr-FR"; -export {default as localeHeIl} from "./src/locale/he-IL"; -export {default as localeHuHu} from "./src/locale/hu-HU"; -export {default as localeItIt} from "./src/locale/it-IT"; -export {default as localeJaJp} from "./src/locale/ja-JP"; -export {default as localeKoKr} from "./src/locale/ko-KR"; -export {default as localeMkMk} from "./src/locale/mk-MK"; -export {default as localeNlNl} from "./src/locale/nl-NL"; -export {default as localePlPl} from "./src/locale/pl-PL"; -export {default as localePtBr} from "./src/locale/pt-BR"; -export {default as localeRuRu} from "./src/locale/ru-RU"; -export {default as localeSvSe} from "./src/locale/sv-SE"; -export {default as localeZhCn} from "./src/locale/zh-CN"; +export {default as formatLocale} from "./src/locale"; +export {default as formatCaEs} from "./src/locale/ca-ES"; +export {default as formatCsCz} from "./src/locale/cs-CZ"; +export {default as formatDeCh} from "./src/locale/de-CH"; +export {default as formatDeDe} from "./src/locale/de-DE"; +export {default as formatEnCa} from "./src/locale/en-CA"; +export {default as formatEnGb} from "./src/locale/en-GB"; +export {default as formatEnUs} from "./src/locale/en-US"; +export {default as formatEsEs} from "./src/locale/es-ES"; +export {default as formatFiFi} from "./src/locale/fi-FI"; +export {default as formatFrCa} from "./src/locale/fr-CA"; +export {default as formatFrFr} from "./src/locale/fr-FR"; +export {default as formatHeIl} from "./src/locale/he-IL"; +export {default as formatHuHu} from "./src/locale/hu-HU"; +export {default as formatItIt} from "./src/locale/it-IT"; +export {default as formatJaJp} from "./src/locale/ja-JP"; +export {default as formatKoKr} from "./src/locale/ko-KR"; +export {default as formatMkMk} from "./src/locale/mk-MK"; +export {default as formatNlNl} from "./src/locale/nl-NL"; +export {default as formatPlPl} from "./src/locale/pl-PL"; +export {default as formatPtBr} from "./src/locale/pt-BR"; +export {default as formatRuRu} from "./src/locale/ru-RU"; +export {default as formatSvSe} from "./src/locale/sv-SE"; +export {default as formatZhCn} from "./src/locale/zh-CN"; export {default as formatSpecifier} from "./src/formatSpecifier"; export {default as precisionFixed} from "./src/precisionFixed"; export {default as precisionPrefix} from "./src/precisionPrefix"; diff --git a/package.json b/package.json index 78c94cc..1703bdb 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "d3-format", - "version": "0.4.2", + "version": "0.5.0", "description": "Format numbers for human consumption.", "keywords": [ "d3", diff --git a/test/format-type-c-test.js b/test/format-type-c-test.js index 94c2e1a..098e2da 100644 --- a/test/format-type-c-test.js +++ b/test/format-type-c-test.js @@ -10,6 +10,6 @@ tape("format(\"c\") unicode character", function(test) { }); tape("format(\"c\") does not localize a decimal point", function(test) { - test.equal(format.locale({decimal: "/"}).format("c")("."), "."); + test.equal(format.formatLocale({decimal: "/"}).format("c")("."), "."); test.end(); }); diff --git a/test/locale-test.js b/test/locale-test.js index 9d3fa1d..f109157 100644 --- a/test/locale-test.js +++ b/test/locale-test.js @@ -1,32 +1,32 @@ var tape = require("tape"), format = require("../"); -tape("locale({decimal: decimal}) observes the specified decimal point", function(test) { - test.equal(format.locale({decimal: "|"}).format("06.2f")(2), "002|00"); - test.equal(format.locale({decimal: "/"}).format("06.2f")(2), "002/00"); +tape("formatLocale({decimal: decimal}) observes the specified decimal point", function(test) { + test.equal(format.formatLocale({decimal: "|"}).format("06.2f")(2), "002|00"); + test.equal(format.formatLocale({decimal: "/"}).format("06.2f")(2), "002/00"); test.end(); }); -tape("locale({currency: [prefix, suffix]}) observes the specified currency prefix and suffix", function(test) { - test.equal(format.locale({decimal: ".", currency: ["฿", ""]}).format("$06.2f")(2), "฿02.00"); - test.equal(format.locale({decimal: ".", currency: ["", "฿"]}).format("$06.2f")(2), "02.00฿"); +tape("formatLocale({currency: [prefix, suffix]}) observes the specified currency prefix and suffix", function(test) { + test.equal(format.formatLocale({decimal: ".", currency: ["฿", ""]}).format("$06.2f")(2), "฿02.00"); + test.equal(format.formatLocale({decimal: ".", currency: ["", "฿"]}).format("$06.2f")(2), "02.00฿"); test.end(); }); -tape("locale({grouping: null}) does not perform any grouping", function(test) { - test.equal(format.locale({decimal: ".", grouping: null}).format("012,.2f")(2), "000000002.00"); +tape("formatLocale({grouping: null}) does not perform any grouping", function(test) { + test.equal(format.formatLocale({decimal: ".", grouping: null}).format("012,.2f")(2), "000000002.00"); test.end(); }); -tape("locale({grouping: [sizes…]}) observes the specified group sizes", function(test) { - test.equal(format.locale({decimal: ".", grouping: [3], thousands: ","}).format("012,.2f")(2), "0,000,002.00"); - test.equal(format.locale({decimal: ".", grouping: [2], thousands: ","}).format("012,.2f")(2), "0,00,00,02.00"); - test.equal(format.locale({decimal: ".", grouping: [2, 3], thousands: ","}).format("012,.2f")(2), "00,000,02.00"); +tape("formatLocale({grouping: [sizes…]}) observes the specified group sizes", function(test) { + test.equal(format.formatLocale({decimal: ".", grouping: [3], thousands: ","}).format("012,.2f")(2), "0,000,002.00"); + test.equal(format.formatLocale({decimal: ".", grouping: [2], thousands: ","}).format("012,.2f")(2), "0,00,00,02.00"); + test.equal(format.formatLocale({decimal: ".", grouping: [2, 3], thousands: ","}).format("012,.2f")(2), "00,000,02.00"); test.end(); }); -tape("locale({thousands: separator}) observes the specified group separator", function(test) { - test.equal(format.locale({decimal: ".", grouping: [3], thousands: " "}).format("012,.2f")(2), "0 000 002.00"); - test.equal(format.locale({decimal: ".", grouping: [3], thousands: "/"}).format("012,.2f")(2), "0/000/002.00"); +tape("formatLocale({thousands: separator}) observes the specified group separator", function(test) { + test.equal(format.formatLocale({decimal: ".", grouping: [3], thousands: " "}).format("012,.2f")(2), "0 000 002.00"); + test.equal(format.formatLocale({decimal: ".", grouping: [3], thousands: "/"}).format("012,.2f")(2), "0/000/002.00"); test.end(); }); diff --git a/test/localeEnUs-test.js b/test/localeEnUs-test.js index bc2b365..656362b 100644 --- a/test/localeEnUs-test.js +++ b/test/localeEnUs-test.js @@ -1,8 +1,8 @@ var tape = require("tape"), format = require("../"); -tape("localeEnUs is a U.S. English format", function(test) { - var locale = format.localeEnUs; +tape("formatEnUs is a U.S. English format locale", function(test) { + var locale = format.formatEnUs; test.equal(locale.format("$,.2f")(1234.56), "$1,234.56"); test.end(); }); diff --git a/test/localeFrFr-test.js b/test/localeFrFr-test.js index 2e2a443..23b245b 100644 --- a/test/localeFrFr-test.js +++ b/test/localeFrFr-test.js @@ -1,8 +1,8 @@ var tape = require("tape"), format = require("../"); -tape("localeFrFr is a French format", function(test) { - var locale = format.localeFrFr; +tape("formatFrFr is a French format locale", function(test) { + var locale = format.formatFrFr; test.equal(locale.format("$,.2f")(1234.56), "1.234,56 €"); test.end(); });