Даты

Модуль Dates предоставляет два типа для работы с датами: Date и DateTime, представляющие точность до дня и миллисекунды соответственно. Оба являются подтипами абстрактного типа TimeType. Мотивация для создания отдельных типов проста: некоторые операции гораздо проще, как с точки зрения кода, так и с точки зрения мысленных рассуждений, когда не приходится иметь дело со сложностями, связанными с большей точностью. Например, поскольку тип Date обеспечивает точность только до даты (т. е. без часов, минут и секунд), обычные соображения о часовых поясах, летнем/зимнем времени и дополнительных секундах не нужны и исключаются.

И Date, и DateTime по сути являются неизменяемыми оболочками Int64. Единственное поле instant любого из этих типов на самом деле является типом UTInstant{P}, который представляет собой непрерывно возрастающую машинную шкалу времени на основе секунды всемирного времени (UT) ^[1]. Типу DateTime неизвестно о часовых поясах (примитивный в языке Python), как и типу LocalDateTime в Java 8. Дополнительный функционал для работы с часовыми поясами можно добавить с помощью пакета TimeZones.jl, который компилирует базу данных часовых поясов IANA. Date и DateTime основаны на стандарте ISO 8601, который соответствует пролептическому григорианскому календарю. Следует отметить, что в стандарте ISO 8601 особое внимание уделяется датам BC/BCE («до Христа» / «до нашей эры»). В целом за последним днем эры BC/BCE (31.12.1 BC/BCE) следовал день 1.1.1 AD/CE, поэтому нулевого года не существует. Однако согласно стандарту ISO 1 BC/BCE является нулевым годом, поэтому 0000-12-31 — это день, предшествующий 0001-01-01, а год -0001 (да, отрицательная единица для года) — это 2 BC/BCE, год -0002 — это 3 BC/BCE и т. д.

Конструкторы

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

julia> DateTime(2013)
2013-01-01T00:00:00

julia> DateTime(2013,7)
2013-07-01T00:00:00

julia> DateTime(2013,7,1)
2013-07-01T00:00:00

julia> DateTime(2013,7,1,12)
2013-07-01T12:00:00

julia> DateTime(2013,7,1,12,30)
2013-07-01T12:30:00

julia> DateTime(2013,7,1,12,30,59)
2013-07-01T12:30:59

julia> DateTime(2013,7,1,12,30,59,1)
2013-07-01T12:30:59.001

julia> Date(2013)
2013-01-01

julia> Date(2013,7)
2013-07-01

julia> Date(2013,7,1)
2013-07-01

julia> Date(Dates.Year(2013),Dates.Month(7),Dates.Day(1))
2013-07-01

julia> Date(Dates.Month(7),Dates.Year(2013))
2013-07-01

Анализ 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 даже при многократном выполнении фрагмента кода.

julia> for i = 1:10^5
           Date("2015-01-01", dateformat"y-m-d")
       end

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

julia> df = DateFormat("y-m-d");

julia> dt = Date("2015-01-01",df)
2015-01-01

julia> dt2 = Date("2015-01-02",df)
2015-01-02

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

julia> years = ["2015", "2016"];

julia> Date.(years, DateFormat("yyyy"))
2-element Vector{Date}:
 2015-01-01
 2016-01-01

Для удобства можно передавать строку формата напрямую (например, 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.

Совместимость: Julia 1.9

До версии Julia 1.9 пустые строки можно было передавать в конструкторы и анализировать (parse) без ошибок. При этом возвращалось соответствующее значение DateTime(1), Date(1) или Time(0). Аналогичным образом, функция tryparse не возвращала nothing.

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

Длительность/сравнение

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

julia> dt = Date(2012,2,29)
2012-02-29

julia> dt2 = Date(2000,2,1)
2000-02-01

julia> dump(dt)
Date
  instant: Dates.UTInstant{Day}
    periods: Day
      value: Int64 734562

julia> dump(dt2)
Date
  instant: Dates.UTInstant{Day}
    periods: Day
      value: Int64 730151

julia> dt > dt2
true

julia> dt != dt2
true

julia> dt + dt2
ERROR: MethodError: no method matching +(::Date, ::Date)
[...]

julia> dt * dt2
ERROR: MethodError: no method matching *(::Date, ::Date)
[...]

julia> dt / dt2
ERROR: MethodError: no method matching /(::Date, ::Date)

julia> dt - dt2
4411 days

julia> dt2 - dt
-4411 days

julia> dt = DateTime(2012,2,29)
2012-02-29T00:00:00

julia> dt2 = DateTime(2000,2,1)
2000-02-01T00:00:00

julia> dt - dt2
381110400000 milliseconds

Функции методов доступа

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

julia> t = Date(2014, 1, 31)
2014-01-31

julia> Dates.year(t)
2014

julia> Dates.month(t)
1

julia> Dates.week(t)
5

julia> Dates.day(t)
31

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

julia> Dates.Year(t)
2014 years

julia> Dates.Day(t)
31 days

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

julia> Dates.yearmonth(t)
(2014, 1)

julia> Dates.monthday(t)
(1, 31)

julia> Dates.yearmonthday(t)
(2014, 1, 31)

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

julia> dump(t)
Date
  instant: Dates.UTInstant{Day}
    periods: Day
      value: Int64 735264

julia> t.instant
Dates.UTInstant{Day}(Day(735264))

julia> Dates.value(t)
735264

Функции запросов

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

julia> t = Date(2014, 1, 31)
2014-01-31

julia> Dates.dayofweek(t)
5

julia> Dates.dayname(t)
"Friday"

julia> Dates.dayofweekofmonth(t) # 5-я пятница января
5

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

julia> Dates.monthname(t)
"January"

julia> Dates.daysinmonth(t)
31

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

julia> Dates.isleapyear(t)
false

julia> Dates.dayofyear(t)
31

julia> Dates.quarterofyear(t)
1

julia> Dates.dayofquarter(t)
31

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

julia> french_months = ["janvier", "février", "mars", "avril", "mai", "juin",
                        "juillet", "août", "septembre", "octobre", "novembre", "décembre"];

julia> french_monts_abbrev = ["janv","févr","mars","avril","mai","juin",
                              "juil","août","sept","oct","nov","déc"];

julia> french_days = ["lundi","mardi","mercredi","jeudi","vendredi","samedi","dimanche"];

julia> Dates.LOCALES["french"] = Dates.DateLocale(french_months, french_monts_abbrev, french_days, [""]);

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

julia> Dates.dayname(t;locale="french")
"vendredi"

julia> Dates.monthname(t;locale="french")
"janvier"

julia> Dates.monthabbr(t;locale="french")
"janv"

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

julia> Dates.dayabbr(t;locale="french")
ERROR: BoundsError: attempt to access 1-element Vector{String} at index [5]
Stacktrace:
[...]

Арифметика TimeType-Period

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

Подход на основе модуля 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, как и ожидалось. Другим следствием такого подхода является потеря ассоциативности при применении определенного упорядочения (т. е. добавление элементов в разном порядке приводит к разным результатам). Пример:

julia> (Date(2014,1,29)+Dates.Day(1)) + Dates.Month(1)
2014-02-28

julia> (Date(2014,1,29)+Dates.Month(1)) + Dates.Day(1)
2014-03-01

Что там происходит? В первой строке мы добавляем 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 и т. д. Следовательно, следующее приводит к ассоциативности и просто работает:

julia> Date(2014,1,29) + Dates.Day(1) + Dates.Month(1)
2014-03-01

julia> Date(2014,1,29) + Dates.Month(1) + Dates.Day(1)
2014-03-01

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

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

julia> dr = Date(2014,1,29):Day(1):Date(2014,2,3)
Date("2014-01-29"):Day(1):Date("2014-02-03")

julia> collect(dr)
6-element Vector{Date}:
 2014-01-29
 2014-01-30
 2014-01-31
 2014-02-01
 2014-02-02
 2014-02-03

julia> dr = Date(2014,1,29):Dates.Month(1):Date(2014,07,29)
Date("2014-01-29"):Month(1):Date("2014-07-29")

julia> collect(dr)
7-element Vector{Date}:
 2014-01-29
 2014-02-28
 2014-03-29
 2014-04-29
 2014-05-29
 2014-06-29
 2014-07-29

Функции регулировщика

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

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

julia> Dates.firstdayofweek(Date(2014,7,16)) # Настраивает входное значение на понедельник входной недели
2014-07-14

julia> Dates.lastdayofmonth(Date(2014,7,16)) # Настраивает на последний день входного месяца
2014-07-31

julia> Dates.lastdayofquarter(Date(2014,7,16)) # Настраивает на последний день входного квартала
2014-09-30

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

julia> istuesday = x->Dates.dayofweek(x) == Dates.Tuesday; # Возвращает true, если днем недели для x является вторник

julia> Dates.tonext(istuesday, Date(2014,7,13)) # 2014-07-13 — воскресенье
2014-07-15

julia> Dates.tonext(Date(2014,7,13), Dates.Tuesday) # Для корректировки дня недели предусмотрен эффективный метод
2014-07-15

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

julia> Dates.tonext(Date(2014,7,13)) do x
           # Возвращает true в 4-й четверг ноября (День благодарения)
           Dates.dayofweek(x) == Dates.Thursday &&
           Dates.dayofweekofmonth(x) == 4 &&
           Dates.month(x) == Dates.November
       end
2014-11-27

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

# Уборка улиц Питтсбурга; каждый 2-й вторник с апреля по ноябрь
# Диапазон дат с 1 января 2014 г. по 1 января 2015 г.
julia> dr = Dates.Date(2014):Day(1):Dates.Date(2015);

julia> filter(dr) do x
           Dates.dayofweek(x) == Dates.Tue &&
           Dates.April <= Dates.month(x) <= Dates.Nov &&
           Dates.dayofweekofmonth(x) == 2
       end
8-element Vector{Date}:
 2014-04-08
 2014-05-13
 2014-06-10
 2014-07-08
 2014-08-12
 2014-09-09
 2014-10-14
 2014-11-11

Дополнительные примеры и тесты доступны в 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 можно извлечь базовое целое число.

julia> y1 = Dates.Year(1)
1 year

julia> y2 = Dates.Year(2)
2 years

julia> y3 = Dates.Year(10)
10 years

julia> y1 + y2
3 years

julia> div(y3,y2)
5

julia> y3 - y2
8 years

julia> y3 % y2
0 years

julia> div(y3,3) # зеркалирует деление целых чисел
3 years

julia> Dates.value(Dates.Millisecond(10))
10

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

julia> cp = Dates.CompoundPeriod(Day(1),Minute(1))
1 day, 1 minute

julia> t1 = DateTime(2018,8,8,16,58,00)
2018-08-08T16:58:00

julia> t2 = DateTime(2021,6,23,10,00,00)
2021-06-23T10:00:00

julia> canonicalize(t2-t1) # создает CompoundPeriod
149 weeks, 6 days, 17 hours, 2 minutes

Округление

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

julia> floor(Date(1985, 8, 16), Dates.Month)
1985-08-01

julia> ceil(DateTime(2013, 2, 13, 0, 31, 20), Dates.Minute(15))
2013-02-13T00:45:00

julia> round(DateTime(2016, 8, 6, 20, 15), Dates.Day)
2016-08-07T00:00:00

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

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

Период округления

Во многих случаях заданное для округления разрешение (например, Dates.Second(30)) равномерно делится на следующий по величине период (в данном случае Dates.Minute(1)). Однако в противных случаях поведение округления может привести к путанице. Каков ожидаемый результат округления числа DateTime до ближайших 10 часов?

julia> round(DateTime(2016, 7, 17, 11, 55), Dates.Hour(10))
2016-07-17T12:00:00

Он может показаться непонятным, если учесть, что час (12) не делится на 10. Причина выбора 2016-07-17T12:00:00 заключается в том, что оно идет через 17 676 660 часов после 0000-01-01T00:00:00, а 17 676 660 кратно 10.

Поскольку значения Julia Date и DateTime представлены в соответствии со стандартом ISO 8601, в качестве базы (или «периода округления»), с которой начинается отсчет дней (и миллисекунд), используемых в расчетах округления, было выбрано 0000-01-01T00:00:00. (Заметим, что это несколько отличается от внутреннего представления Date в Julia, использующего нотацию Rata Die; но поскольку стандарт ISO 8601 наиболее заметен для конечного пользователя, 0000-01-01T00:00:00 было выбрано в качестве периода округления вместо 0000-12-31T00:00:00, используемого внутренним образом, чтобы минимизировать путаницу.)

Единственным исключением из использования 0000-01-01T00:00:00 в качестве периода округления является округление до недель. Округление до ближайшей недели всегда возвращает понедельник (первый день недели согласно стандарту ISO 8601). Поэтому при округлении до числа недель в качестве базы используется 0000-01-03T00:00:00 (первый день первой недели года 0000, как определено в стандарте ISO 8601).

Вот связанный с этим случай, в котором ожидаемое поведение не всегда очевидно. Что произойдет, если мы округлим до ближайшего P(2), где P является типом Period? В некоторых случаях (в частности, когда P <: Dates.TimePeriod) ответ очевиден:

julia> round(DateTime(2016, 7, 17, 8, 55, 30), Dates.Hour(2))
2016-07-17T08:00:00

julia> round(DateTime(2016, 7, 17, 8, 55, 30), Dates.Minute(2))
2016-07-17T08:56:00

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

julia> round(DateTime(2016, 7, 17, 8, 55, 30), Dates.Month(2))
2016-07-01T00:00:00

Зачем округлять до первого числа июля, даже если это 7-й месяц (нечетное число)? Ключевым моментом является то, что месяцы индексируются с 1 (первому месяцу присваивается 1), в отличие от часов, минут, секунд и миллисекунд (первым из которых присваивается 0).

Это означает, что округление значения DateTime до четного количества секунд, минут, часов или лет (поскольку спецификация ISO 8601 включает нулевой год) приведет к тому, что поле DateTime будет иметь четное значение, а округление значения DateTime до четного количества месяцев приведет к тому, что поле месяцев будет иметь нечетное значение. Поскольку и месяцы, и годы могут содержать неравномерное количество дней, неясно, будет ли результатом округления до четного числа дней четное значение в поле дней.

Дополнительные сведения о методах, экспортируемых из модуля Dates, см. в справке по API.

Справка по API

Типы дат и времени

# Dates.Period — Type

Period
Year
Quarter
Month
Week
Day
Hour
Minute
Second
Millisecond
Microsecond
Nanosecond

Типы Period представляют дискретное «человеческое» представление времени.

# Dates.CompoundPeriod — Type

CompoundPeriod

CompoundPeriod полезен для выражения временных периодов, которые не являются фиксированной суммой более коротких периодов. Например, «год и день» не является фиксированным числом дней, но может быть выражен с помощью CompoundPeriod. На самом деле CompoundPeriod автоматически создается путем добавления различных типов периодов, например Year(1) + Day(1) производит результат CompoundPeriod.

# Dates.Instant — Type

Instant

Типы Instant представляют целочисленное машинное представление времени в виде продолжительных шкал времени, начинающихся с эпохи.

# Dates.UTInstant — Type

UTInstant{T}

UTInstant представляет машинную шкалу времени на основе всемирного времени (1 день = один оборот Земли). T — это параметр Period, указывающий разрешение или точность момента времени.

# Dates.TimeType — Type

TimeType

Типы TimeType оборачивают машинные экземпляры Instant, чтобы предоставить «человеческое» представление машинного момента времени. Time, DateTime и Date являются подтипами TimeType.

# Dates.DateTime — Type

DateTime

DateTime оборачивает UTInstant{Millisecond} и интерпретирует его в соответствии с пролептическим григорианским календарем.

# Dates.Date — Type

Date

Date оборачивает UTInstant{Day} и интерпретирует его в соответствии с пролептическим григорианским календарем.

# Dates.Time — Type

Time

Time оборачивает Nanosecond и представляет конкретный момент в сутках (24 часа).

# Dates.TimeZone — Type

TimeZone

Географическая зона обычно основывается на долготе, определяющей время в конкретном расположении. В некоторых часовых поясах осуществляется переход на летнее время (например, EST -> EDT). Реализации и дополнительную поддержку см. в пакете TimeZones.jl

# Dates.UTC — Type

UTC

UTC, или Всемирное координированное время, — это часовой пояс (TimeZone), от которого отсчитываются все остальные. Он связан со временем на долготе 0°. В нем не осуществляется переход на летнее время.

Функции работы с датами

# Dates.DateTime — Method

DateTime(y, [m, d, h, mi, s, ms]) -> DateTime

Конструирует тип DateTime по частям. Аргументы должны иметь возможность преобразования в Int64.

# Dates.DateTime — Method

DateTime(periods::Period...) -> DateTime

Конструирует тип DateTime по частям типа Period. Аргументы могут указываться в любом порядке. Неуказанные части DateTime по умолчанию будут иметь значение Dates.default(period).

# Dates.DateTime — Method

DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), limit=10000) -> DateTime

Создает дату и время (DateTime) с помощью API регулировщика. Начальная точка будет конструироваться из указанных аргументов y, m, d... и будет регулироваться, пока функция f::Function не возвратит true. Величину шага регулировки можно указывать вручную с помощью ключевого слова step. limit указывает ограничение максимального числа итераций, которые будет осуществлять API регулировки, прежде чем выдавать ошибку (в том случае, если f::Function никогда не будет удовлетворять условиям).

Примеры

julia> DateTime(dt -> second(dt) == 40, 2010, 10, 20, 10; step = Second(1))
2010-10-20T10:00:40

julia> DateTime(dt -> hour(dt) == 20, 2010, 10, 20, 10; step = Hour(1), limit = 5)
ERROR: ArgumentError: Adjustment limit reached: 5 iterations
Stacktrace:
[...]

# Dates.DateTime — Method

DateTime(dt::Date) -> DateTime

Преобразует Date в DateTime. Компоненты часов, минут, секунд и миллисекунд новых даты и времени (DateTime) имеют значение ноль.

# Dates.DateTime — Method

DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime

Конструирует DateTime путем анализа строки даты и времени dt, следуя шаблону, заданному в строке format (синтаксис см. в DateFormat).

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

Пример

julia> DateTime("2020-01-01", "yyyy-mm-dd")
2020-01-01T00:00:00

julia> a = ("2020-01-01", "2020-01-02");

julia> [DateTime(d, dateformat"yyyy-mm-dd") for d ∈ a] # предпочтительно
2-element Vector{DateTime}:
 2020-01-01T00:00:00
 2020-01-02T00:00:00

# Dates.format — Method

format(dt::TimeType, format::AbstractString; locale="english") -> AbstractString

Конструирует строку, используя объект TimeType и применяя указанный format. Для конструирования строки format можно использовать следующие коды символов:

Код Примеры Комментарий

Код	Примеры	Комментарий
`y`	6	Выраженный числом год с фиксированной шириной
`Y`	1996	Выраженный числом год с минимальной шириной
`m`	1, 12	Выраженный числом месяц с фиксированной шириной
`u`	Jan	Название месяца, сокращенное до 3 символов в соответствии с локалью (`locale`)
`U`	January	Полное название месяца в соответствии с ключевым словом `locale`
`d`	1, 31	День месяца с минимальной шириной
`H`	0, 23	Час (в формате 24 часов) с минимальной шириной
`M`	0, 59	Минута с минимальной шириной
`S`	0, 59	Секунда с минимальной шириной
`s`	000, 500	Миллисекунда с минимальной шириной 3
`e`	Mon, Tue	Сокращения дней недели
`E`	Monday	Полное название дня недели

y

Выраженный числом год с фиксированной шириной

Y

1996

Выраженный числом год с минимальной шириной

m

1, 12

Выраженный числом месяц с фиксированной шириной

u

Jan

Название месяца, сокращенное до 3 символов в соответствии с локалью (locale)

U

January

Полное название месяца в соответствии с ключевым словом locale

d

1, 31

День месяца с минимальной шириной

H

0, 23

Час (в формате 24 часов) с минимальной шириной

M

0, 59

Минута с минимальной шириной

S

0, 59

Секунда с минимальной шириной

s

000, 500

Миллисекунда с минимальной шириной 3

e

Mon, Tue

Сокращения дней недели

E

Monday

Полное название дня недели

Число последовательных символов кода указывает ширину кода. Формат yyyy-mm указывает, что код y должен иметь ширину четыре, а код m — ширину два. Коды, которые выдают цифры, имеют связанный режим: фиксированной ширины или минимальной ширины. Режим фиксированной ширины заполняет значение нулями слева, когда оно короче, чем указанная ширина, и усекает значение, когда оно длиннее. Режим минимальной ширины работает так же, как и режим фиксированной ширины, за исключением того, что он не усекает значения, длина которых превышает ширину.

При создании формата (format) в качестве разделителя можно использовать любые символы, не являющиеся символами кода. Например, чтобы сгенерировать строку "1996-01-15T00:00:00", можно использовать формат (format) "yyyy-mm-ddTHH:MM:SS". Обратите внимание, что если вам нужно использовать символ кода в качестве литерала, вы можете использовать escape-символ «обратный слэш». Строку "1996y01m" можно создать с помощью формата "yyyy\ymm\m".

# Dates.DateFormat — Type

DateFormat(format::AbstractString, locale="english") -> DateFormat

Конструирует объект форматирования даты, который можно использовать для анализа строк дат или форматирования объекта даты как строки. Для конструирования строки format можно использовать следующие коды символов:

Код Соответствующие значения Примечание

Код	Соответствующие значения	Примечание
`Y`	1996, 96	Возвращает год 1996, 0096
`y`	1996, 96	То же, что `Y`, при анализе (`parse`), но лишние цифры в `format` отбрасываются
`m`	1, 01	Соответствует месяцам, состоящим из 1 или 2 цифр
`u`	Jan	Соответствует сокращенным названиям месяцев в соответствии с именованным аргументом `locale`
`U`	January	Соответствует полным названиям месяцев в соответствии с именованным аргументом `locale`
`d`	1, 01	Соответствует дням, состоящим из 1 или 2 цифр
`H`	00	Соответствует часам (в 24-часовом формате)
`I`	00	Для вывода часов в 12-часовом формате
`M`	00	Соответствует минутам
`S`	00	Соответствует секундам
`s`	.500	Соответствует миллисекундам
`e`	Mon, Tues	Соответствует сокращенным названиям дней недели
`E`	Monday	Соответствует полным названиям дней недели
`p`	AM	Соответствует указанию AM/PM (без учета регистра)
`yyyymmdd`	19960101	Соответствует указанию года, месяца и дня фиксированной ширины

Y

1996, 96

Возвращает год 1996, 0096

y

1996, 96

То же, что Y, при анализе (parse), но лишние цифры в format отбрасываются

m

1, 01

Соответствует месяцам, состоящим из 1 или 2 цифр

u

Jan

Соответствует сокращенным названиям месяцев в соответствии с именованным аргументом locale

U

January

Соответствует полным названиям месяцев в соответствии с именованным аргументом locale

d

1, 01

Соответствует дням, состоящим из 1 или 2 цифр

H

Соответствует часам (в 24-часовом формате)

I

Для вывода часов в 12-часовом формате

M

Соответствует минутам

S

Соответствует секундам

s

.500

Соответствует миллисекундам

e

Mon, Tues

Соответствует сокращенным названиям дней недели

E

Monday

Соответствует полным названиям дней недели

p

Соответствует указанию AM/PM (без учета регистра)

yyyymmdd

19960101

Соответствует указанию года, месяца и дня фиксированной ширины

Символы, не перечисленные выше, обычно рассматриваются как разграничители между слотами даты и времени. Например, строка dt "1996-01-15T00:00:00.0" будет иметь строку формата (format) вида "y-m-dTH:M:S.s". Если вам нужно использовать символ кода в качестве разграничителя, вы можете использовать escape-символ «обратный слэш». Дата "1995y01m" будет иметь формат "y\ym\m".

Обратите внимание, что 12:00 AM соответствует 00:00 (полуночи), а 12:00 PM — 12:00 (полудню). При анализе времени с помощью спецификатора p любой час (H или I) интерпретируется как имеющий 12-часовой формат, поэтому код I полезен в основном для вывода.

Создание объекта DateFormat затратно. Всегда, когда это возможно, создавайте его один раз и используйте многократно или попробуйте использовать строковый макрос dateformat"". При применении этого макроса создается объект DateFormat один раз во время расширения макроса, и он повторно используется далее. Существует несколько предопределенных средств форматирования, которые будут перечислены позже.

Сведения о том, как использовать объект DateFormat для анализа и записи строк даты, см. в разделах DateTime и format соответственно.

# Dates.@dateformat_str — Macro

dateformat"Y-m-d H:M:S"

Создает объект DateFormat. Аналогичен DateFormat("Y-m-d H:M:S"), но создает объект DateFormat один раз во время расширения макроса.

См. подробные сведения о спецификаторах формата в разделе DateFormat.

# Dates.DateTime — Method

DateTime(dt::AbstractString, df::DateFormat=ISODateTimeFormat) -> DateTime

Конструирует DateTime путем анализа строки даты и времени dt, следуя шаблону, заданному в объекте DateFormat, или формату даты yyyy-mm-dd\THH:MM:SS.s, если он опущен.

Аналогичен DateTime(::AbstractString, ::AbstractString), но более эффективен при неоднократном анализе строк даты и времени в похожем формате с предварительно созданным объектом DateFormat.

# Dates.Date — Method

Date(y, [m, d]) -> Date

Конструирует тип Date по частям. Аргументы должны иметь возможность преобразования в Int64.

# Dates.Date — Method

Date(period::Period...) -> Date

Конструирует тип Date по частям типа Period. Аргументы могут указываться в любом порядке. Неуказанные части Date по умолчанию будут иметь значение Dates.default(period).

# Dates.Date — Method

Date(f::Function, y[, m, d]; step=Day(1), limit=10000) -> Date

Создает дату (Date) с помощью API регулировщика. Начальная точка будет конструироваться из указанных аргументов y, m, d и будет регулироваться, пока функция f::Function не возвратит значение true. Величину шага регулировки можно указывать вручную с помощью ключевого слова step. limit указывает ограничение максимального числа итераций, которые будет осуществлять API регулировки, прежде чем выдавать ошибку (в том случае, если f::Function никогда не будет удовлетворять условиям).

Примеры

julia> Date(date -> week(date) == 20, 2010, 01, 01)
2010-05-17

julia> Date(date -> year(date) == 2010, 2000, 01, 01)
2010-01-01

julia> Date(date -> month(date) == 10, 2000, 01, 01; limit = 5)
ERROR: ArgumentError: Adjustment limit reached: 5 iterations
Stacktrace:
[...]

# Dates.Date — Method

Date(dt::DateTime) -> Date

Преобразует DateTime в Date. Компоненты часов, минут, секунд и миллисекунд DateTime усечены, поэтому только части года, месяца и дня используются в конструкции.

# Dates.Date — Method

Date(d::AbstractString, format::AbstractString; locale="english") -> Date

Конструирует Date, анализируя строку даты d, следуя шаблону, заданному в строке format (синтаксис см. в DateFormat).

Пример

julia> Date("2020-01-01", "yyyy-mm-dd")
2020-01-01

julia> a = ("2020-01-01", "2020-01-02");

julia> [Date(d, dateformat"yyyy-mm-dd") for d ∈ a] # предпочтительно
2-element Vector{Date}:
 2020-01-01
 2020-01-02

# Dates.Date — Method

Date(d::AbstractString, df::DateFormat=ISODateFormat) -> Date

Конструирует дату (Date), анализируя строку даты d, следуя шаблону, заданному в объекте DateFormat, или формату даты "yyyy-mm-dd", если он опущен.

Аналогичен Date(::AbstractString, ::AbstractString), но более эффективен при неоднократном анализе строк даты в похожем формате с предварительно созданным объектом DateFormat.

# Dates.Time — Method

Time(h, [mi, s, ms, us, ns]) -> Time

Конструирует тип Time по частям. Аргументы должны иметь возможность преобразования в Int64.

# Dates.Time — Method

Time(period::TimePeriod...) -> Time

Конструирует тип Time по частям типа Period. Аргументы могут указываться в любом порядке. Неуказанные части Time по умолчанию будут иметь значение Dates.default(period).

# Dates.Time — Method

Time(f::Function, h, mi=0; step::Period=Second(1), limit::Int=10000)
Time(f::Function, h, mi, s; step::Period=Millisecond(1), limit::Int=10000)
Time(f::Function, h, mi, s, ms; step::Period=Microsecond(1), limit::Int=10000)
Time(f::Function, h, mi, s, ms, us; step::Period=Nanosecond(1), limit::Int=10000)

Создает время (Time) с помощью API регулировщика. Начальная точка будет конструироваться из указанных аргументов h, mi, s, ms, us и будет регулироваться, пока функция f::Function не возвратит значение true. Величину шага регулировки можно указывать вручную с помощью ключевого слова step. limit предоставляет ограничение максимального числа итераций, которые будет осуществлять API регулировки, прежде чем выдавать ошибку (в том случае, если f::Function никогда не будет удовлетворять условиям). Обратите внимание, что величина по умолчанию будет регулироваться для большей точности для заданных аргументов; то есть если указаны аргументы «час», «минута» и «секунда», величина по умолчанию будет Millisecond(1), а не Second(1).

Примеры

julia> Time(t -> minute(t) == 30, 20)
20:30:00

julia> Time(t -> minute(t) == 0, 20)
20:00:00

julia> Time(t -> hour(t) == 10, 3; limit = 5)
ERROR: ArgumentError: Adjustment limit reached: 5 iterations
Stacktrace:
[...]

# Dates.Time — Method

Time(dt::DateTime) -> Time

Преобразует DateTime в Time. Компоненты часов, минут, секунд и миллисекунд DateTime используются для создания нового Time. Микросекунды и наносекунды по умолчанию имеют значение ноль.

# Dates.Time — Method

Time(t::AbstractString, format::AbstractString; locale="english") -> Time

Конструирует Time, анализируя строку времени t, следуя шаблону, заданному в строке format (синтаксис см. в DateFormat).

Пример

julia> Time("12:34pm", "HH:MMp")
12:34:00

julia> a = ("12:34pm", "2:34am");

julia> [Time(d, dateformat"HH:MMp") for d ∈ a] # предпочтительно
2-element Vector{Time}:
 12:34:00
 02:34:00

# Dates.Time — Method

Time(t::AbstractString, df::DateFormat=ISOTimeFormat) -> Time

Конструирует Time путем анализа строки даты и времени t, следуя шаблону, заданному в объекте DateFormat, или формату даты HH:MM:SS.s, если он опущен.

Аналогичен Time(::AbstractString, ::AbstractString), но более эффективен при неоднократном анализе строк времени в похожем формате с предварительно созданным объектом DateFormat.

# Dates.now — Method

now() -> DateTime

Возвращает дату и время (DateTime), соответствующие системному времени пользователя, в том числе локаль часового пояса системы.

# Dates.now — Method

now(::Type{UTC}) -> DateTime

Возвращает дату и время (DateTime), соответствующие системному времени пользователя в формате UTC/GMT.

# Base.eps — Method

eps(::Type{DateTime}) -> Millisecond
eps(::Type{Date}) -> Day
eps(::Type{Time}) -> Nanosecond
eps(::TimeType) -> Period

Возвращает наименьшее значение единицы, поддерживаемое TimeType.

Примеры

julia> eps(DateTime)
1 millisecond

julia> eps(Date)
1 day

julia> eps(Time)
1 nanosecond

Функции методов доступа

# Dates.year — Function

year(dt::TimeType) -> Int64

Год даты (Date) или даты и времени (DateTime) как Int64.

# Dates.month — Function

month(dt::TimeType) -> Int64

Месяц даты (Date) или даты и времени (DateTime) как Int64.

# Dates.week — Function

week(dt::TimeType) -> Int64

Возвращает дату недели ISO для даты (Date) или даты и времени (DateTime) как Int64. Обратите внимание, что первая неделя года — это неделя, которая содержит первый четверг года, что может привести к тому, что даты до 4 января будут находиться в последней неделе предыдущего года. Например, week(Date(2005, 1, 1)) — это 53-я неделя 2004 г.

Примеры

julia> week(Date(1989, 6, 22))
25

julia> week(Date(2005, 1, 1))
53

julia> week(Date(2004, 12, 31))
53

# Dates.day — Function

day(dt::TimeType) -> Int64

День месяца даты (Date) или даты и времени (DateTime) как Int64.

# Dates.hour — Function

hour(dt::DateTime) -> Int64

Час дня даты и времени (DateTime) как Int64.

hour(t::Time) -> Int64

Час времени (Time) как Int64.

# Dates.minute — Function

minute(dt::DateTime) -> Int64

Минута даты и времени (DateTime) как Int64.

minute(t::Time) -> Int64

Минута времени (Time) как Int64.

# Dates.second — Function

second(dt::DateTime) -> Int64

Секунда даты и времени (DateTime) как Int64.

second(t::Time) -> Int64

Секунда времени (Time) как Int64.

# Dates.millisecond — Function

millisecond(dt::DateTime) -> Int64

Миллисекунда даты и времени (DateTime) как Int64.

millisecond(t::Time) -> Int64

Миллисекунда времени (Time) как Int64.

# Dates.microsecond — Function

microsecond(t::Time) -> Int64

Микросекунда времени (Time) как Int64.

# Dates.nanosecond — Function

nanosecond(t::Time) -> Int64

Наносекунда времени (Time) как Int64.

# Dates.Year — Method

Year(v)

Конструирует объект Year с заданным значением v. Входные данные должны иметь возможность преобразования без потерь в Int64.

# Dates.Month — Method

Month(v)

Конструирует объект Month с заданным значением v. Входные данные должны иметь возможность преобразования без потерь в Int64.

# Dates.Week — Method

Week(v)

Конструирует объект Week с заданным значением v. Входные данные должны иметь возможность преобразования без потерь в Int64.

# Dates.Day — Method

Day(v)

Конструирует объект Day с заданным значением v. Входные данные должны иметь возможность преобразования без потерь в Int64.

# Dates.Hour — Method

Hour(dt::DateTime) -> Hour

Часть часа DateTime как час (Hour).

# Dates.Minute — Method

Minute(dt::DateTime) -> Minute

Часть минуты DateTime как минута (Minute).

# Dates.Second — Method

Second(dt::DateTime) -> Second

Часть секунды DateTime как секунда (Second).

# Dates.Millisecond — Method

Millisecond(dt::DateTime) -> Millisecond

Часть миллисекунды DateTime как миллисекунда (Millisecond).

# Dates.Microsecond — Method

Microsecond(dt::Time) -> Microsecond

Часть микросекунды времени как микросекунда (Microsecond).

# Dates.Nanosecond — Method

Nanosecond(dt::Time) -> Nanosecond

Часть наносекунды времени как наносекунда (Nanosecond).

# Dates.yearmonth — Function

yearmonth(dt::TimeType) -> (Int64, Int64)

Одновременно возвращает части года и месяца даты (Date) или даты и времени DateTime.

# Dates.monthday — Function

monthday(dt::TimeType) -> (Int64, Int64)

Одновременно возвращает части месяца и дня даты (Date) или даты и времени DateTime.

# Dates.yearmonthday — Function

yearmonthday(dt::TimeType) -> (Int64, Int64, Int64)

Одновременно возвращает части года, месяца и дня даты (Date) или даты и времени DateTime.

Функции запросов

# Dates.dayname — Function

dayname(dt::TimeType; locale="english") -> String
dayname(day::Integer; locale="english") -> String

Возвращает полное название дня, соответствующее дню недели даты (Date) или даты и времени (DateTime) в заданной локали (locale). Также принимает Integer.

Примеры

julia> dayname(Date("2000-01-01"))
"Saturday"

julia> dayname(4)
"Thursday"

# Dates.dayabbr — Function

dayabbr(dt::TimeType; locale="english") -> String
dayabbr(day::Integer; locale="english") -> String

Возвращает сокращение названия, соответствующее дню недели даты (Date) или даты и времени (DateTime) в заданной локали (locale). Также принимает Integer.

Примеры

julia> dayabbr(Date("2000-01-01"))
"Sat"

julia> dayabbr(3)
"Wed"

# Dates.dayofweek — Function

dayofweek(dt::TimeType) -> Int64

Возвращает день недели как Int64, где 1 = Monday, 2 = Tuesday, etc..

Примеры

julia> dayofweek(Date("2000-01-01"))
6

# Dates.dayofmonth — Function

dayofmonth(dt::TimeType) -> Int64

День месяца даты (Date) или даты и времени (DateTime) как Int64.

# Dates.dayofweekofmonth — Function

dayofweekofmonth(dt::TimeType) -> Int

Для дня недели dt возвращает данные о том, какой порядковый номер он занимает в месяце dt. Поэтому, если день недели dt — понедельник, то 1 = первый понедельник месяца, 2 = второй понедельник месяца и т д. в диапазоне 1:5.

Примеры

julia> dayofweekofmonth(Date("2000-02-01"))
1

julia> dayofweekofmonth(Date("2000-02-08"))
2

julia> dayofweekofmonth(Date("2000-02-15"))
3

# Dates.daysofweekinmonth — Function

daysofweekinmonth(dt::TimeType) -> Int

Для дня недели dt возвращает общее число этого дня недели в месяце dt . Возвращает 4 или 5. Полезна во временных выражениях для указания последнего дня недели месяца путем включения dayofweekofmonth(dt) == daysofweekinmonth(dt) в функцию регулировщика.

Примеры

julia> daysofweekinmonth(Date("2005-01-01"))
5

julia> daysofweekinmonth(Date("2005-01-04"))
4

# Dates.monthname — Function

monthname(dt::TimeType; locale="english") -> String
monthname(month::Integer, locale="english") -> String

Возвращает полное название месяца даты (Date) или даты и времени (DateTime) или целого числа (Integer) в заданной локали (locale).

Примеры

julia> monthname(Date("2005-01-04"))
"January"

julia> monthname(2)
"February"

# Dates.monthabbr — Function

monthabbr(dt::TimeType; locale="english") -> String
monthabbr(month::Integer, locale="english") -> String

Возвращает сокращение названия месяца даты (Date) или даты и времени (DateTime) или целого числа (Integer) в заданной локали (locale).

Примеры

julia> monthabbr(Date("2005-01-04"))
"Jan"

julia> monthabbr(2)
"Feb"

# Dates.daysinmonth — Function

daysinmonth(dt::TimeType) -> Int

Возвращает число дней в месяце dt. Значения могут быть 28, 29, 30 или 31.

Примеры

julia> daysinmonth(Date("2000-01"))
31

julia> daysinmonth(Date("2001-02"))
28

julia> daysinmonth(Date("2000-02"))
29

# Dates.isleapyear — Function

isleapyear(dt::TimeType) -> Bool

Возвращает значение true, если год dt — високосный.

Примеры

julia> isleapyear(Date("2004"))
true

julia> isleapyear(Date("2005"))
false

# Dates.dayofyear — Function

dayofyear(dt::TimeType) -> Int

Возвращает день года dt, (начиная с 1 января как первого дня).

# Dates.daysinyear — Function

daysinyear(dt::TimeType) -> Int

Возвращает 366, если год dt — високосный, в противном случае возвращает 365.

Примеры

julia> daysinyear(1999)
365

julia> daysinyear(2000)
366

# Dates.quarterofyear — Function

quarterofyear(dt::TimeType) -> Int

Возвращает квартал, в котором находится dt. Диапазон значения — 1:4.

# Dates.dayofquarter — Function

dayofquarter(dt::TimeType) -> Int

Возвращает день текущего квартала dt. Диапазон значения — 1:92.

Функции регулировщика

# Base.trunc — Method

trunc(dt::TimeType, ::Type{Period}) -> TimeType

Усекает значение dt в соответствии с указанным типом Period.

Примеры

julia> trunc(DateTime("1996-01-01T12:30:00"), Day)
1996-01-01T00:00:00

# Dates.firstdayofweek — Function

firstdayofweek(dt::TimeType) -> TimeType

Настраивает dt на понедельник недели, в которую он входит.

Примеры

julia> firstdayofweek(DateTime("1996-01-05T12:30:00"))
1996-01-01T00:00:00

# Dates.lastdayofweek — Function

lastdayofweek(dt::TimeType) -> TimeType

Настраивает dt на воскресенье недели, в которую он входит.

Примеры

julia> lastdayofweek(DateTime("1996-01-05T12:30:00"))
1996-01-07T00:00:00

# Dates.firstdayofmonth — Function

firstdayofmonth(dt::TimeType) -> TimeType

Настраивает dt на первый день месяца, в который он входит.

Примеры

julia> firstdayofmonth(DateTime("1996-05-20"))
1996-05-01T00:00:00

# Dates.lastdayofmonth — Function

lastdayofmonth(dt::TimeType) -> TimeType

Настраивает dt на последний день месяца, в который он входит.

Примеры

julia> lastdayofmonth(DateTime("1996-05-20"))
1996-05-31T00:00:00

# Dates.firstdayofyear — Function

firstdayofyear(dt::TimeType) -> TimeType

Настраивает dt на первый день года, в который он входит.

Примеры

julia> firstdayofyear(DateTime("1996-05-20"))
1996-01-01T00:00:00

# Dates.lastdayofyear — Function

lastdayofyear(dt::TimeType) -> TimeType

Настраивает dt на последний день года, в который он входит.

Примеры

julia> lastdayofyear(DateTime("1996-05-20"))
1996-12-31T00:00:00

# Dates.firstdayofquarter — Function

firstdayofquarter(dt::TimeType) -> TimeType

Настраивает dt на первый день квартала, в который он входит.

Примеры

julia> firstdayofquarter(DateTime("1996-05-20"))
1996-04-01T00:00:00

julia> firstdayofquarter(DateTime("1996-08-20"))
1996-07-01T00:00:00

# Dates.lastdayofquarter — Function

lastdayofquarter(dt::TimeType) -> TimeType

Настраивает dt на последний день квартала, в который он входит.

Примеры

julia> lastdayofquarter(DateTime("1996-05-20"))
1996-06-30T00:00:00

julia> lastdayofquarter(DateTime("1996-08-20"))
1996-09-30T00:00:00

# Dates.tonext — Method

tonext(dt::TimeType, dow::Int; same::Bool=false) -> TimeType

Настраивает dt на следующий день недели, соответствующий dow, где 1 = понедельник, 2 = вторник и т. д.. Установка same=true разрешает текущему dt рассматриваться как следующий dow, что не позволяет выполнить регулировку.

# Dates.toprev — Method

toprev(dt::TimeType, dow::Int; same::Bool=false) -> TimeType

Настраивает dt на предыдущий день недели, соответствующий dow, где 1 = понедельник, 2 = вторник и т. д.. Установка same=true разрешает текущему dt рассматриваться как предыдущий день недели (dow), что не позволяет выполнить регулировку.

# Dates.tofirst — Function

tofirst(dt::TimeType, dow::Int; of=Month) -> TimeType

Настраивает дату и время (dt) на первый день недели (dow) месяца, в который он входит. В качестве варианта, of=Year будет настраивать на первый день недели (dow) года.

# Dates.tolast — Function

tolast(dt::TimeType, dow::Int; of=Month) -> TimeType

Настраивает дату и время (dt) на последний день недели (dow) месяца, в который он входит. В качестве варианта, of=Year будет настраивать на последний день недели (dow) года.

# Dates.tonext — Method

tonext(func::Function, dt::TimeType; step=Day(1), limit=10000, same=false) -> TimeType

Настраивает дату и время (dt) путем итерации до максимального числа итераций limit с приращением step, пока func не возвратит значение true. func должна принимать один аргумент TimeType и возвращать Bool. same разрешает рассматривать дату и время (dt) при удовлетворении условий func.

# Dates.toprev — Method

toprev(func::Function, dt::TimeType; step=Day(-1), limit=10000, same=false) -> TimeType

Периоды

# Dates.Period — Method

Year(v)
Quarter(v)
Month(v)
Week(v)
Day(v)
Hour(v)
Minute(v)
Second(v)
Millisecond(v)
Microsecond(v)
Nanosecond(v)

Конструирует тип Period с заданным значением v. Входные данные должны иметь возможность преобразования без потерь в Int64.

# Dates.CompoundPeriod — Method

CompoundPeriod(periods) -> CompoundPeriod

Конструирует CompoundPeriod из вектора (Vector) периодов (Period). Все периоды Period одинакового типа будут добавлены вместе.

Примеры

julia> Dates.CompoundPeriod(Dates.Hour(12), Dates.Hour(13))
25 hours

julia> Dates.CompoundPeriod(Dates.Hour(-1), Dates.Minute(1))
-1 hour, 1 minute

julia> Dates.CompoundPeriod(Dates.Month(1), Dates.Week(-2))
1 month, -2 weeks

julia> Dates.CompoundPeriod(Dates.Minute(50000))
50000 minutes

# Dates.canonicalize — Function

canonicalize(::CompoundPeriod) -> CompoundPeriod

Упрощает CompoundPeriod в каноническую форму, применяя следующие правила.

Любой период (Period), достаточно большой, чтобы частично входить в более крупный период (Period), будет разбит на несколько периодов (Period) (например, Hour(30) становится Day(1) + Hour(6))
Периоды (Period) с противоположными знаками будут при возможности объединены (например, Hour(1) - Day(1) становится -Hour(23))

Примеры

julia> canonicalize(Dates.CompoundPeriod(Dates.Hour(12), Dates.Hour(13)))
1 day, 1 hour

julia> canonicalize(Dates.CompoundPeriod(Dates.Hour(-1), Dates.Minute(1)))
-59 minutes

julia> canonicalize(Dates.CompoundPeriod(Dates.Month(1), Dates.Week(-2)))
1 month, -2 weeks

julia> canonicalize(Dates.CompoundPeriod(Dates.Minute(50000)))
4 weeks, 6 days, 17 hours, 20 minutes

# Dates.value — Function

Dates.value(x::Period) -> Int64

Для заданного периода возвращает значение, связанное с этим периодом. Например, value(Millisecond(10)) возвращает 10 как целое число.

# Dates.default — Function

default(p::Period) -> Period

Возвращает разумное значение «по умолчанию» для входного периода, возвращая T(1) для года, месяца и дня и T(0) для часа, минуты, секунды и миллисекунды.

# Dates.periods — Function

Dates.periods(::CompoundPeriod) -> Vector{Period}

Возвращает вектор (Vector) периодов (Period), которые охватывают данный CompoundPeriod.

Совместимость: Julia 1.7

Для этой функции требуется версия не ниже Julia 1.7.

Функции округления

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

# Base.floor — Method

floor(dt::TimeType, p::Period) -> TimeType

Возвращает ближайшую дату (Date) или дату и время (DateTime), меньшую или равную dt при разрешении p.

Для удобства p может быть типом, а не значением: floor(dt, Dates.Hour) — это ярлык для floor(dt, Dates.Hour(1)).

julia> floor(Date(1985, 8, 16), Month)
1985-08-01

julia> floor(DateTime(2013, 2, 13, 0, 31, 20), Minute(15))
2013-02-13T00:30:00

julia> floor(DateTime(2016, 8, 6, 12, 0, 0), Day)
2016-08-06T00:00:00

# Base.ceil — Method

ceil(dt::TimeType, p::Period) -> TimeType

Возвращает ближайшую дату (Date) или дату и время (DateTime), большую или равную dt при разрешении p.

Для удобства p может быть типом, а не значением: ceil(dt, Dates.Hour) — это ярлык для ceil(dt, Dates.Hour(1)).

julia> ceil(Date(1985, 8, 16), Month)
1985-09-01

julia> ceil(DateTime(2013, 2, 13, 0, 31, 20), Minute(15))
2013-02-13T00:45:00

julia> ceil(DateTime(2016, 8, 6, 12, 0, 0), Day)
2016-08-07T00:00:00

# Base.round — Method

round(dt::TimeType, p::Period, [r::RoundingMode]) -> TimeType

Возвращает дату (Date) или дату и время (DateTime), ближайшую к dt при разрешении p. По умолчанию (RoundNearestTiesUp), привязки (например, округление 9:30 до ближайшего часа) будут округляться.

Для удобства p может быть типом, а не значением: round(dt, Dates.Hour) — это ярлык для round(dt, Dates.Hour(1)).

julia> round(Date(1985, 8, 16), Month)
1985-08-01

julia> round(DateTime(2013, 2, 13, 0, 31, 20), Minute(15))
2013-02-13T00:30:00

julia> round(DateTime(2016, 8, 6, 12, 0, 0), Day)
2016-08-07T00:00:00

Допустимые режимы округления для round(::TimeType, ::Period, ::RoundingMode) — RoundNearestTiesUp (по умолчанию), RoundDown (floor) и RoundUp (ceil).

Большинство значений Period также можно округлить до заданного разрешения:

# Base.floor — Method

floor(x::Period, precision::T) where T <: Union{TimePeriod, Week, Day} -> T

Округлить x до ближайшего кратного precision. Если x и precision являются разными подтипами Period, возвращаемое значение будет иметь тот же тип, что и precision.

Для удобства precision может быть типом, а не значением: floor(x, Dates.Hour) является ярлыком для floor(x, Dates.Hour(1)).

julia> floor(Day(16), Week)
2 weeks

julia> floor(Minute(44), Minute(15))
30 minutes

julia> floor(Hour(36), Day)
1 day

Округление до точности (precision) месяцев (Month) или лет (Year) не поддерживается, так как эти периоды (Period) имеют непоследовательную длину.

# Base.ceil — Method

ceil(x::Period, precision::T) where T <: Union{TimePeriod, Week, Day} -> T

Для удобства precision может быть типом, а не значением: ceil(x, Dates.Hour) является ярлыком для ceil(x, Dates.Hour(1)).

julia> ceil(Day(16), Week)
3 weeks

julia> ceil(Minute(44), Minute(15))
45 minutes

julia> ceil(Hour(36), Day)
2 days

# Base.round — Method

round(x::Period, precision::T, [r::RoundingMode]) where T <: Union{TimePeriod, Week, Day} -> T

Округляет x до ближайшего кратного precision. Если x и precision являются разными подтипами Period, возвращаемое значение будет иметь тот же тип, что и precision. По умолчанию (RoundNearestTiesUp), привязки (например, если требуется округлить 90 минут до ближайшего часа) будут округляться .

Для удобства precision может быть типом, а не значением: round(x, Dates.Hour) является ярлыком для round(x, Dates.Hour(1)).

julia> round(Day(16), Week)
2 weeks

julia> round(Minute(44), Minute(15))
45 minutes

julia> round(Hour(36), Day)
2 days

Допустимые режимы округления для round(::Period, ::T, ::RoundingMode) — RoundNearestTiesUp (по умолчанию), RoundDown (floor) и RoundUp (ceil).

Следующие функции не экспортируются:

# Dates.floorceil — Function

floorceil(dt::TimeType, p::Period) -> (TimeType, TimeType)

Одновременно возвращает floor и ceil даты (Date) или даты и времени (DateTime) при разрешении p. Эффективнее, чем вызов floor и ceil по отдельности.

floorceil(x::Period, precision::T) where T <: Union{TimePeriod, Week, Day} -> (T, T)

Одновременно возвращает floor и ceil периода (Period) при разрешении p. Эффективнее, чем вызов floor и ceil по отдельности.

# Dates.epochdays2date — Function

epochdays2date(days) -> Date

Принимает число дней с эпохи округления (0000-01-01T00:00:00) и возвращает соответствующую дату (Date).

# Dates.epochms2datetime — Function

epochms2datetime(milliseconds) -> DateTime

Принимает число миллисекунд с эпохи округления (0000-01-01T00:00:00) и возвращает соответствующие дату и время (DateTime).

# Dates.date2epochdays — Function

date2epochdays(dt::Date) -> Int64

Принимает заданную дату (Date) и возвращает число дней с эпохи округления (0000-01-01T00:00:00) как Int64.

# Dates.datetime2epochms — Function

datetime2epochms(dt::DateTime) -> Int64

Принимает заданную дату (DateTime) и возвращает число миллисекунд с эпохи округления (0000-01-01T00:00:00) как Int64.

Функции преобразования

# Dates.today — Function

today() -> Date

Возвращает часть даты now().

# Dates.unix2datetime — Function

unix2datetime(x) -> DateTime

Принимает число секунд с эпохи Unix 1970-01-01T00:00:00 и преобразует в соответствующие дату и время (DateTime).

# Dates.datetime2unix — Function

datetime2unix(dt::DateTime) -> Float64

Принимает заданные дату и время (DateTime) и возвращает число секунд с эпохи Unix 1970-01-01T00:00:00 как Float64.

# Dates.julian2datetime — Function

julian2datetime(julian_days) -> DateTime

Принимает число дней юлианского календаря с эпохи -4713-11-24T12:00:00 и возвращает соответствующие дату и время (DateTime).

# Dates.datetime2julian — Function

datetime2julian(dt::DateTime) -> Float64

Принимает заданные дату и время (DateTime) и возвращает число дней юлианского календаря с юлианской эпохи -4713-11-24T12:00:00 как Float64.

# Dates.rata2datetime — Function

rata2datetime(days) -> DateTime

Принимает число дней Rata Die с эпохи 0000-12-31T00:00:00 и возвращает соответствующие дату и время (DateTime).

# Dates.datetime2rata — Function

datetime2rata(dt::TimeType) -> Int64

Возвращает число дней Rata Die с эпохи из заданных даты (Date) или даты и времени (DateTime).

Константы

Дни недели:

Переменная Сокращение Значение (целочисленное)

Переменная	Сокращение	Значение (целочисленное)
`Monday`	`Mon`	1
`Tuesday`	`Tue`	2
`Wednesday`	`Wed`	3
`Thursday`	`Thu`	4
`Friday`	`Fri`	5
`Saturday`	`Sat`	6
`Sunday`	`Sun`	7

Monday

Mon

Tuesday

Tue

Wednesday

Wed

Thursday

Thu

Friday

Fri

Saturday

Sat

Sunday

Sun

Месяцы года:

Переменная Сокращение Значение (целочисленное)

Переменная	Сокращение	Значение (целочисленное)
`January`	`Jan`	1
`February`	`Feb`	2
`March`	`Mar`	3
`April`	`Apr`	4
`May`	`May`	5
`June`	`Jun`	6
`July`	`Jul`	7
`August`	`Aug`	8
`September`	`Sep`	9
`October`	`Oct`	10
`November`	`Nov`	11
`December`	`Dec`	12

January

Jan

February

Feb

March

Mar

April

Apr

May

June

Jun

July

Jul

August

Aug

September

Sep

October

Oct

November

Nov

December

Dec

Основные средства форматирования дат

# Dates.ISODateTimeFormat — Constant

Dates.ISODateTimeFormat

Описывает форматирование ISO8601 для даты и времени. Это значение по умолчанию для Dates.format DateTime.

Пример

julia> Dates.format(DateTime(2018, 8, 8, 12, 0, 43, 1), ISODateTimeFormat)
"2018-08-08T12:00:43.001"

# Dates.ISODateFormat — Constant

Dates.ISODateFormat

Описывает форматирование ISO8601 для даты. Это значение по умолчанию для Dates.format даты (Date).

Пример

julia> Dates.format(Date(2018, 8, 8), ISODateFormat)
"2018-08-08"

# Dates.ISOTimeFormat — Constant

Dates.ISOTimeFormat

Описывает форматирование ISO8601 для времени. Это значение по умолчанию для Dates.format времени (Time).

Пример

julia> Dates.format(Time(12, 0, 43, 1), ISOTimeFormat)
"12:00:43.001"

# Dates.RFC1123Format — Constant

Dates.RFC1123Format

Описывает форматирование RFC1123 для даты и времени.

Пример

julia> Dates.format(DateTime(2018, 8, 8, 12, 0, 43, 1), RFC1123Format)
"Wed, 08 Aug 2018 12:00:43"

1. Понятие секунды всемирного времени на самом деле является достаточно фундаментальным. В принципе, существует два общепринятых представления о времени: одно основано на физическом вращении Земли (один полный оборот равен одним суткам), другое — на секунде в международной системе единиц (фиксированная, постоянная величина). Они кардинально отличаются. Только подумайте, секунда всемирного времени, определенная относительно вращения Земли, может иметь разную абсолютную длину в зависимости от дня! В любом случае, тот факт, что Date и DateTime основаны на секундах всемирного времени, является упрощающим, но честным допущением, позволяющим избежать таких вещей, как добавочные секунды и все связанные с ними сложности. Такой базис времени формально называется всемирным временем (UT) или UT1. Базирование типов на секунде всемирного времени означает, что каждая минута состоит из 60 секунд, а каждый день — из 24 часов, и приводит к более естественным вычислениям при работе с календарными датами.