d3-time

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

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

var start = new Date(2015, 02, 01), // Sun Mar 01 2015 00:00:00 GMT-0800 (PST)
    end = new Date(2015, 03, 01); // Wed Apr 01 2015 00:00:00 GMT-0700 (PDT)
(end - start) / 864e5; // 30.958333333333332, oops!

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

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

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

var now = new Date;
d3.timeWeek.range(d3.timeMonth.floor(now), d3.timeMonth.ceil(now));
// [Sun Jun 07 2015 00:00:00 GMT-0700 (PDT),
//  Sun Jun 14 2015 00:00:00 GMT-0700 (PDT),
//  Sun Jun 21 2015 00:00:00 GMT-0700 (PDT),
//  Sun Jun 28 2015 00:00:00 GMT-0700 (PDT)]

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

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

Установка

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

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

var day = d3.timeDay(new Date);

</script>

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

Справочник по API

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

Псевдоним для interval.floor. Например, d3.timeYear(date) и d3.timeYear.floor(date) эквивалентны.

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 не целое число, он округляется до ближайшего целого. Этот метод не округляет указанную 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 не целое число, оно округляется до ближайшего целого.

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

d3.timeDay.range(new Date(2015, 0, 1), new Date(2015, 0, 7), 2);
// [Thu Jan 01 2015 00:00:00 GMT-0800 (PST),
//  Sat Jan 03 2015 00:00:00 GMT-0800 (PST),
//  Mon Jan 05 2015 00:00:00 GMT-0800 (PST)]

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

d3.timeDay.range(new Date(2015, 0, 2), new Date(2015, 0, 8), 2);
// [Fri Jan 02 2015 00:00:00 GMT-0800 (PST),
//  Sun Jan 04 2015 00:00:00 GMT-0800 (PST),
//  Tue Jan 06 2015 00:00:00 GMT-0800 (PST)]

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

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

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

var i = d3.timeDay.filter(function(d) { return (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));
// [Thu Jan 01 2015 00:00:00 GMT-0800 (PST),
//  Sat Jan 03 2015 00:00:00 GMT-0800 (PST),
//  Mon Jan 05 2015 00:00:00 GMT-0800 (PST)]

Так же, как и этот:

d3.timeDay.every(2).range(new Date(2015, 0, 2), new Date(2015, 0, 8));
// [Sat Jan 03 2015 00:00:00 GMT-0800 (PST),
//  Mon Jan 05 2015 00:00:00 GMT-0800 (PST),
//  Wed Jan 07 2015 00:00:00 GMT-0800 (PST)]

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

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

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

var now = new Date;
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 Source
d3.utcMillisecond

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

d3.timeSecond Source
d3.utcSecond

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

d3.timeMinute Source
d3.utcMinute Source

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

d3.timeHour Source
d3.utcHour Source

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

d3.timeDay Source
d3.utcDay Source

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

d3.timeWeek Source
d3.utcWeek Source

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

d3.timeSunday Source
d3.utcSunday Source

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

d3.timeMonday Source
d3.utcMonday Source

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

d3.timeTuesday Source
d3.utcTuesday Source

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

d3.timeWednesday Source
d3.utcWednesday Source

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

d3.timeThursday Source
d3.utcThursday Source

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

d3.timeFriday Source
d3.utcFriday Source

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

d3.timeSaturday Source
d3.utcSaturday Source

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

d3.timeMonth Source
d3.utcMonth Source

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

d3.timeYear Source
d3.utcYear Source

Годы (например, 1 января 2012 года в 12:00 AM); диапазон от 365 до 366 дней.

Диапазоны

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

d3.timeMilliseconds(start, stop[, step]) Source
d3.utcMilliseconds(start, stop[, step])

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

d3.timeSeconds(start, stop[, step]) Source
d3.utcSeconds(start, stop[, step])

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

d3.timeMinutes(start, stop[, step]) Source
d3.utcMinutes(start, stop[, step]) Source

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

d3.timeHours(start, stop[, step]) Source
d3.utcHours(start, stop[, step]) Source

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

d3.timeDays(start, stop[, step]) Source
d3.utcDays(start, stop[, step]) Source

Псевдонимы для 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]) Source
d3.utcSundays(start, stop[, step]) Source

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

d3.timeMondays(start, stop[, step]) Source
d3.utcMondays(start, stop[, step]) Source

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

d3.timeTuesdays(start, stop[, step]) Source
d3.utcTuesdays(start, stop[, step]) Source

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

d3.timeWednesdays(start, stop[, step]) Source
d3.utcWednesdays(start, stop[, step]) Source

Псевдонимы для 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.