API вспомогательных функций
В Vega используются вспомогательные функции JavaScript: генераторы функций, проверка типов, журналирование и методы для объектов, массивов и строк. Они доступны через объект верхнего уровня vega, а отдельно — через пакет vega-util. Методы для дат и времени приведены в справочнике API работы со временем.
Справочник API вспомогательных функций
Функции
Функции и генераторы функций для доступа к значениям и их сравнения.
# vega.accessor(function[, fields, name]) Исходный код
Добавляет к экземпляру function сведения о зависимых полях данных fields (массив строк) и имя name, затем возвращает ту же функцию. Предполагается, что функция принимает объект записи данных, а строки fields называют его свойства, к которым она обращается. Если такую функцию использовать для доступа к полям, Vega сможет отслеживать зависимости и задавать подходящие имена результатов, например при агрегации.
Внутри метод записывает массив полей в свойство fields, а имя — в fname переданной функции. Не обращайтесь к этим свойствам напрямую: для совместимости с будущими версиями используйте accessorFields и accessorName.
# vega.accessorFields(accessor) Исходный код
Возвращает массив имён зависимых полей функции accessor. Если у функции нет сведений о полях, возвращает undefined; если сам аргумент accessor равен null или undefined, возвращает null.
# vega.accessorName(accessor) Исходный код
Возвращает имя функции accessor. Если у функции нет имени accessor, возвращает undefined; если сам аргумент accessor равен null или undefined, возвращает null.
# vega.ascending(a, b) Исходный код
Функция сравнения для сортировки простых значений и объектов Date по возрастанию.
# vega.compare(fields[, orders]) Исходный код
Создаёт функцию сравнения для сортировки по полям fields и необязательным направлениям orders. fields может быть строкой, функцией доступа или массивом таких значений. Строки называют свойства объекта в порядке приоритета; допустимы вложенные пути, например foo.bar.baz. orders — строка или массив строк 'ascending' (по возрастанию) и 'descending' (по убыванию) для соответствующих полей. Если значение не задано, массив короче fields или содержит недопустимую строку, соответствующее поле сортируется по возрастанию.
# vega.constant(value) Исходный код
Для входного value возвращает функцию, которая выдаёт это значение. Если value само является функцией, возвращает её без изменений.
# vega.debounce(delay, func) Исходный код
Создаёт функцию с задержкой вызова func: она срабатывает, когда с последнего обращения прошло delay миллисекунд. В func передаётся не более одного аргумента; контекст this не сохраняется.
# vega.field(field[, name]) Исходный код
Создаёт функцию доступа к значению поля field. Строка field может содержать вложенные свойства, например foo.bar.baz. Необязательный name задаёт имя функции; по умолчанию используется строка поля. Подробнее см. accessor.
var fooField = vega.field('foo');
fooField({foo: 5}); // 5
vega.accessorName(fooField); // 'foo'
vega.accessorFields(fooField); // ['foo']
var pathField = vega.field('foo.bar', 'path');
pathField({foo: {bar: 'vega'}}); // 'vega'
pathField({foo: 5}); // undefined
vega.accessorName(pathField); // 'path'
vega.accessorFields(pathField); // ['foo.bar']
# vega.id(object) Исходный код
Функция доступа, возвращающая свойство id объекта object.
# vega.identity(value) Исходный код
Функция доступа, возвращающая свой аргумент value без изменений.
# vega.key(fields[, flat]) Исходный код
Создаёт функцию доступа, возвращающую строковый ключ для набора полей объекта fields. Ключ подходит для использования как имя свойства. fields — строка или массив строк с именами свойств входного объекта. Полученная функция является экземпляром accessor с именем 'key'. Необязательный логический flat определяет, считать ли имена полей буквальными, не разбирая точечную и скобочную запись вложенных свойств. По умолчанию flat равен false, поэтому вложенные свойства распознаются.
var keyf = vega.key(['foo', 'bar']);
keyf({foo:'hi', bar:5}); // 'hi|5'
vega.accessorName(keyf); // 'key'
vega.accessorFields(keyf); // ['foo', 'bar']
# vega.one() Исходный код
Функция доступа, всегда возвращающая единицу (1).
# vega.zero() Исходный код
Функция доступа, всегда возвращающая ноль (0).
# vega.truthy() Исходный код
Функция доступа, всегда возвращающая логическое значение true.
# vega.falsy() Исходный код
Функция доступа, всегда возвращающая логическое значение false.
Проверка типов
Функции для проверки типов значений JavaScript.
# vega.isArray(value) Исходный код
Возвращает true, если value — массив Array, иначе false.
# vega.isBoolean(value) Исходный код
Возвращает true, если value имеет тип Boolean, иначе false.
# vega.isDate(value) Исходный код
Возвращает true, если value — объект Date, иначе false.
# vega.isFunction(value) Исходный код
Возвращает true, если value — функция, иначе false.
# vega.isIterable(value) Исходный код
Возвращает true, если value поддерживает протокол итерации, иначе false.
# vega.isNumber(value) Исходный код
Возвращает true, если value имеет тип Number, иначе false.
# vega.isObject(value) Исходный код
Возвращает true, если value — объект, иначе false.
# vega.isRegExp(value) Исходный код
Возвращает true, если value — регулярное выражение RegExp, иначе false.
# vega.isString(value) Исходный код
Возвращает true, если value имеет тип String, иначе false.
Преобразование типов
Функции для преобразования значений к нужному типу.
# vega.toBoolean(value) Исходный код
Преобразует value к логическому типу. Строки "true" и "1" дают true, строки "false" и "0" — false. Пустые строки и значения null дают null.
# vega.toDate(value[, parser]) Исходный код
Преобразует value к временной метке Date. Пустые строки и значения null дают null, а объекты Date возвращаются без изменений. Если задана функция parser, она разбирает дату. По умолчанию числа (временные метки) возвращаются без изменений, а для остальных значений вызывается Date.parse. Учтите, что реализация Date.parse различается между браузерами.
# vega.toNumber(value) Исходный код
Преобразует value к числу. Пустые строки и значения null дают null.
# vega.toString(value) Исходный код
Преобразует value к строке. Пустые строки и значения null дают null.
Объекты
Функции для работы с объектами JavaScript.
# vega.extend(target[, source1, source2, …]) Исходный код
Дополняет объект target, последовательно копируя все перечисляемые свойства входных объектов source.
# vega.hasOwnProperty(object, property) Исходный код
Возвращает true, если свойство property определено непосредственно в объекте object, иначе false. Свойства в цепочке прототипов не учитываются. Метод аналогичен Object.prototype.hasOwnProperty, но защищён от переопределения встроенных методов прототипа объекта.
# vega.inherits(child, parent[, members]) Исходный код
Удобный метод настройки наследования объектов. Задаёт свойство prototype функции child так, чтобы она наследовала свойства прототипа parent. Необязательный объект members содержит методы или свойства, добавляемые в новый прототип дочерней функции. Возвращает этот прототип.
# vega.lruCache([maxsize]) Исходный код
Создаёт кеш пар «ключ — значение» со строковыми ключами. Когда кеш заполнен, из него удаляются записи, к которым дольше всего не обращались (LRU). Поддерживаются методы has, get, set и clear. Необязательный maxsize (по умолчанию 10 000) задаёт максимальное число элементов до вытеснения.
Внутри используются два кеша: текущий и предыдущий. Когда текущий заполняется, он становится предыдущим, а вместо него создаётся пустой. Последующие вызовы get переносят найденные в предыдущем кеше записи в текущий. При следующем заполнении кеши снова меняются местами, а оставшиеся в предыдущем кеше давно неиспользуемые записи удаляются.
var cache = vega.lruCache(1); // кеш на один элемент для примера
cache.set('a', 1); // в текущем кеше a->1
cache.set('b', 2); // в текущем b->2, в предыдущем a->1
cache.get('a'); // -> 1 (a в текущем кеше, b в предыдущем)
cache.set('c', 3); // в текущем c->3, в предыдущем a->1
cache.has('c'); // -> true (c в текущем кеше)
cache.has('b'); // -> false (b удалён)
cache.has('a'); // -> true (a в предыдущем кеше)
cache.get('c'); // -> 3
cache.clear();
# vega.fastmap([object]) Исходный код
Создаёт отображение пар «ключ — значение» со строковыми ключами. Поддерживает часть API Map из ES6: методы has, get, set, delete, clear и свойство size. Если передать необязательный object, все его пары ключей и значений добавляются в новое отображение.
var map = vega.fastmap({foo:1, bar:2});
map.has('foo'); // -> true
map.get('foo'); // -> 1
map.delete('bar');
map.has('bar'); // -> false
map.set('baz', 0);
map.get('baz'); // -> 0
map.size; // -> 2
map.empty; // -> 1 (число пустых записей)
map.clean(); // очистить пустые записи
fastmap работает быстро, поскольку хеширует значения в обычных объектах JavaScript и не вызывает встроенный оператор delete. Однако при частых удалениях структура разрастается и требует периодической очистки. Метод clean удаляет пустые записи. Метод test позволяет задать или получить необязательную функцию-предикат: она отмечает дополнительные объекты, которые следует удалить при очистке, помимо пустых записей.
# vega.mergeConfig(…config) Исходный код
Объединяет несколько объектов конфигурации Vega в один. Объекты, переданные позднее, имеют больший приоритет и могут переопределять настройки предыдущих.
# vega.writeConfig(config, key, value[, recurse]) Исходный код
Записывает value по ключу key в объект конфигурации Vega config. Параметр recurse определяет, объединять ли вложенные значения вместо перезаписи. При false или undefined вложенное объединение не выполняется; при true выполняется на одном уровне. Если recurse — объект, объединяются на одном уровне только ключи, для которых в нём указано истинное значение. Это вспомогательный метод mergeConfig.
Массивы
Функции для работы с массивами JavaScript.
# vega.array(value) Исходный код
Гарантирует, что результат имеет тип Array. Если value уже массив, возвращает его без изменений. Для null и undefined возвращает пустой массив []; остальные значения оборачивает в новый массив [value] из одного элемента.
# vega.clampRange(range, min, max) Исходный код
Ограничивает диапазон, сохраняя его протяжённость. Если длина входного range меньше (max − min), но одна из границ выходит за min или max, диапазон сдвигается без изменения длины так, чтобы его граница совпала с допустимой. Если длина range больше (max − min), возвращает [min, max].
# vega.extent(array[, accessor]) Исходный код
Возвращает минимум и максимум массива array в виде [min, max]. Значения null, undefined и NaN игнорируются. Необязательная функция accessor применяется к каждому элементу перед сравнением.
# vega.extentIndex(array[, accessor]) Исходный код
Возвращает индексы минимального и максимального значений массива array в виде [minIndex, maxIndex] согласно естественному порядку. Необязательная функция accessor применяется к каждому элементу перед сравнением.
vega.extentIndex([1,5,3,0,4,2]); // [3, 1]
vega.extentIndex([
{a: 3, b:2},
{a: 2, b:1},
{a: 1, b:3}
], vega.field('b')); // [1, 2]
# vega.flush(range, value, threshold, left, right, center) Исходный код
Выбирает результат по близости value к границам числового range. Возвращает left, если расстояние от value до минимальной границы не превышает threshold, и right, если оно не превышает threshold до максимальной границы. В остальных случаях возвращает center.
# vega.inrange(value, range[, left, right]) Исходный код
Возвращает true, если value находится в пределах массива range. Логические параметры left и right определяют, включать ли соответствующие границы (true) или исключать (false). По умолчанию обе границы включены.
# vega.lerp(array, fraction) Исходный код
Возвращает результат линейной интерполяции между первым и последним элементами array для доли fraction (обычно от 0 до 1). Например, lerp([0, 50], 0.5) возвращает 25.
# vega.merge(compare, array1, array2[, output]) Исходный код
Объединяет два отсортированных массива в один отсортированный массив. Функция compare должна сравнивать элементы в том же порядке, в котором уже отсортированы array1 и array2. Если указан output, результат записывается в него; иначе создаётся и возвращается новый массив.
# vega.panLinear(domain, delta) Исходный код
Для числового domain, отсортированного по возрастанию, возвращает новый диапазон, сдвинутый на delta с помощью линейного преобразования. delta задаётся долей текущей длины диапазона; знак определяет направление сдвига. Результат — массив из начальной и конечной границ сдвинутого диапазона.
# vega.panLog(domain, delta) Исходный код
Для числового domain, отсортированного по возрастанию, возвращает новый диапазон, сдвинутый на delta с помощью логарифмического преобразования. delta задаётся долей длины диапазона после соответствующего преобразования; знак определяет направление сдвига. Результат — массив из начальной и конечной границ сдвинутого диапазона.
# vega.panPow(domain, delta, exponent) Исходный код
Для числового domain, отсортированного по возрастанию, возвращает новый диапазон, сдвинутый на delta с помощью степенного преобразования с показателем exponent. delta задаётся долей длины диапазона после соответствующего преобразования; знак определяет направление сдвига. Результат — массив из начальной и конечной границ сдвинутого диапазона.
# vega.panSymlog(domain, delta, constant) Исходный код
Для числового domain, отсортированного по возрастанию, возвращает новый диапазон, сдвинутый на delta с помощью симметричного логарифмического преобразования с параметром constant. delta задаётся долей длины диапазона после соответствующего преобразования; знак определяет направление сдвига. Результат — массив из начальной и конечной границ сдвинутого диапазона.
# vega.peek(array) Исходный код
Возвращает последний элемент array, не удаляя его. Это удобная запись выражения array[array.length - 1], похожая на Array.pop без изменения массива.
# vega.span(array) Исходный код
Возвращает числовую протяжённость array: разность последнего и первого значений.
# vega.toSet(array) Исходный код
По массиву значений array создаёт объект, в котором каждое значение становится ключом со значением true. Элементы массива преобразуются в строки, поэтому должны давать подходящие строковые ключи.
vega.toSet([1, 2, 3]); // {'1':true, '2':true, '3':true}
# vega.visitArray(array, [filter,] visitor) Исходный код
Обходит элементы array и вызывает visitor для каждого значения, прошедшего необязательный filter. Фильтр вызывается с каждым элементом. Если его результат истинный, именно этот результат передаётся visitor: фильтр может одновременно преобразовывать значение. Без фильтра обработчик получает все элементы массива. Подобно Array.forEach, visitor вызывается с тремя аргументами: значением, индексом и ссылкой на исходный массив.
// вывод в консоль: 1 0; 3 2
vega.visitArray([0, -1, 2],
function(x) { return x + 1; },
function(v, i, array) { console.log(v, i); });
# vega.zoomLinear(domain, anchor, scale) Исходный код
Для числового domain, отсортированного по возрастанию, возвращает диапазон, масштабированный с коэффициентом scale линейным преобразованием относительно точки anchor. Если anchor равен null, используется середина диапазона. Результат — массив из начальной и конечной границ масштабированного диапазона.
# vega.zoomLog(domain, anchor, scale) Исходный код
Для числового domain, отсортированного по возрастанию, возвращает диапазон, масштабированный с коэффициентом scale логарифмическим преобразованием относительно точки anchor. Если anchor равен null, используется середина диапазона в преобразованном пространстве, затем выполняется обратное преобразование. Результат — массив из начальной и конечной границ масштабированного диапазона.
# vega.zoomPow(domain, anchor, scale, exponent) Исходный код
Для числового domain, отсортированного по возрастанию, возвращает диапазон, масштабированный с коэффициентом scale степенным преобразованием с показателем exponent относительно точки anchor. Если anchor равен null, используется середина диапазона в преобразованном пространстве, затем выполняется обратное преобразование. Результат — массив из начальной и конечной границ масштабированного диапазона.
# vega.zoomSymlog(domain, anchor, scale, constant) Исходный код
Для числового domain, отсортированного по возрастанию, возвращает диапазон, масштабированный с коэффициентом scale симметричным логарифмическим преобразованием с параметром constant относительно точки anchor. Если anchor равен null, используется середина диапазона в преобразованном пространстве, затем выполняется обратное преобразование. Результат — массив из начальной и конечной границ масштабированного диапазона.
Даты
Функции для работы с датами JavaScript.
# vega.quarter(date) Исходный код
Возвращает квартал года — целое число от 1 до 4 — для объекта или временной метки date в местном часовом поясе.
# vega.utcquarter(date) Исходный код
Возвращает квартал года — целое число от 1 до 4 — для объекта или временной метки date по времени UTC.
Строки
Функции для создания и обработки строк JavaScript.
# vega.pad(string, length[, character, align]) Исходный код
Дополняет string повторениями символа character до длины length. По умолчанию используется пробел (' '), а символы добавляются в конец. Необязательный align задаёт расположение дополнения: 'left' (перед строкой), 'center' (по обеим сторонам, чтобы исходная строка оказалась по центру) или 'right' (после строки).
vega.pad('15', 5, '0', 'left'); // '00015'
# vega.repeat(string, count) Исходный код
Возвращает новую строку, повторяющую string число раз, заданное count.
vega.repeat('0', 5); // '00000'
# vega.splitAccessPath(path) Исходный код
Разбивает строку пути path к свойству объекта JavaScript на массив составляющих пути.
vega.splitAccessPath('foo'); // ['foo']
vega.splitAccessPath('foo.bar'); // ['foo', 'bar']
vega.splitAccessPath('foo["bar"]'); // ['foo', 'bar']
vega.splitAccessPath('foo[0].bar'); // ['foo', '0', 'bar']
# vega.stringValue(value) Исходный код
Возвращает представление входного значения, допустимое одновременно в JSON и JavaScript. Для объектов и строк вывод создаётся через JSON.stringify. Простые значения, например числа и логические значения, возвращаются без изменений. Метод пригодится при создании значений для фрагментов кода, компилируемых во время выполнения, например через конструктор Function.
# vega.truncate(string, length[, align, ellipsis]) Исходный код
Обрезает string до длины length. Необязательный align определяет, какую часть удалить: 'left' (начало), 'center' (середину) или 'right' (конец). По умолчанию обрезается конец. Необязательный ellipsis задаёт обозначение пропуска; по умолчанию это многоточие (…, символ \u2026).
Журналирование
# vega.logger([level, method]) Исходный код
Создаёт объект журнала для выборочного вывода сообщений в консоль JavaScript. Необязательный level задаёт начальный уровень: None, Error, Warn, Info или Debug. По умолчанию используется None.
Созданный объект предоставляет следующие методы:
- level(value): задаёт текущий уровень. В консоль выводятся сообщения, уровень которых не выше value.
- error(message1[, message2, …]): выводит ошибку через
console.error, если текущий уровень не ниже Error. - warn(message1[, message2, …]): выводит предупреждение через
console.warn, если текущий уровень не ниже Warn. - info(message1[, message2, …]): выводит информационное сообщение через
console.log, если текущий уровень не ниже Info. - debug(message1[, message2, …]): выводит отладочное сообщение через
console.log, если текущий уровень не ниже Debug.
Чтобы направить все сообщения через один метод консоли вместо автоматического выбора между console.log, console.warn и console.error, передайте необязательный аргумент method: "log", "warn" или "error".
# vega.None Исходный код
Константа уровня None. Если задать её объекту logger, вывод всех сообщений будет отключён.
# vega.Error Исходный код
Константа уровня Error. При таком уровне logger выводит только ошибки.
# vega.Warn Исходный код
Константа уровня Warn. При таком уровне logger выводит ошибки и предупреждения.
# vega.Info Исходный код
Константа уровня Info. При таком уровне logger выводит ошибки, предупреждения и информационные сообщения.
# vega.Debug Исходный код
Константа уровня Debug. При таком уровне logger выводит все сообщения: ошибки, предупреждения, информационные и отладочные.
Ошибки
# vega.error(message) Исходный код
Создаёт и выбрасывает ошибку с текстом message. Вспомогательный метод позволяет, например, включать ошибки в цепочки выражений.
vega.error('Uh oh'); // эквивалентно throw Error('Uh oh')
// включить ошибку в выражение
return isOk ? returnValue : vega.error('Not OK');