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>

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

Справочник API

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

Объекты

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

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

d3.keys(объект) Источник

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

d3.values(объект) Источник

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

d3.entries(объект) Источник

Возвращает массив, содержащий ключи и значения свойств указанного объекта (ассоциативный массив). Каждый элемент — это объект с атрибутами 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 возвращает массив объектов {ключ, значение}, а не итератор [ключ, значение].
• map.size — метод, а не свойство; также есть map.empty.

d3.map([объект[, ключ]]) Источник

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

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

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

карта.has(ключ) Источник

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

карта.get(ключ) Источник

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

карта.set(ключ, значение) Источник

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

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

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

карта.remove(ключ) Источник

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

карта.clear() Источник

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

карта.keys() Источник

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

карта.values() Источник

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

карта.entries() Источник

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

карта.each(функция) Источник

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

карта.empty() Источник

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

карта.size() Источник

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

Множества

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

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

d3.set([массив[, обработчик]]) Источник

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

множество.has(значение) Источник

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

множество.add(значение) Источник

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

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

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

множество.remove(значение) Источник

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

множество.clear() Источник

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

множество.values() Источник

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

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

множество.each(функция) Источник

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

множество.empty() Источник

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

множество.size() Источник

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

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

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

nest.rollup(function) Source

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

nest.map(array) Source

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

nest.object(array) Source

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

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

nest.entries(array) Source

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