d3-format

Заметили ли вы, как иногда JavaScript не отображает числа так, как вы ожидаете? Например, вы пытались вывести десятые доли с помощью простого цикла:

for (var i = 0; i < 10; i++) {
  console.log(0.1 * i);
}

И получили вот это:

0
0.1
0.2
0.30000000000000004
0.4
0.5
0.6000000000000001
0.7000000000000001
0.8
0.9

Добро пожаловать в двойную точность с плавающей запятой! ಠ_ಠ

Однако ошибка округления — не единственная причина для настройки форматирования чисел. Таблица чисел должна быть отформатирована последовательно для сравнения; выше, 0.0 было бы лучше, чем 0. Большие числа должны иметь сгруппированные цифры (например, 42 000) или быть в научной или метрической записи (4,2e+4, 42к). Валюты должны иметь фиксированную точность ($3,50). Сообщаемые числовые результаты должны быть округлены до значащих цифр (4021 становится 4000). Форматы чисел должны соответствовать региональным настройкам пользователя (42 000,00 или 42 000,00). И так далее.

Форматирование чисел для восприятия человеком — цель d3-format, которая моделируется по мини-языку спецификации формата Python 3 (PEP 3101). Вернёмся к приведенному выше примеру:

var f = d3.format(".1f");
for (var i = 0; i < 10; i++) {
  console.log(f(0.1 * i));
}

Теперь вы получите это:

0.0
0.1
0.2
0.3
0.4
0.5
0.6
0.7
0.8
0.9

Но d3-format — это намного больше, чем просто псевдоним для number.toFixed! Вот ещё несколько примеров:

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"

См. locale.format для подробной спецификации и попробуйте запустить d3.formatSpecifier на приведенных выше форматах, чтобы расшифровать их значение.

Установка

Если вы используете NPM, npm install d3-format. В противном случае скачайте последнюю версию. Вы также можете загрузить её напрямую с d3js.org, как самостоятельную библиотеку или как часть D3 4.0. Поддерживаются среды AMD, CommonJS и vanilla. В vanilla экспортируется глобальная переменная d3:

<script src="https://d3js.org/d3-format.v1.min.js"></script>
<script>

var format = d3.format(".2s");

</script>

Файлы локалей размещаются на unpkg и могут быть загружены с помощью d3.json. Например, чтобы установить русский язык в качестве языка по умолчанию:

d3.json("https://unpkg.com/d3-format@1/locale/ru-RU.json", function(error, locale) {
  if (error) throw error;

  d3.formatDefaultLocale(locale);

  var format = d3.format("$,");

  console.log(format(1234.56)); // 1 234,56 руб.
});

Попробуйте d3-format в вашем браузере.

Справочник по API

d3.format(specifier) Источник

Псевдоним для locale.format на языке по умолчанию.

d3.formatPrefix(specifier, value) Источник

Псевдоним для locale.formatPrefix на языке по умолчанию.

locale.format(specifier) Источник

Возвращает новую функцию форматирования для заданной строки specifier. Возвращаемая функция принимает число в качестве единственного аргумента и возвращает строку, представляющую отформатированное число. Общий вид спецификатора:

[​[fill]align][sign][symbol][0][width][,][.precision][~][type]

fill может быть любым символом. Наличие символа заполнения сигнализируется символом align, который должен быть одним из следующих:

• > — Принудительно выравнивает поле по правому краю в доступном пространстве. (Поведение по умолчанию).
• < — Принудительно выравнивает поле по левому краю в доступном пространстве.
• ^ — Принудительно выравнивает поле по центру в доступном пространстве.
• = — аналогично >, но со знаком и символом слева от любого заполнения.

sign может быть:

• - — ничего для нуля или положительного и знак минус для отрицательного. (Поведение по умолчанию.)
• + — знак плюс для нуля или положительного и знак минус для отрицательного.
• ( — ничего для нуля или положительного и скобки для отрицательного.
• (пробел) — пробел для нуля или положительного и знак минус для отрицательного.

symbol может быть:

• $ — применяет символы валюты в соответствии с определением локали.
• # — для двоичной, восьмеричной или шестнадцатеричной записи — префиксы 0b, 0o, или 0x, соответственно.

Опция zero (0) включает нулевое заполнение; это неявно устанавливает fill в 0 и align в =. width определяет минимальную ширину поля; если не указано, ширина определяется содержимым. Опция comma (,) включает использование разделителя групп, такого как запятая для тысяч.

В зависимости от type, precision либо указывает количество цифр после десятичной точки (типы f и %), либо количество значащих цифр (типы ​, e, g, r, s и p). Если точность не указана, она по умолчанию равна 6 для всех типов, за исключением ​ (нет), который по умолчанию равен 12. Точность игнорируется для целочисленных форматов (типы b, o, d, x, X и c). См. precisionFixed и precisionRound для выбора подходящей точности.

Опция ~ обрезает несущественные хвостовые нули для всех типов форматов. Это наиболее часто используется в сочетании с типами r, e, s и %. Например:

d3.format("s")(1500);  // "1.50000k"
d3.format("~s")(1500); // "1.5k"

Доступные значения type:

• e — экспоненциальная запись.
• f — запись с фиксированной точкой.
• g — либо десятичная, либо экспоненциальная запись, округленная до значащих цифр.
• r — десятичная запись, округленная до значащих цифр.
• s — десятичная запись с префиксом СИ, округленная до значащих цифр.
• % — умножить на 100, а затем десятичная запись со знаком процента.
• p — умножить на 100, округлить до значащих цифр, а затем десятичная запись со знаком процента.
• b — двоичная запись, округленная до целого числа.
• o — восьмеричная запись, округленная до целого числа.
• d — десятичная запись, округленная до целого числа.
• x — шестнадцатеричная запись с использованием строчных букв, округленная до целого числа.
• X — шестнадцатеричная запись с использованием прописных букв, округленная до целого числа.
• c — преобразует целое число в соответствующий символ Unicode перед печатью.

Тип ​ (нет) также поддерживается в качестве сокращения для ~g (с точностью по умолчанию 12 вместо 6), а тип n — в качестве сокращения для ,g. Для типов g, n и ​ (нет) используется десятичная запись, если полученная строка будет содержать precision или меньше цифр; в противном случае используется экспоненциальная запись. Например:

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) Источник

Эквивалентно locale.format, за исключением того, что возвращаемая функция преобразует значения в единицы соответствующего префикса СИ для указанного числового значения value перед форматированием в записи с фиксированной точкой. Поддерживаются следующие префиксы:

• y — йокто, 10⁻²⁴
• z — зепто, 10⁻²¹
• a — атто, 10⁻¹⁸
• f — фемто, 10⁻¹⁵
• p — пико, 10⁻¹²
• n — нано, 10⁻⁹
• µ — микро, 10⁻⁶
• m — милли, 10⁻³
• ​ (нет) — 10⁰
• k — кило, 10³
• M — мега, 10⁶
• G — гига, 10⁹
• T — тера, 10¹²
• P — пета, 10¹⁵
• E — экза, 10¹⁸
• Z — зетта, 10²¹
• Y — йотта, 10²⁴

В отличие от locale.format с форматом s, этот метод возвращает форматировщик с постоянным префиксом СИ, а не вычисляет префикс динамически для каждого числа. Кроме того, precision для данного specifier представляет количество цифр после десятичной точки (как в f записи с фиксированной точкой), а не количество значащих цифр. Например:

var f = d3.formatPrefix(",.0", 1e-6);
f(0.00042); // "420µ"
f(0.0042); // "4,200µ"

Этот метод полезен при форматировании нескольких чисел в одних и тех же единицах для удобства сравнения. См. precisionPrefix для выбора подходящей точности и bl.ocks.org/9764126 для примера.

d3.formatSpecifier(specifier) Источник

Парсит заданный specifier, возвращая объект с открытыми полями, соответствующими мини-языку спецификации формата, и методом toString, который восстанавливает спецификатор. Например, formatSpecifier("s") возвращает:

{
  "fill": " ",
  "align": ">",
  "sign": "-",
  "symbol": "",
  "zero": false,
  "width": undefined,
  "comma": false,
  "precision": undefined,
  "trim": false,
  "type": "s"
}

Этот метод полезен для понимания того, как парсятся спецификаторы формата, и для вывода новых спецификаторов. Например, вы можете вычислить подходящую точность на основе чисел, которые вы хотите отформатировать, используя precisionFixed, а затем создать новый формат:

var s = d3.formatSpecifier("f");
s.precision = d3.precisionFixed(0.01);
var f = d3.format(s);
f(42); // "42.00";

d3.precisionFixed(step) Источник

Возвращает рекомендуемую десятичную точность для фиксированной точки, учитывая заданное значение step. Step представляет собой минимальное абсолютное различие между значениями, которые будут отформатированы. (Предполагается, что значения, которые будут отформатированы, также являются кратными step.) Например, для чисел 1, 1.5 и 2, step должен быть 0.5, а рекомендуемая точность — 1:

var p = d3.precisionFixed(0.5),
    f = d3.format("." + p + "f");
f(1);   // "1.0"
f(1.5); // "1.5"
f(2);   // "2.0"

В то время как для чисел 1, 2 и 3, step должен быть 1, а рекомендуемая точность — 0:

var p = d3.precisionFixed(1),
    f = d3.format("." + p + "f");
f(1); // "1"
f(2); // "2"
f(3); // "3"

Примечание: для типа формата % вычтите два:

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.precisionPrefix(step, value) Источник

Возвращает рекомендуемую десятичную точность для использования с locale.formatPrefix, учитывая указанное числовое значение step и эталонное значение value. Step представляет собой минимальное абсолютное различие между значениями, которые будут отформатированы, а value определяет, какой префикс СИ будет использоваться. (Предполагается, что значения, которые будут отформатированы, также являются кратными step.) Например, для чисел 1.1e6, 1.2e6 и 1.3e6, step должен быть 1e5, value может быть 1.3e6, а рекомендуемая точность — 1:

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.precisionRound(step, max) Источник

Возвращает рекомендуемую десятичную точность для типов формата, которые округляют до значащих цифр, учитывая указанные числовые значения step и max. Step представляет собой минимальное абсолютное различие между значениями, которые будут отформатированы, а max — наибольшее абсолютное значение, которое будет отформатировано. (Предполагается, что значения, которые будут отформатированы, также являются кратными step.) Например, для чисел 0.99, 1.0 и 1.01, step должен быть 0.01, max — 1.01, а рекомендуемая точность — 3:

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"

В то время как для чисел 0.9, 1.0 и 1.1, step должен быть 0.1, max — 1.1, а рекомендуемая точность — 2:

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"

Примечание: для типа формата 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"

Локали

d3.formatLocale(definition) Источник

Возвращает объект locale для указанного definition с методами locale.format и locale.formatPrefix. Definition должен включать следующие свойства:

• decimal - десятичная точка (например, ".").
• thousands - разделитель групп (например, ",").
• grouping - массив размеров групп (например, [3]), циклически используемый по мере необходимости.
• currency - префикс и суффикс валюты (например, ["$", ""]).
• numerals - необязательно; массив из десяти строк для замены цифр от 0 до 9.
• percent - необязательно; суффикс процента (по умолчанию "%").

Обратите внимание, что свойство thousands является неточным, так как определение группировки позволяет группировать числа не только тысячами.

d3.formatDefaultLocale(definition) Источник

Эквивалентно d3.formatLocale, за исключением того, что оно также переопределяет d3.format и d3.formatPrefix на новые методы локализации locale.format и locale.formatPrefix. Если вы не задаете локаль по умолчанию, она устанавливается по умолчанию на Английский (США).