Даты

Типы Date и DateTime могут быть построены с помощью целочисленных типов или типов Period, путем синтаксического анализа или с помощью регулировщиков (подробнее об этом позже):

Анализ Date или DateTime осуществляется с помощью строк формата. Строки формата определяют разграниченные слоты или слоты фиксированной ширины, содержащие период для анализа, и передают конструктору Date или DateTime текст для анализа и строку формата в виде Date("2015-01-01",dateformat"y-m-d") или DateTime("20150101",dateformat"yyyymmdd").

Разграниченные слоты помечаются с указанием разделителя, который анализатор должен ожидать между двумя последующими периодами. Так, "y-m-d" указывает анализатору, что между первым и вторым слотами в строке даты, например "2014-07-16", он должен найти символ -. Символы y, m и d позволяют синтаксическому анализатору определять, какие периоды следует анализировать в каждом слоте.

Как и в случае с такими конструкторами, как Date(2013), разграниченные DateFormat допускают отсутствие частей даты и времени, если указаны предшествующие части. Остальные части имеют обычные значения по умолчанию. Например, Date("1981-03", dateformat"y-m-d") возвращает 1981-03-01, а Date("31/12", dateformat"d/m/y") выдает 0001-12-31. (Обратите внимание, что годом по умолчанию является 1 AD/CE.) Однако для пустой строки всегда выдается ошибка ArgumentError.

Слоты фиксированной ширины задаются повторением символа периода соответствующее ширине количество раз без разделителя между символами. Таким образом, dateformat"yyyymmdd" будет соответствовать строке даты, например "20140716". Анализатор различает слот фиксированной ширины по отсутствию разделителя, отмечая переход "yyyymm" от одного символа периода к другому.

Поддержка анализа месяца в текстовой форме также осуществляется с помощью символов u и U, предназначенных для сокращенного и полного названия месяца, соответственно. По умолчанию поддерживаются только названия месяцев на английском языке, поэтому u соответствует Jan, Feb, Mar и т. д. А U соответствует January, February, March и т. д. Аналогично другим функциям сопоставления «имя=>значение»dayname и monthname, пользовательские локали могут быть загружены путем передачи сопоставления locale=>Dict{String,Int} в словари MONTHTOVALUEABBR и MONTHTOVALUE для сокращенных и полных названий месяцев, соответственно.

В приведенном выше примере используется строковый макрос dateformat"". Этот макрос создает объект DateFormat один раз при расширении макроса и использует один и тот же объект DateFormat даже при многократном выполнении фрагмента кода.

Или вы можете создать объект DateFormat явным образом:

Либо используйте трансляцию:

Для удобства можно передавать строку формата напрямую (например, Date("2015-01-01","y-m-d")), хотя при многократном анализе одного и того же формата такая форма приводит к росту затрат на производительность, так как каждый раз создается новый объект DateFormat.

Date или DateTime могут быть созданы не только с помощью конструкторов, но и с помощью функций parse и tryparse, но с необязательным третьим аргументом типа DateFormat, задающим формат. Например, parse(Date, "06.23.2013", dateformat"m.d.y"), или tryparse(DateTime, "1999-12-31T23:59:59"), который использует формат по умолчанию. Разница между функциями заключается в том, что при использовании tryparse не выдается ошибка, если строка пустая или имеет недопустимый формат, а возвращается nothing.

Полный набор тестов и примеров анализа и форматирования приведен в stdlib/Dates/test/io.jl.

Найти длительность промежутка времени между двумя Date или DateTime несложно, учитывая их базовое представление в виде UTInstant{Day} и UTInstant{Millisecond}, соответственно. Разница между Date возвращается в числе Day, а DateTime — в числе Millisecond. Аналогично, сравнение TimeType сводится к сравнению базовых машинных моментов времени (которые, в свою очередь, сравнивают внутренние значения Int64).

Поскольку типы Date и DateTime хранятся как отдельные значения Int64, части даты или поля могут быть получены с помощью функций методов доступа. Методы доступа в нижнем регистре возвращают поле как целочисленное значение:

Тогда как методы в регистре ProperCase возвращают то же самое значение в соответствующем типе Period:

Доступны составные методы, так как доступ к нескольким полям одновременно более эффективен, чем по отдельности:

Также можно получить доступ к базовому значению UTInstant или целому числу:

Функции запросов предоставляют календарную информацию о типе времени (TimeType). Они содержат информацию о дне недели:

о месяце года:

а также сведения о годе и квартале TimeType:

Методы dayname и monthname могут также принимать необязательное ключевое слово locale, которое можно использовать для возврата названия дня или месяца года для других языков и локалей. Существуют также версии этих функций, возвращающие сокращенные названия, а именно dayabbr и monthabbr. Сначала в переменную LOCALES загружается сопоставление:

Затем перечисленные выше функции могут быть использованы для выполнения запросов:

Поскольку сокращенные версии дней не загружены, попытка использовать функцию dayabbr приведет к ошибке.

При использовании любой платформы для работы с языком и датами полезно знать, как действует арифметика «дата-период», так как при этом возникают некоторые сложные вопросы (хотя для типов с точностью до дня их гораздо меньше).

Подход на основе модуля Dates пытается следовать простому принципу: стараться вносить как можно меньше изменений при выполнении арифметических действий Period. Этот подход также часто называют календарной арифметикой или тем, о чем вы, вероятно, догадались бы, если бы кто-то попросил вас в разговоре выполнить подобное вычисление. Почему возникает так много шума по этому поводу? Рассмотрим классический пример: добавим 1 месяц к 31 января 2014 года. Каков же ответ? Согласно Javascript — 3 марта (предполагается 31 день в месяце). Согласно PHP — 2 марта (предполагается 30 дней в месяце). Но дело в том, что правильного ответа не существует. В модуле Dates выдается такой результат — 28 февраля. Каким образом это определяется? Рассмотрим классическую азартную игру 7-7-7 в казино.

Теперь представьте, что вместо 7-7-7 слоты имеют вид «год-месяц-день», или, как в нашем примере, 2014-01-31. Когда вы просите добавить 1 месяц к этой дате, слот месяца увеличивается, так что теперь мы имеем 2014-02-31. Затем проверяется, не превышает ли номер дня последний допустимый день нового месяца. Если значение дня больше (как в приведенном выше случае), номер дня корректируется в сторону уменьшения до последнего допустимого дня (28). Какие последствия может иметь такой подход? Добавим к нашей дате еще один месяц — 2014-02-28 + Month(1) == 2014-03-28. Что? Вы ожидали последний день марта? Нет, извините. Помните про слоты 7-7-7. Будет изменяться минимальное число слотов, поэтому сначала мы увеличим слот месяца на 1 (2014-03-28), и вот, все готово, потому что это допустимая дата. С другой стороны, если мы добавим 2 месяца к исходной дате 2014-01-31, то получим 2014-03-31, как и ожидалось. Другим следствием такого подхода является потеря ассоциативности при применении определенного упорядочения (т. е. добавление элементов в разном порядке приводит к разным результатам). Пример:

Что там происходит? В первой строке мы добавляем 1 день к 29 января, в результате чего получаем 2014-01-30. Затем добавляем 1 месяц, в результате чего получаем дату 2014-02-30, которая затем корректируется до 2014-02-28. Во втором примере мы сначала добавляем 1 месяц и получаем дату 2014-02-29, которая корректируется до 2014-02-28, а затем добавляем 1 день, в результате чего получаем 2014-03-01. Один из принципов проектирования, который помогает в этом случае, заключается в том, что при наличии нескольких периодов операции будут упорядочены по типам периодов, а не по их значению или порядку расположения. Это означает, что сначала всегда будет добавляться Year, затем Month, затем Week и т. д. Следовательно, следующее приводит к ассоциативности и просто работает:

Сложно? Может быть. Что же делать простому пользователю Dates? Следует иметь в виду, что явное принудительное использование определенной ассоциативности при работе с месяцами может привести к неожиданным результатам, но в остальном все должно работать так, как ожидается. К счастью, на этом странности в арифметике «дата-период» при работе со временем в формате UT практически заканчиваются (за исключением «удовольствий», связанных с переходом на летнее время, дополнительными високосными секундами и т. д.).

А вот и бонус: все арифметические объекты периода напрямую работают с диапазонами:

Как бы ни была удобна арифметика «дата-период», часто вычисления, связанные с датами, имеют не фиксированное число периодов, а носят календарный или временной характер. Прекрасным примером являются праздники. Большинство из них подчиняются таким правилам, как «День памяти — последний понедельник мая» или «День благодарения — четвертый четверг ноября». Эти виды временных выражений работают с правилами, относящимися к календарю, например первое или последнее число месяца, следующий вторник или первая и третья среда и т. д.

Модуль Dates предоставляет API регулировщика с помощью нескольких удобных методов, которые помогают просто и лаконично выражать временные правила. Первая группа методов регулировщика работает с первыми и последними неделями, месяцами, кварталами и годами. Каждый из них принимает в качестве входного один TimeType и возвращает или настраивает первое или последнее значение нужного периода относительно входного значения.

Следующие два метода более высокого порядка, tonext и toprev, обобщают работу с временными выражениями, принимая в качестве первого аргумента DateFunction, а также начальный TimeType. DateFunction — это просто функция, обычно анонимная, которая принимает в качестве входного один TimeType и возвращает Bool, true, указывающий на выполненное условие настройки. Пример:

Это удобно при использовании синтаксиса do-block для более сложных временных выражений:

Метод Base.filter можно использовать для получения всех действительных дат / событий в указанном диапазоне:

Дополнительные примеры и тесты доступны в stdlib/Dates/test/adjusters.jl.

Периоды — это человеческая точка зрения на отдельные, иногда нерегулярные отрезки времени. Рассмотрим 1 месяц. Он может представлять в днях значение 28, 29, 30 или 31 в зависимости от года и месяца. Или же год может представлять собой 365 или 366 дней (в случае високосного года). Типы Period являются простыми оболочками Int64 и строятся путем заключения в оболочку любого преобразуемого типа Int64, т. е. Year(1) или Month(3.0). Арифметические операции между Period одного типа работают как операции с целыми числами. Доступна ограниченная арифметика Period-Real. С помощью Dates.value можно извлечь базовое целое число.

Представление периодов или длительностей, не являющихся целыми кратными базовых типов, можно осуществить с помощью типа Dates.CompoundPeriod. Составные периоды могут быть построены вручную из простых типов Period. Кроме того, с помощью функции canonicalize можно разбить период на Dates.CompoundPeriod. Это особенно удобно для преобразования длительности, например разности двух DateTime, в более оптимальное представление.

Значения Date и DateTime можно округлить до заданного разрешения (например, 1 месяц или 15 минут) с помощью функций floor, ceil или round:

В отличие от числового метода round, который по умолчанию разрешает неоднозначность в сторону четного числа, метод TimeTyperound использует режим округления RoundNearestTiesUp. (Трудно предположить, что повлечет за собой разрешение неоднозначности в сторону ближайшего «четного» TimeType.) Более подробную информацию о доступных RoundingMode можно найти в справочнике по API.

В целом округление должно вести себя так, как ожидается, но в некоторых случаях ожидаемое поведение неочевидно.