d3-collection

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

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

Установка

Если вы используете NPM, npm install d3-collection. В противном случае, скачайте последнюю версию. Вы также можете загрузить напрямую с d3js.org, как отдельную библиотеку или как часть 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) Исходный код

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

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) Source

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

set.empty() Source

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

set.size() Source

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

Вложенность

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

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

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 от Phoebe Bright D3 Nest Tutorial and examples
• Mister Nester от Shan Carter’s 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, возвращая вложенный map. Каждый элемент в возвращаемом map соответствует уникальному значению ключа, возвращенному первой функцией ключа. Значение элемента зависит от количества зарегистрированных функций ключа: если есть дополнительный ключ, значение — это другой map; в противном случае значение — это массив элементов, отфильтрованных из входного array, имеющих данное значение ключа. Если ключи не определены, возвращается входной array.

nest.object(array) Source

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

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

nest.entries(array) Source

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