Модуль:Date/документація

Цей модуль надає функції з датами для використання іншими модулями. Підтримуються дати в григоріанському та юліанському калегдарях, від 9999 до н.е. до 9999 н.е. Календарі є пролептичними, тобто вважається, що вони застосовувалися для всіх часів без виключень.

Дата, з оптимальним часом, може бути зазначена в різних форматах та може бути перетворення для відображення в різні формати, наприклад, 1 квітня 2016 або квітня 1, 2016. Властивості дати включають її юлінську дату та григоріанську дату, а також день тижня та день року.

Дати можна порівнювати (наприклад, date1 <= date2), а також можна їх додавити і віднімати (наприклад, date + '3 months'). Різниція між двома датами може бути визначення через date1 - date2. Ці операції працюють дат як григоріанського так і юлінанського календарів, але date1 - date2 є nil, якщо дві дати з різних календарів.

Модуль надає наступні елементи.

Елементи, що повертає модуль	Опис
_current	Таблиця з поточним роком, місяцем, днем, годиною, хвилиною, секундою.
_Date	Функція, що повертає таблицю для визначеної дати.
_days_in_month	Функція, що повертає кількість днів у місяці.

Нижче наведено приклади використання модулю:

• Модуль:Date/example • приклад, що показує як Модуль:Date може бути використаний.
• Обговорення модуля:Date/example • результат роботи прикладу.

Форматування вихідних даних

Дата може бути відформатована, щоб відображуватися у вигляді тексту.

local Date = require('Module:Date')._Date
local text = Date(2016, 7, 1):text()          -- результатом є '1 July 2016'
local text = Date(2016, 7, 1):text('%-d %B')  -- результатом є '1 July'
local text = Date('1 July 2016'):text('mdy')  -- результатом є 'July 1, 2016'

Доступні спрощені коди форматування, що наведені нижче.

Код	Результат
hm	година:хвилина, з «am» або «pm» або інший варіант, якщо зазначено (14:30 або 2:30 pm або інший варіант)
hms	година:хвилина:секунда (14:30:45)
ymd	рік-місяць-день (2016-07-01)
mdy	місяць день, рік (July 1, 2016)
dmy	день місяць рік (1 July 2016)

Доступні коди форматування (подібні до strftime), що наведені нижче.

Код	Результат
%a	Скорочення для днів: Mon, Tue, ...
%A	Назва днів: Monday, Tuesday, ...
%u	День тижня: 1 to 7 (Monday to Sunday)
%w	День тижня: 0 to 6 (Sunday to Saturday)
%d	День місяця з нулем на початку: 01 to 31
%b	Скорочення для місяців: Jan to Dec
%B	Назва місяця: January to December
%m	Місяць з нулем на початку: 01 to 12
%Y	Рік з нулем на початку: 0012, 0120, 1200
%H	Година 24-годинного формату часу з нулем на початку: 00 to 23
%I	Година 12-годинного формату часу з нулем на початку: 01 to 12
%p	AM або PM або як в опціях
%M	Хвилина з нулем на початку: 00 to 59
%S	Секунда з нулем на початку: 00 to 59
%j	День року з нулем на початку: 001 to 366
%-d	День місяця: 1 to 31
%-m	Місяць: 1 to 12
%-Y	Рік: 12, 120, 1200
%-H	Година 24-годинного формату часу: 0 to 23
%-M	Хвилина: 0 to 59
%-S	Секунда: 0 to 59
%-j	День року: 1 to 366
%-I	Годлина 12-годинного формату часу: 1 to 12
%%	%

На додаток, можна використовувати %{property} (де property є будь-якою властивістю дати).

Наприклад, Date('1 Feb 2015 14:30:45 A.D.') має наступні властовості.

Код	Результат
%{calendar}	Gregorian
%{year}	2015
%{month}	2
%{day}	1
%{hour}	14
%{minute}	30
%{second}	45
%{dayabbr}	Sun
%{dayname}	Sunday
%{dayofweek}	0
%{dow}	0 (такий самий як і dayofweek)
%{dayofweekiso}	7
%{dowiso}	7 (такий самий як і dayofweekiso)
%{dayofyear}	32
%{era}	A.D.
%{gsd}	735630 (кількість днів від 1 січня 1 н.е.; першим є день 1)
%{juliandate}	2457055.1046875 (Юліанський день)
%{jd}	2457055.1046875 (такий самий як і juliandate)
%{isleapyear}	false
%{monthdays}	28
%{monthabbr}	Feb
%{monthname}	February

Доступні деякі скорочення. Якщо візьмемо date = Date('1 Feb 2015 14:30'), то можемо отримати наступні результати.

Код	Опис	Приклад результату	Еквівалентне форматування
date:text('%c')	дата та час	2:30 pm 1 February 2015	%-I:%M %p %-d %B %-Y %{era}
date:text('%x')	дата	1 February 2015	%-d %B %-Y %{era}
date:text('%X')	час	2:30 pm	%-I:%M %p

Дата за юліанським календарем

Нижче наведено приклад перетворення Дата за юліанським календарем в дату, а потім отримання іформацію про дату.

-- Код                                                 -- Результат
Date = require('Module:Date')._Date
date = Date('juliandate', 320)
number = date.gsd                                      -- -1721105
number = date.jd                                       -- 320
text = date.dayname                                    -- Saturday
text = date:text()                                     -- 9 October 4713 BC
text = date:text('%Y-%m-%d')                           -- 4713-10-09
text = date:text('%{era} %Y-%m-%d')                    -- BC 4713-10-09
text = date:text('%Y-%m-%d %{era}')                    -- 4713-10-09 BC
text = date:text('%Y-%m-%d %{era}', 'era=B.C.E.')      -- 4713-10-09 B.C.E.
text = date:text('%Y-%m-%d', 'era=BCNEGATIVE')         -- -4712-10-09
text = date:text('%Y-%m-%d', 'era=BCMINUS')            -- −4712-10-09 (використовує Unicode MINUS SIGN U+2212)
text = Date('juliandate',320):text('%{gsd} %{jd}')     -- -1721105 320
text = Date('Oct 9, 4713 B.C.E.'):text('%{gsd} %{jd}') -- -1721105 320
text = Date(-4712,10,9):text('%{gsd} %{jd}')           -- -1721105 320

Різниця дат

Різниця між двома датими можна визначити через date1 - date2. Результат є дійсним, якщо обидві дати використовують григоріанський календар або якщо обидві дати використовують юліанський календар, в іншому випадку результатом є nil. Вік та тривалість можна обрахувати, використовуючи різницю дат.

Наприклад:

-- Код                                       -- Результат
Date = require('Module:Date')._Date
date1 = Date('21 Mar 2015')
date2 = Date('4 Dec 1999')
diff = date1 - date2
d = diff.age_days                            -- 5586
y, m, d = diff.years, diff.months, diff.days -- 15, 3, 17 (15 років + 3 місяці + 17 днів)
y, m, d = diff:age('ymd')                    -- 15, 3, 17
y, m, w, d = diff:age('ymwd')                -- 15, 3, 2, 3 (15 років + 3 місяці + 2 тижні + 3 дні)
y, m, w, d = diff:duration('ymwd')           -- 15, 3, 2, 4
d = diff:duration('d')                       -- 5587 (тривалість включно з останнім днем)

Різниця дат містить оригінальні значення, крім випадку, коли значення були поміняні місцями, щоб виконувалася умова diff.date1 >= diff.date2 (diff.date1 є більш новішою датою). Це продемонстровано нижче.

date1 = Date('21 Mar 2015')
date2 = Date('4 Dec 1999')
diff = date1 - date2
neg = diff.isnegative                        -- false
text = diff.date1:text()                     -- 21 March 2015
text = diff.date2:text()                     -- 4 December 1999
diff = date2 - date1
neg = diff.isnegative                        -- true (дати поміняно місцями)
text = diff.date1:text()                     -- 21 March 2015
text = diff.date2:text()                     -- 4 December 1999

Різниця дат також вміщує і різницю часу:

date1 = Date('8 Mar 2016 0:30:45')
date2 = Date('19 Jan 2014 22:55')
diff = date1 - date2
y, m, d = diff.years, diff.months, diff.days      -- 2, 1, 17
H, M, S = diff.hours, diff.minutes, diff.seconds  -- 1, 35, 45

Різниця дат може бути додана до дати чи віднята від дати.

date1 = Date('8 Mar 2016 0:30:45')
date2 = Date('19 Jan 2014 22:55')
diff = date1 - date2
date3 = date2 + diff
date4 = date1 - diff
text = date3:text('ymd hms')        -- 2016-03-08 00:30:45
text = date4:text('ymd hms')        -- 2014-01-19 22:55:00
equal = (date1 == date3)            -- true
equal = (date2 == date4)            -- true

Методи різниць дати для віку і тривалості приймають код, що визначає компоненти, які варто повернути. Тривалість має додатковий день, бо включається із останній день.

Код	Значення, що повертаються
'ymwd'	роки, місяці, тижні, дні
'ymd'	роки, місяці, дні
'ym'	роки, місяці
'y'	роки
'm'	місяці
'wd'	тижні, дні
'w'	тижні
'd'	дні