Skip to content

Commit

Permalink
Prefix exported symbols with “format”.
Browse files Browse the repository at this point in the history
  • Loading branch information
@mbostock
mbostock committed Jan 7, 2016
1 parent c7eb9a6 commit 61a5e8a
Show file tree
Hide file tree
Showing 7 changed files with 107 additions and 107 deletions.
124 changes: 62 additions & 62 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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));
}
Expand All @@ -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.
Expand All @@ -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
<script src="https://d3js.org/d3-format.v0.4.min.js"></script>
<script src="https://d3js.org/d3-format.v0.5.min.js"></script>
```

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

## API Reference

<a name="format" href="#format">#</a> d3_format.<b>format</b>(<i>specifier</i>)
<a name="format" href="#format">#</a> d3.<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.
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.

<a name="formatPrefix" href="#formatPrefix">#</a> d3_format.<b>formatPrefix</b>(<i>specifier</i>, <i>value</i>)
<a name="formatPrefix" href="#formatPrefix">#</a> d3.<b>formatPrefix</b>(<i>specifier</i>, <i>value</i>)

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.

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

Expand Down Expand Up @@ -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"
```

<a name="locale_formatPrefix" href="#locale_formatPrefix">#</a> <i>locale</i>.<b>formatPrefix</b>(<i>specifier</i>, <i>value</i>)
Expand Down Expand Up @@ -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.

<a name="formatSpecifier" href="#formatSpecifier">#</a> d3_format.<b>formatSpecifier</b>(<i>specifier</i>)
<a name="formatSpecifier" href="#formatSpecifier">#</a> d3.<b>formatSpecifier</b>(<i>specifier</i>)

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:

Expand All @@ -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";
```

<a name="precisionFixed" href="#precisionFixed">#</a> d3_format.<b>precisionFixed</b>(<i>step</i>)
<a name="precisionFixed" href="#precisionFixed">#</a> d3.<b>precisionFixed</b>(<i>step</i>)

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"
Expand All @@ -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"
Expand All @@ -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%"
```

<a name="precisionPrefix" href="#precisionPrefix">#</a> d3_format.<b>precisionPrefix</b>(<i>step</i>, <i>value</i>)
<a name="precisionPrefix" href="#precisionPrefix">#</a> d3.<b>precisionPrefix</b>(<i>step</i>, <i>value</i>)

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"
```

<a name="precisionRound" href="#precisionRound">#</a> d3_format.<b>precisionRound</b>(<i>step</i>, <i>max</i>)
<a name="precisionRound" href="#precisionRound">#</a> d3.<b>precisionRound</b>(<i>step</i>, <i>max</i>)

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"
Expand All @@ -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"
Expand All @@ -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

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

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:

Expand All @@ -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.

<a name="localeCaEs" href="#localeCaEs">#</a> d3_format.<b>localeCaEs</b>
<a name="formatCaEs" href="#formatCaEs">#</a> d3.<b>formatCaEs</b>

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

<a name="localeCsCz" href="#localeCsCz">#</a> d3_format.<b>localeCsCz</b>
<a name="formatCsCz" href="#formatCsCz">#</a> d3.<b>formatCsCz</b>

[Czech (Czech Republic)](https://github.com/d3/d3-format/tree/master/src/locale/cs-CZ.js)

<a name="localeDeCh" href="#localeDeCh">#</a> d3_format.<b>localeDeCh</b>
<a name="formatDeCh" href="#formatDeCh">#</a> d3.<b>formatDeCh</b>

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

<a name="localeDeDe" href="#localeDeDe">#</a> d3_format.<b>localeDeDe</b>
<a name="formatDeDe" href="#formatDeDe">#</a> d3.<b>formatDeDe</b>

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

<a name="localeEnCa" href="#localeEnCa">#</a> d3_format.<b>localeEnCa</b>
<a name="formatEnCa" href="#formatEnCa">#</a> d3.<b>formatEnCa</b>

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

<a name="localeEnGb" href="#localeEnGb">#</a> d3_format.<b>localeEnGb</b>
<a name="formatEnGb" href="#formatEnGb">#</a> d3.<b>formatEnGb</b>

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

<a name="localeEnUs" href="#localeEnUs">#</a> d3_format.<b>localeEnUs</b>
<a name="formatEnUs" href="#formatEnUs">#</a> d3.<b>formatEnUs</b>

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

<a name="localeEsEs" href="#localeEsEs">#</a> d3_format.<b>localeEsEs</b>
<a name="formatEsEs" href="#formatEsEs">#</a> d3.<b>formatEsEs</b>

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

<a name="localeFiFi" href="#localeFiFi">#</a> d3_format.<b>localeFiFi</b>
<a name="formatFiFi" href="#formatFiFi">#</a> d3.<b>formatFiFi</b>

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

<a name="localeFrCa" href="#localeFrCa">#</a> d3_format.<b>localeFrCa</b>
<a name="formatFrCa" href="#formatFrCa">#</a> d3.<b>formatFrCa</b>

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

<a name="localeFrFr" href="#localeFrFr">#</a> d3_format.<b>localeFrFr</b>
<a name="formatFrFr" href="#formatFrFr">#</a> d3.<b>formatFrFr</b>

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

<a name="localeHeIl" href="#localeHeIl">#</a> d3_format.<b>localeHeIl</b>
<a name="formatHeIl" href="#formatHeIl">#</a> d3.<b>formatHeIl</b>

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

<a name="localeHuHu" href="#localeHuHu">#</a> d3_format.<b>localeHuHu</b>
<a name="formatHuHu" href="#formatHuHu">#</a> d3.<b>formatHuHu</b>

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

<a name="localeItIt" href="#localeItIt">#</a> d3_format.<b>localeItIt</b>
<a name="formatItIt" href="#formatItIt">#</a> d3.<b>formatItIt</b>

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

<a name="localeJaJp" href="#localeJaJp">#</a> d3_format.<b>localeJaJp</b>
<a name="formatJaJp" href="#formatJaJp">#</a> d3.<b>formatJaJp</b>

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

<a name="localeKoKr" href="#localeKoKr">#</a> d3_format.<b>localeKoKr</b>
<a name="formatKoKr" href="#formatKoKr">#</a> d3.<b>formatKoKr</b>

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

<a name="localeMkMk" href="#localeMkMk">#</a> d3_format.<b>localeMkMk</b>
<a name="formatMkMk" href="#formatMkMk">#</a> d3.<b>formatMkMk</b>

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

<a name="localeNlNl" href="#localeNlNl">#</a> d3_format.<b>localeNlNl</b>
<a name="formatNlNl" href="#formatNlNl">#</a> d3.<b>formatNlNl</b>

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

<a name="localePlPl" href="#localePlPl">#</a> d3_format.<b>localePlPl</b>
<a name="formatPlPl" href="#formatPlPl">#</a> d3.<b>formatPlPl</b>

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

<a name="localePtBr" href="#localePtBr">#</a> d3_format.<b>localePtBr</b>
<a name="formatPtBr" href="#formatPtBr">#</a> d3.<b>formatPtBr</b>

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

<a name="localeRuRu" href="#localeRuRu">#</a> d3_format.<b>localeRuRu</b>
<a name="formatRuRu" href="#formatRuRu">#</a> d3.<b>formatRuRu</b>

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

<a name="localeSvSe" href="#localeSvSe">#</a> d3_format.<b>localeSvSe</b>
<a name="formatSvSe" href="#formatSvSe">#</a> d3.<b>formatSvSe</b>

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

<a name="localeZhCn" href="#localeZhCn">#</a> d3_format.<b>localeZhCn</b>
<a name="formatZhCn" href="#formatZhCn">#</a> d3.<b>formatZhCn</b>

[Chinese (China)](https://github.com/d3/d3-format/tree/master/src/locale/zh-CN.js)
48 changes: 24 additions & 24 deletions index.js
View file
Original file line number Diff line number Diff line change
@@ -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";
Expand Down
2 changes: 1 addition & 1 deletion package.json
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "d3-format",
"version": "0.4.2",
"version": "0.5.0",
"description": "Format numbers for human consumption.",
"keywords": [
"d3",
Expand Down
2 changes: 1 addition & 1 deletion test/format-type-c-test.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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();
});
Loading

0 comments on commit 61a5e8a

Please sign in to comment.