d3-time

При визуализации временных рядов, анализе временных закономерностей или работе с временем в целом быстро становится очевидной неравномерность обычных единиц времени. Например, в григорианском календаре большинство месяцев имеют 31 день, но некоторые имеют 28, 29 или 30; большинство лет имеют 365 дней, но високосные годы имеют 366; и с переходом на летнее время большинство дней имеют 24 часа, но некоторые имеют 23 или 25. Сложность усугубляется тем, что правила перехода на летнее время различаются по всему миру.

Вследствие этих временных особенностей, выполнение, казалось бы, тривиальных задач может оказаться затруднительным. Например, если вы хотите вычислить количество прошедших дней между двумя датами, вы не можете просто вычесть и разделить на 24 часа (86 400 000 мс):

start = new Date(2015, 02, 01) // 2015-03-01T00:00
end = new Date(2015, 03, 01) // 2015-04-01T00:00
(end - start) / 864e5 // 30.958333333333332, oops! 🤯

Однако вы можете использовать d3.timeDay.count:

d3.timeDay.count(start, end) // 31 😌

Интервал дня интервала является одним из нескольких, предоставляемых модулем d3-time. Каждый интервал представляет собой стандартную временную единицу — часов, недель, месяцев и т. д. — и имеет методы для расчета граничных дат. Например, d3.timeDay вычисляет полночь (обычно 00:00 по местному времени) соответствующего дня. В дополнение к округлению и подсчёту, интервалы также могут использоваться для генерации массивов граничных дат. Например, для вычисления каждого воскресенья текущего месяца:

start = d3.timeMonth.floor() // 2015-01-01T00:00
stop = d3.timeMonth.ceil() // 2015-02-01T00:00
d3.timeWeek.range(start, stop) // [2015-01-07T00:00, 2015-01-14T00:00, 2015-01-21T00:00, 2015-01-28T00:00]

Модуль d3-time не реализует собственную систему календарей; он просто реализует удобный API для календарных вычислений на основе ECMAScript Date. Таким образом, он игнорирует високосные секунды и может работать только с местным часовым поясом и координированным универсальным временем (UTC).

Этот модуль используется масштабами времени D3 для генерации разумных делений, форматом времени D3, а также может использоваться напрямую для выполнения таких задач, как календарные макеты.

Установка

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

<script src="https://d3js.org/d3-array.v2.min.js"></script>
<script src="https://d3js.org/d3-time.v2.min.js"></script>
<script>

const day = d3.timeDay(new Date);

</script>

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

Справочник API

interval([date]) · Источник

Эквивалентно interval.floor, за исключением того, что если date не указан, по умолчанию используется текущее время. Например, d3.timeYear(date) и d3.timeYear.floor(date) эквивалентны.

monday = d3.timeMonday() // the latest preceeding Monday, local time

interval.floor(date) · Источник

Возвращает новую дату, представляющую последнюю границу интервала до или равную date. Например, d3.timeDay.floor(date) обычно возвращает 00:00 по местному времени на заданную date.

Этот метод идемпотентен: если заданная date уже выровнена по текущему интервалу, возвращается новая дата с идентичным временем. Кроме того, возвращаемая дата является минимальным выразимым значением связанного интервала, таким образом, interval.floor(interval.floor(date) - 1) возвращает дату предыдущей границы интервала.

Обратите внимание, что операторы == и === не сравнивают значения с объектами Date, и поэтому вы не можете использовать их для определения того, уже ли заданная date выровнена. Вместо этого преобразуйте к числу и затем сравнивайте:

// Returns true if the specified date is a day boundary.
function isDay(date) {
  return +d3.timeDay.floor(date) === +date;
}

Это более надёжно, чем проверка того, является ли время 00:00, поскольку в некоторых часовых поясах полночь может отсутствовать из-за перехода на летнее время.

interval.round(date) · Источник

Возвращает новую дату, представляющую ближайшую границу интервала к date. Например, d3.timeDay.round(date) обычно возвращает 00:00 по местному времени на заданную date, если она находится до или равна полудню, и 00:00 следующего дня, если она после полудня.

Этот метод идемпотентен: если заданная date уже округляется до текущего интервала, возвращается новая дата с идентичным временем.

interval.ceil(date) · Источник

Возвращает новую дату, представляющую самую раннюю границу интервала после или равную date. Например, d3.timeDay.ceil(date) обычно возвращает 00:00 по местному времени на день, следующий за заданной date.

Этот метод идемпотентен: если заданная date уже округляется до потолка текущего интервала, возвращается новая дата с идентичным временем. Кроме того, возвращаемая дата является максимальным выразимым значением связанного интервала, таким образом, interval.ceil(interval.ceil(date) + 1) возвращает дату следующей границы интервала.

interval.offset(date[, step]) · Источник

Возвращает новую дату, равную date плюс step интервалов. Если step не указан, по умолчанию он равен 1. Если step отрицательный, возвращаемая дата будет раньше указанной date; если step равен нулю, возвращается копия указанной date; если step не является целым числом, он округляется вниз с помощью функции Math.floor. Этот метод не округляет указанную date до интервала. Например, если date — сегодня в 17:34, то d3.timeDay.offset(date, 1) возвращает 17:34 завтра (даже если правила перехода на летнее время меняются!).

interval.range(start, stop[, step]) · Источник

Возвращает массив дат, представляющих каждую границу интервала после или равную start (включительно) и перед stop (исключительно). Если step указан, то будет возвращаться каждая step-я граница; например, для интервала d3.timeDay значение step, равное 2, вернёт каждый второй день. Если step не является целым числом, он округляется вниз с помощью функции Math.floor.

Первая дата в возвращаемом массиве — это самая ранняя граница после или равная start; последующие даты сдвигаются на step интервалов и округляются вниз с помощью floor. Таким образом, два перекрывающихся диапазона могут быть согласованными. Например, этот диапазон содержит нечётные дни:

d3.timeDay.range(new Date(2015, 0, 1), new Date(2015, 0, 7), 2) // [2015-01-01T00:00, 2015-01-03T00:00, 2015-01-05T00:00]

В то время как этот содержит чётные дни:

d3.timeDay.range(new Date(2015, 0, 2), new Date(2015, 0, 8), 2) // [2015-01-02T00:00, 2015-01-04T00:00, 2015-01-06T00:00]

Чтобы сделать диапазоны согласованными при заданном step, используйте interval.every вместо этого.

interval.filter(test) · Источник

Возвращает новый интервал, который является отфильтрованной подмножеством этого интервала, используя указанную функцию test. Функция test принимает дату и должна возвращать true тогда и только тогда, когда заданная дата должна считаться частью интервала. Например, чтобы создать интервал, который возвращает 1, 11, 21 и 31 (если существует) каждого месяца:

d3.timeDay.filter(d => (d.getDate() - 1) % 10 === 0)

Возвращаемый отфильтрованный интервал не поддерживает interval.count. См. также interval.every.

interval.every(step) · Источник

Возвращает отфильтрованный вид этого интервала, представляющий каждую step-ю дату. Значение step зависит от родительского интервала этого интервала, как определено функцией поля. Например, d3.timeMinute.every(15) возвращает интервал, представляющий каждую пятнадцать минут, начиная с часа: :00, :15, :30, :45 и т. д. Обратите внимание, что для некоторых интервалов результирующие даты могут не быть равномерно распределены; родительским интервалом d3.timeDay является d3.timeMonth, и поэтому номер интервала сбрасывается в начале каждого месяца. Если step недействителен, возвращает null. Если step равен единице, возвращает этот интервал.

Этот метод может использоваться совместно с interval.range для обеспечения согласованности двух перекрывающихся диапазонов. Например, этот диапазон содержит нечётные дни:

d3.timeDay.every(2).range(new Date(2015, 0, 1), new Date(2015, 0, 7)) // [2015-01-01T00:00, 2015-01-03T00:00, 2015-01-05T00:00]

Как и этот:

d3.timeDay.every(2).range(new Date(2015, 0, 2), new Date(2015, 0, 8)) // [2015-01-03T00:00, 2015-01-05T00:00, 2015-01-07T00:00]

Возвращаемый отфильтрованный интервал не поддерживает interval.count. См. также interval.filter.

interval.count(start, end) · Источник

Возвращает количество границ интервала после start (исключая) и до или равной end (включительно). Обратите внимание, что это поведение немного отличается от interval.range, потому что его цель — вернуть нулево-базированное число указанной даты end относительно указанной даты start. Например, для вычисления текущего нулево-базированного дня года:

d3.timeDay.count(d3.timeYear(now), now) // 177

Аналогично, для вычисления текущего нулево-базированного номера недели года для недель, начинающихся в воскресенье:

d3.timeSunday.count(d3.timeYear(now), now) // 25

d3.timeInterval(floor, offset[, count[, field]]) · Источник

Создаёт новый пользовательский интервал, заданный указанными функциями floor и offset и необязательной функцией count.

Функция floor принимает одну дату в качестве аргумента и округляет её вниз до ближайшей границы интервала.

Функция offset принимает дату и целое число шага в качестве аргументов и продвигает указанную дату на указанное количество границ; шаг может быть положительным, отрицательным или нулевым.

Необязательная функция count принимает начальную и конечную даты, уже округленные до текущего интервала, и возвращает количество границ между начальной (исключительно) и конечной (включительно) датами. Если функция count не указана, возвращаемый интервал не экспонирует методы interval.count или interval.every. Примечание: из-за внутренней оптимизации указанная функция count не должна вызывать interval.count для других временных интервалов.

Необязательная функция field принимает дату, уже округленную до текущего интервала, и возвращает значение поля указанной даты, соответствующее количеству границ между этой датой (исключительно) и последней предыдущей родительской границей. Например, для интервала d3.timeDay эта функция возвращает количество дней с начала месяца. Если функция field не указана, она по умолчанию подсчитывает количество границ интервала с момента эпохи Unix 1 января 1970 года по UTC. Функция field определяет поведение метода interval.every.

Интервалы

Предоставлены следующие интервалы:

d3.timeMillisecond · Исходный код
d3.utcMillisecond

Миллисекунды; наименьший доступный временной интервал.

d3.timeSecond · Исходный код
d3.utcSecond

Секунды (например, 01:23:45.0000 AM); 1000 миллисекунд.

d3.timeMinute · Исходный код
d3.utcMinute · Исходный код

Минуты (например, 01:02:00 AM); 60 секунд. Обратите внимание, что ECMAScript игнорирует високосные секунды.

d3.timeHour · Исходный код
d3.utcHour · Исходный код

Часы (например, 01:00 AM); 60 минут. Обратите внимание, что продвижение времени на один час в местном времени может вернуть тот же час или пропустить час из-за перехода на летнее время.

d3.timeDay · Исходный код
d3.utcDay · Исходный код

Дни (например, 7 февраля 2012 года в 00:00); обычно 24 часа. Дни в местном времени могут варьироваться от 23 до 25 часов из-за перехода на летнее время.

d3.timeWeek · Исходный код
d3.utcWeek · Исходный код

Псевдоним для d3.timeSunday; 7 дней и обычно 168 часов. Недели в местном времени могут варьироваться от 167 до 169 часов из-за перехода на летнее время.

d3.timeSunday · Исходный код
d3.utcSunday · Исходный код

Недели, основанные на воскресенье (например, 5 февраля 2012 года в 00:00).

d3.timeMonday · Исходный код
d3.utcMonday · Исходный код

Недели, основанные на понедельник (например, 6 февраля 2012 года в 00:00).

d3.timeTuesday · Исходный код
d3.utcTuesday · Исходный код

Недели, основанные на вторник (например, 7 февраля 2012 года в 00:00).

d3.timeWednesday · Исходный код
d3.utcWednesday · Исходный код

Недели, основанные на среду (например, 8 февраля 2012 года в 00:00).

d3.timeThursday · Исходный код
d3.utcThursday · Исходный код

Недели, основанные на четверг (например, 9 февраля 2012 года в 00:00).

d3.timeFriday · Исходный код
d3.utcFriday · Исходный код

Недели, основанные на пятницу (например, 10 февраля 2012 года в 00:00).

d3.timeSaturday · Источник
d3.utcSaturday · Источник

Недели, начинающиеся с субботы (например, 11 февраля 2012 года в 00:00).

d3.timeMonth · Источник
d3.utcMonth · Источник

Месяцы (например, 1 февраля 2012 года в 00:00); продолжительность от 28 до 31 дня.

d3.timeYear · Источник
d3.utcYear · Источник

Годы (например, 1 января 2012 года в 00:00); продолжительность от 365 до 366 дней.

Диапазоны

Для удобства также предоставляются псевдонимы для interval.range в виде множественного числа соответствующего интервала.

d3.timeMilliseconds(start, stop[, step]) · Источник
d3.utcMilliseconds(start, stop[, step])

Псевдонимы для d3.timeMillisecond.range и d3.utcMillisecond.range.

d3.timeSeconds(start, stop[, step]) · Источник
d3.utcSeconds(start, stop[, step])

Псевдонимы для d3.timeSecond.range и d3.utcSecond.range.

d3.timeMinutes(start, stop[, step]) · Источник
d3.utcMinutes(start, stop[, step]) · Источник

Псевдонимы для d3.timeMinute.range и d3.utcMinute.range.

d3.timeHours(start, stop[, step]) · Источник
d3.utcHours(start, stop[, step]) · Источник

Псевдонимы для d3.timeHour.range и d3.utcHour.range.

d3.timeDays(start, stop[, step]) · Источник
d3.utcDays(start, stop[, step]) · Источник

Псевдонимы для d3.timeDay.range и d3.utcDay.range.

d3.timeWeeks(start, stop[, step])
d3.utcWeeks(start, stop[, step])

Псевдонимы для d3.timeWeek.range и d3.utcWeek.range.

d3.timeSundays(start, stop[, step]) · Источник
d3.utcSundays(start, stop[, step]) · Источник

Псевдонимы для d3.timeSunday.range и d3.utcSunday.range.

d3.timeMondays(start, stop[, step]) · Источник
d3.utcMondays(start, stop[, step]) · Источник

Псевдонимы для d3.timeMonday.range и d3.utcMonday.range.

d3.timeTuesdays(start, stop[, step]) · Источник
d3.utcTuesdays(start, stop[, step]) · Источник

Псевдонимы для d3.timeTuesday.range и d3.utcTuesday.range.

d3.timeWednesdays(start, stop[, step]) · Источник
d3.utcWednesdays(start, stop[, step]) · Источник

Псевдонимы для d3.timeWednesday.range и d3.utcWednesday.range.

d3.timeThursdays(start, stop[, step]) · Source
d3.utcThursdays(start, stop[, step]) · Source

Псевдонимы для d3.timeThursday.range и d3.utcThursday.range.

d3.timeFridays(start, stop[, step]) · Source
d3.utcFridays(start, stop[, step]) · Source

Псевдонимы для d3.timeFriday.range и d3.utcFriday.range.

d3.timeSaturdays(start, stop[, step]) · Source
d3.utcSaturdays(start, stop[, step]) · Source

Псевдонимы для d3.timeSaturday.range и d3.utcSaturday.range.

d3.timeMonths(start, stop[, step]) · Source
d3.utcMonths(start, stop[, step]) · Source

Псевдонимы для d3.timeMonth.range и d3.utcMonth.range.

d3.timeYears(start, stop[, step]) · Source
d3.utcYears(start, stop[, step]) · Source

Псевдонимы для d3.timeYear.range и d3.utcYear.range.

Маркировки

d3.timeTicks(start, stop, count) · Source

Эквивалентно d3.utcTicks, но в локальном времени.

d3.timeTickInterval(start, stop, count) · Source

Возвращает временной интервал, который будет использоваться функцией d3.timeTicks с теми же аргументами.

d3.utcTicks(start, stop, count) · Source

Возвращает массив примерно count дат с равными интервалами между start и stop (включительно). Если stop предшествует start, даты возвращаются в обратном хронологическом порядке; в противном случае даты возвращаются в хронологическом порядке. Рассматриваются следующие интервалы UTC-времени:

• 1 секунда
• 5 секунд
• 15 секунд
• 30 секунд
• 1 минута
• 5 минут
• 15 минут
• 30 минут
• 1 час
• 3 часа
• 6 часов
• 12 часов
• 1 день
• 2 дня
• 1 неделя
• 1 месяц
• 3 месяца
• 1 год

Также рассматриваются кратные значения миллисекунд (для небольших диапазонов) и годов (для больших диапазонов), следуя правилам d3.ticks. Используется интервал, который обеспечивает количество дат, наиболее близкое к count. Например:

start = new Date(Date.UTC(1970, 2, 1))
stop = new Date(Date.UTC(1996, 2, 19))
count = 4
d3.utcTicks(start, stop, count) // [1975-01-01, 1980-01-01, 1985-01-01, 1990-01-01, 1995-01-01]

Если count является временным интервалом, эта функция ведет себя аналогично interval.range, за исключением того, что как start, так и stop включительно, и она может возвращать даты в обратном хронологическом порядке, если stop предшествует start.

d3.utcTickInterval(start, stop, count) · Source

Возвращает временной интервал, который будет использоваться функцией d3.utcTicks с теми же аргументами. Если нет связанного интервала, например, когда start или stop недействительны, возвращает null.