d3-collection

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

Установка

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

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

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

</script>

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

Справочник API

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

Объекты

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

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

d3.keys(object) Исходный код

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

d3.values(object) Исходный код

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

d3.entries(object) Исходный код

Возвращает массив, содержащий ключи и значения свойств указанного объекта (ассоциативного массива). Каждый элемент — объект с атрибутами 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]]) Исходный код

Создаёт новую карту. Если 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) Исходный код

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

map.get(key) Исходный код

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

map.set(key, value) Исходный код

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

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

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

map.remove(key) Исходный код

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

map.clear() Исходный код

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

map.keys() Исходный код

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

map.values() Исходный код

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

map.entries() Исходный код

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

map.each(function) Исходный код

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

map.empty() Исходный код

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

map.size() Исходный код

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

Множества

Подобно ES6 Множествам, но с некоторыми отличиями:

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

d3.set([array[, accessor]]) Исходный код

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

set.has(value) Исходный код

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

set.add(value) Исходный код

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

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

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

set.remove(value) Исходный код

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

set.clear() Исходный код

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

set.values() Исходный код

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

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

set.each(function) Исходный код

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

set.empty() Исходный код

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

set.size() Исходный код

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

Вложенные структуры

Гнездование позволяет группировать элементы массива в иерархическую древовидную структуру; представьте себе оператор GROUP BY в SQL, за исключением того, что у вас может быть несколько уровней группировки, а результат — дерево, а не плоская таблица. Уровни в дереве определяются функциями ключей. Листья дерева могут быть отсортированы по значению, а внутренние узлы — по ключу. Необязательная функция сворачивания (rollup) объединит элементы в каждом листе, используя сводную функцию. Оператор gнездования (объект, возвращаемый 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 от Шэна Картера 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; однако, обычно это более эффективно, так как размер каждой группы меньше. Если компаратор значений не указан, элементы будут возвращены в порядке их появления во входном массиве. Это относится к nest.map, nest.entries и nest.object.

nest.rollup(function) Source

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

nest.map(array) Source

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

nest.object(array) Source

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

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

nest.entries(array) Source

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