time

Макрос !{time} предназначен для работы с датами и временем: парсинга, форматирования, вычислений и манипуляций.

Параметры

Входные параметры (источник времени)

• value — входное значение времени для обработки
  • По умолчанию принимает:
    • now — текущее время
    • RFC3339 формат (например: 2025-11-03T13:02:12+03:00)
  • Для других форматов необходимо указать input_format или format1

Форматы времени

• input_format (синоним: format1) — формат для парсинга входного значения value

  • Используется, если value не now и не RFC3339

• output_format (синоним: format2) — формат вывода результата

  • По умолчанию: RFC3339

Оба параметра поддерживают три типа форматов:

1. Стандартные форматы (названия)

• ANSIC — Mon Jan _2 15:04:05 2006
• UnixDate — Mon Jan _2 15:04:05 MST 2006
• RubyDate — Mon Jan 02 15:04:05 -0700 2006
• RFC822 — 02 Jan 06 15:04 MST
• RFC822Z — 02 Jan 06 15:04 -0700
• RFC850 — Monday, 02-Jan-06 15:04:05 MST
• RFC1123 — Mon, 02 Jan 2006 15:04:05 MST
• RFC1123Z — Mon, 02 Jan 2006 15:04:05 -0700
• RFC3339 — 2006-01-02T15:04:05Z07:00
• RFC3339Nano — 2006-01-02T15:04:05.999999999Z07:00
• Kitchen — 3:04PM
• DateTime — 2006-01-02 15:04:05
• DateOnly — 2006-01-02
• TimeOnly — 15:04:05

Специальные значения:

• unix — Unix timestamp (секунды)
• unixMilli — Unix timestamp (миллисекунды)

2. Пользовательский формат (буквенные паттерны)

некоторые работают только на выводе

• D — день (1-31)
• DD — день с нулём в начале (01-31)
• DDD — день недели, сокращённо (Mon, Tue, ...)
• DDDD — день недели, полностью (Monday, Tuesday, ...)
• M — номер месяца (1-12)
• MM — номер месяца с нулём (01-12)
• MMM — месяц, сокращённо (Jan, Feb, ...)
• MMMM — месяц, полностью (January, February, ...)
• YY — год сокращённо (24)
• YYYY — год полностью (2024)
• H — часы 12-часовой формат (1-12)
• HH — часы 12-часовой формат с нулём (01-12)
• h — часы 24-часовой формат (0-23)
• hh — часы 24-часовой формат с нулём (00-23)
• m — минуты (0-59)
• mm — минуты с нулём (00-59)
• s — секунды (0-59)
• ss — секунды с нулём (00-59)
• l — миллисекунды (0-999)
• a — am/pm (строчными)
• A — AM/PM (заглавными)
• z — временная зона сокращённая (+3)
• zz — временная зона полная (+03:00)
• zzz — временная зона буквами (MSK)
• W — номер недели (1-53)
• N — номер дня недели (1-7, где 1 = понедельник)

Примеры:

• DD.MM.YYYY → 31.12.2024
• YYYY-MM-DD hh:mm:ss → 2024-12-31 23:59:59
• DDDD, MMMM D, YYYY → Tuesday, December 31, 2024
• hh:mm A → 11:59 PM

3. Go layout формат

Стандартный формат Go с эталонной датой 01/02 03:04:05PM '06 -0700:

• 02.01.2006 → 31.12.2024
• 2006-01-02 15:04:05 → 2024-12-31 23:59:59
• Monday, 02 January 2006 → Tuesday, 31 December 2024

Манипуляции со временем

Добавление/вычитание длительности

• plus — добавить длительность

  • Формат: [число][единица], где единица: Y (годы), M (месяцы), D (дни), h (часы), m (минуты),s (секунды)
  • Можно комбинировать: 1h30m, 2D12h
  • Пример: plus:24h
  • Пример: plus:1D
  • Пример: plus:1h30m15s

• minus — вычесть длительность

  • Формат аналогичен add
  • Пример: minus:7d

• next — установка даты в следующий день недели возможные значения: (monday|mon|tuesday|tue|wednesday|wed|thursday|thu|friday|fri|saturday|sat|sunday|sun) (понедельник|пн|вторник|вт|среда|ср|четверг|чт|пятница|пт|суббота|сб|воскресенье|вс) (weekend|выходной)
  (weekday|будний|рабочий)

Установка компонентов времени

• setYear — установить год (например: setYear:2025)
• setMonth — установить месяц, 1-12 (например: setMonth:12)
• setDay — установить день месяца, 1-31 (например: setDay:15)
• setHour — установить час, 0-23 (например: setHour:14)
• setMinute — установить минуту, 0-59 (например: setMinute:30)
• setSecond — установить секунду, 0-59 (например: setSecond:0)

Часовые пояса

• input_timezone (синоним: timezone1) — часовой пояс входного времени

  • Используется для интерпретации входного времени, если оно не содержит информацию о часовом поясе
  • Форматы:
    • IANA timezone: Europe/Moscow, America/New_York, UTC
    • Числовое смещение: 3, +3, +03, +03:00, -5, -05:00
  • Пример: input_timezone:Europe/Moscow
  • Пример: timezone1:+3

• output_timezone (синоним: timezone2) — часовой пояс выходного времени

  • Используется для преобразования времени в указанный часовой пояс перед выводом
  • Форматы:
    • IANA timezone: Europe/Moscow, America/New_York, UTC
    • Числовое смещение: 3, +3, +03, +03:00, -5, -05:00
  • Пример: output_timezone:UTC
  • Пример: timezone2:+03:00

Округление

• round — округлить время

  • Значения: second, minute, hour, day, week, month, year
  • Округляет до ближайшего значения
  • Пример: round:hour → округлит до ближайшего часа
  • Пример: round:minute → округлит до ближайшей минуты

• truncate — обрезать время (округление вниз)

  • Значения: second, minute, hour, day, week, month, year
  • Пример: truncate:day → установит время в 00:00:00
  • Пример: truncate:hour → установит минуты и секунды в 0

Порядок выполнения операций

Операции выполняются в следующем порядке:

1. Получение исходного времени (value:now или value с input_format/format1 и input_timezone/timezone1)
2. Установка компонентов (setYear, setMonth, setDay, setHour, setMinute, setSecond)
3. Арифметические операции (add, sub)
4. Округление (round, truncate)
5. Изменение часового пояса (output_timezone/timezone2)
6. Форматирование вывода (output_format/format2)

Примечания

• Все операции с датами учитывают високосные годы и количество дней в месяце
• По умолчанию вывод в формате RFC3339, если output_format не указан
• Параметры value по умолчанию принимают now или RFC3339, для других форматов нужен input_format
• Можно комбинировать множество операций в одном вызове макроса
• Параметры input_format и format1 взаимозаменяемы
• Параметры output_format и format2 взаимозаменяемы
• Параметры input_timezone и timezone1 взаимозаменяемы
• Параметры output_timezone и timezone2 взаимозаменяемы