d3-collection

Предупреждение о устаревании: Используйте встроенные в JavaScript классы Map, Set и Object вместо соответствующих методов d3-collection. Используйте методы d3-array’s group и rollup вместо nest из d3-collection.

Удобные структуры данных для элементов с ключами по строкам.

Установка

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

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

var map = d3.map()
    .set("foo", 1)
    .set("bar", 2);

</script>

Справочник API

• Объекты
• Карты
• Множества
• Вложенные структуры

Объекты

Распространённый тип данных в JavaScript — это ассоциативный массив, или проще говоря, объект, который имеет набор именованных свойств. Стандартный механизм для итерации по ключам (или именам свойств) в ассоциативном массиве — это цикл for…in. Однако обратите внимание, что порядок итерации не определён. D3 предоставляет несколько методов для преобразования ассоциативных массивов в стандартные массивы с числовыми индексами.

Предупреждение: соблазнительно использовать обычные объекты как карты, но это приводит к неожиданному поведению, когда используются встроенные имена свойств в качестве ключей, такие как object["__proto__"] = 42 и "hasOwnProperty" in object. Если вы не можете гарантировать, что ключи карты и значения множества будут безопасными, используйте карты и множества (или их эквиваленты ES6) вместо обычных объектов.

d3.keys(object) Source

Возвращает массив, содержащий имена свойств указанного объекта (ассоциативного массива). Порядок возвращаемого массива не определён.

d3.values(object) Source

Возвращает массив, содержащий значения свойств указанного объекта (ассоциативного массива). Порядок возвращаемого массива не определён.

d3.entries(object) Source

Возвращает массив, содержащий ключи и значения свойств указанного объекта (ассоциативного массива). Каждый элемент — это объект с атрибутами key и value, например {key: "foo", value: 42}. Порядок возвращаемого массива не определён.

d3.entries({foo: 42, bar: true}); // [{key: "foo", value: 42}, {key: "bar", value: true}]

Карты

Как ES6 карты, но с некоторыми отличиями:

• Ключи приводятся к строкам.
• map.each, а не map.forEach. (Также нет thisArg.)
• map.remove, а не map.delete.
• map.entries возвращает массив объектов {key, value}, а не итератор [key, value].
• map.size — это метод, а не свойство; также есть map.empty.

d3.map([object[, key]]) Source

Создаёт новую карту. Если object указан, копирует все перечисляемые свойства из указанного объекта в эту карту. Указанный объект также может быть массивом или другой картой. Можно указать опциональный функцию key для вычисления ключа для каждого значения в массиве. Например:

var map = d3.map([{name: "foo"}, {name: "bar"}], function(d) { return d.name; });
map.get("foo"); // {"name": "foo"}
map.get("bar"); // {"name": "bar"}
map.get("baz"); // undefined

См. также вложенные структуры.

map.has(key) Source

Возвращает true только в том случае, если в этой карте есть запись для указанного ключа key. Примечание: значение может быть null или undefined.

map.get(key) Source

Возвращает значение для указанного ключа key. Если в карте нет записи для указанного ключа, возвращает undefined.

map.set(key, value) Source

Устанавливает значение value для указанного ключа key. Если в карте ранее была запись для того же ключа, старая запись заменяется новым значением. Возвращает карту, позволяя цепочку вызовов. Например:

var map = d3.map()
    .set("foo", 1)
    .set("bar", 2)
    .set("baz", 3);

map.get("foo"); // 1

map.remove(key) Source

Если в карте есть запись для указанного ключа key, удаляет запись и возвращает true. В противном случае этот метод ничего не делает и возвращает false.

map.clear() Source

Удаляет все записи из этой карты.

map.keys() Source

Возвращает массив строковых ключей для каждой записи в этой карте. Порядок возвращаемых ключей произвольный.

map.values() Source

Возвращает массив значений для каждой записи в этой карте. Порядок возвращаемых значений произвольный.

map.entries() Source

Возвращает массив объектов ключ-значение для каждой записи в этой карте. Порядок возвращаемых записей произвольный. Ключ каждой записи — это строка, но значение имеет произвольный тип.

map.each(function) Source

Вызывает указанную функцию function для каждой записи в этой карте, передавая значение и ключ записи в качестве аргументов, а затем саму карту. Возвращает undefined. Порядок итерации произвольный.

map.empty() Source

Возвращает true только в том случае, если в этой карте нет записей.

map.size() Source

Возвращает количество записей в этой карте.

Множества

Как ES6 множества, но с некоторыми отличиями:

• Значения приводятся к строкам.
• set.each, а не set.forEach. (Также нет thisArg.)
• set.remove, а не set.delete.
• set.size — это метод, а не свойство; также есть set.empty.

d3.set([array[, accessor]]) Source

Создаёт новое множество. Если array указан, добавляет заданный массив строковых значений в возвращаемое множество. Указанный массив также может быть другим множеством. Можно указать опциональную функцию accessor, что эквивалентно вызову array.map(accessor) перед созданием множества.

set.has(value) Source

Возвращает true только в том случае, если в этом множестве есть запись для указанного значения value.

set.add(value) Source

Добавляет указанное значение value в это множество. Возвращает множество, позволяя цепочку вызовов. Например:

var set = d3.set()
    .add("foo")
    .add("bar")
    .add("baz");

set.has("foo"); // true

set.remove(value) Source

Если множество содержит указанное значение value, удаляет его и возвращает true. В противном случае этот метод ничего не делает и возвращает false.

set.clear() Source

Удаляет все значения из этого множества.

set.values() Source

Возвращает массив строковых значений в этом множестве. Порядок возвращаемых значений произвольный. Может использоваться в качестве удобного способа вычисления уникальных значений для набора строк. Например:

d3.set(["foo", "bar", "foo", "baz"]).values(); // "foo", "bar", "baz"

set.each(function) Source

Вызывает указанную функцию function для каждого значения в этом множестве, передавая значение в качестве первых двух аргументов (для симметрии с map.each), а затем само множество. Возвращает undefined. Порядок итерации произвольный.

set.empty() Source

Возвращает true тогда и только тогда, когда в этом множестве нет значений.

set.size() Source

Возвращает количество значений в этом множестве.

Вложенность

Вложенность позволяет группировать элементы в массиве в иерархическую древовидную структуру; представьте себе оператор GROUP BY в SQL, за исключением того, что у вас может быть несколько уровней группировки, а результирующий вывод — дерево, а не плоская таблица. Уровни дерева задаются функциями ключей. Листовые узлы дерева можно отсортировать по значению, а внутренние узлы — по ключу. Дополнительная функция сворачивания позволит объединить элементы в каждом листовом узле с помощью функции сводки. Оператор вложенности (объект, возвращаемый nest) является многоразовым и не сохраняет никаких ссылок на данные, которые вложены.

Например, рассмотрим следующую табличную структуру данных о урожайности ячменя, полученную с различных участков в Миннесоте в период 1931-2 годов:

var yields = [
  {yield: 27.00, variety: "Manchuria", year: 1931, site: "University Farm"},
  {yield: 48.87, variety: "Manchuria", year: 1931, site: "Waseca"},
  {yield: 27.43, variety: "Manchuria", year: 1931, site: "Morris"},
  ...
];

Для облегчения визуализации может быть полезно сначала вложить элементы по году, а затем по сорту, как показано ниже:

var entries = d3.nest()
    .key(function(d) { return d.year; })
    .key(function(d) { return d.variety; })
    .entries(yields);

Это возвращает вложенный массив. Каждый элемент внешнего массива представляет собой пару ключ-значение, перечисляющую значения для каждого уникального ключа:

[{key: "1931", values: [
   {key: "Manchuria", values: [
     {yield: 27.00, variety: "Manchuria", year: 1931, site: "University Farm"},
     {yield: 48.87, variety: "Manchuria", year: 1931, site: "Waseca"},
     {yield: 27.43, variety: "Manchuria", year: 1931, site: "Morris"}, ...]},
   {key: "Glabron", values: [
     {yield: 43.07, variety: "Glabron", year: 1931, site: "University Farm"},
     {yield: 55.20, variety: "Glabron", year: 1931, site: "Waseca"}, ...]}, ...]},
 {key: "1932", values: ...}]

Вложенный формат позволяет легко итерировать и генерировать иерархические структуры в SVG или HTML.

Для более подробного введения во вложенность см.:

• Учебник и примеры вложенности D3 от Фёби Брайт D3 Nest Tutorial and examples
• «Мистер Вложенный» от Шана Картера Mister Nester

d3.nest() Source

Создаёт новый оператор вложенности. Набор ключей изначально пуст.

nest.key(key) Source

Регистрирует новую функцию key. Функция key будет вызываться для каждого элемента в входном массиве и должна возвращать строковый идентификатор для назначения элемента в его группу. Чаще всего функция является простым аксессором, например, аксессоры года и сорта выше. (Функциям ключей не передаётся индекс элемента в входном массиве). Каждый раз при регистрации ключа он добавляется в конец внутреннего массива ключей, и оператор вложенности применяет дополнительный уровень вложенности.

nest.sortKeys(comparator) Source

Сортирует значения ключей для текущего ключа с использованием заданной функции сравнения comparator, например, d3.ascending или d3.descending. Если для текущего ключа не указан сравниватель, порядок возврата ключей не определён. Например, чтобы отсортировать годы по возрастанию, а сорта — по убыванию:

var entries = d3.nest()
    .key(function(d) { return d.year; }).sortKeys(d3.ascending)
    .key(function(d) { return d.variety; }).sortKeys(d3.descending)
    .entries(yields);

Обратите внимание, что это влияет только на результат nest.entries; порядок ключей, возвращаемых методами nest.map и nest.object, всегда не определён, независимо от сравнителя.

nest.sortValues(comparator) Source

Сортирует листовые элементы с помощью заданной функции сравнения comparator, например, d3.ascending или d3.descending. Это примерно эквивалентно сортировке входного массива перед применением оператора вложенности; однако, обычно это более эффективно, поскольку размер каждой группы меньше. Если не указан сравниватель значений, элементы будут возвращены в порядке их появления во входном массиве. Это относится к nest.map, nest.entries и nest.object.

nest.rollup(function) Source

Указывает функцию сворачивания function, которая будет применяться к каждой группе листовых элементов. Возвращаемое значение функции сворачивания заменит массив значений листовых элементов либо в ассоциативном массиве, возвращаемом nest.map, либо nest.object; для nest.entries оно заменит entry.values на entry.value. Если указан сравниватель листовых элементов, листовые элементы сортируются перед вызовом функции сворачивания.

nest.map(array) Source

Применяет оператор вложенности к указанному массиву array, возвращая вложенную карту. Каждый элемент в возвращаемой карте соответствует уникальному значению ключа, возвращаемому первой функцией ключа. Значение элемента зависит от количества зарегистрированных функций ключа: если есть дополнительный ключ, значение — это ещё одна карта; в противном случае значение — массив элементов, отфильтрованных из входного массива array, которые имеют данное значение ключа. Если ключи не определены, возвращает входной массив array.

nest.object(array) Source

Применяет оператор вложенности к указанному массиву array, возвращая вложенный объект. Каждый элемент в возвращаемом ассоциативном массиве соответствует уникальному значению ключа, возвращаемому первой функцией ключа. Значение элемента зависит от количества зарегистрированных функций ключа: если есть дополнительный ключ, значение — это ещё один ассоциативный массив; в противном случае значение — массив элементов, отфильтрованных из входного массива array, которые имеют данное значение ключа.

Примечание: этот метод небезопасен, если какой-либо из ключей конфликтует со встроенными свойствами JavaScript, такими как __proto__. Если вы не можете гарантировать, что ключи будут безопасными, следует использовать nest.map вместо него.

nest.entries(array) Source

Применяет оператор вложенности к указанному массиву array, возвращая массив записей ключ-значение. По сути, это аналогично применению map.entries к ассоциативному массиву, возвращаемому nest.map, но это применяется ко всем уровням иерархии, а не только к первому (внешнему) уровню. Каждый элемент в возвращаемом массиве соответствует уникальному значению ключа, возвращаемому первой функцией ключа. Значение элемента зависит от количества зарегистрированных функций ключа: если есть дополнительный ключ, значение — это другой вложенный массив записей; в противном случае значение — массив элементов, отфильтрованных из входного массива array, которые имеют данное значение ключа.