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 вычисляет полночь (обычно 12: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) обычно возвращает 12: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;
}

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

interval.round(date) Исходный код

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

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

interval.ceil(date) Исходный код

Возвращает новую дату, представляющую самую раннюю границу интервала после или равную date. Например, d3.timeDay.ceil(date) обычно возвращает 12: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 интервалов и усекаются до 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 Источник
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 года в 12:00 AM); обычно 24 часа. Дни в местном времени могут составлять от 23 до 25 часов из-за перехода на летнее время.

d3.timeWeek Источник
d3.utcWeek Источник

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

d3.timeSunday Источник
d3.utcSunday Источник

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

d3.timeMonday Источник
d3.utcMonday Источник

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

d3.timeTuesday Источник
d3.utcTuesday Источник

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

d3.timeWednesday Источник
d3.utcWednesday Источник

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

d3.timeThursday Источник
d3.utcThursday Источник

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

d3.timeFriday Источник
d3.utcFriday Источник

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

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

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

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

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

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

Годы (например, 1 января 2012 года в 12:00 AM); от 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]) 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.