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

• tg_format (синоним: format3) — обернуть результат в HTML-сущность <tg-time> для нативного отображения даты/времени в Telegram

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

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

• DateTime — 2006-01-02 15:04:05
• DateOnly — 2006-01-02
• TimeOnly — 15:04:05

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

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

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

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

• D — день (1-31)
• DD — день с нулём в начале (01-31)
• M — номер месяца (1-12)
• MM — номер месяца с нулём (01-12)
• YY — год сокращённо (24)
• YYYY — год полностью (2024)
• m — минуты (0-59)
• mm — минуты с нулём (00-59)
• s — секунды (0-59)
• ss — секунды с нулём (00-59)
• h — часы 24-часовой формат (0-23)
• hh — часы 24-часовой формат с нулём (00-23)

Примеры

!{time| 
  value:now; 
  output_format:DD.MM.YYYY;}

Результат:

• 16.03.2026

!{time| 
  value:now;
  output_format:DD.MM.YY;}

Результат:

• 16.03.26

!{time| 
  value:now; 
  output_format:YYYY-MM-DD hh:mm:ss; }

Результат:

• 2026-03-16 14:30:45

!{time| 
  value:now; 
  output_format:DDDD, MMMM D, YYYY;}

!{time| 
  value:now; 
  output_format:hh:mm A;}

!{time| 
  value:now; 
  output_format:h:mm a zz;}

!{time| 
  value:now; 
  output_format:DDD, MMM D YYYY;}

!{time| 
  value:now; 
  output_format:HH:mm:ss l;}

!{time| 
  value:now; 
  output_format:W-й день недели;}

!{time| 
  value:now; 
  output_format:N-й день недели (1-пн);}

Telegram tg-time форматирование

• tg_format (синоним: format3) — обернуть результат в HTML-сущность <tg-time> для нативного отображения даты/времени в Telegram
  • Telegram отображает такие даты в локализованном формате пользователя
  • Допустимые значения (regex r|w?[dD]?[tT]?):
    • r — относительное время («через 5 минут», «вчера»); нельзя комбинировать с другими флагами
    • w — день недели
    • d — дата в коротком виде (17.03.22)
    • D — дата в длинном виде (March 17, 2022)
    • t — время в коротком виде (22:45)
    • T — время в длинном виде (22:45:00)
    • Флаги можно комбинировать: wDT, wt, Dt и т.д.
  • Текст внутри тега (output_format/format2) используется как fallback

Примеры

!{time| 
  value:now; 
  plus:3D12h30m; }

Результат:

• 2026-03-19T03:00:45+03:00

(через 3 дня 12.5 часов в RFC3339)

!{time| 
  value:now; 
  plus:3D12h30m; 
  tg_format:r; }

Результат:

• <tg-time>через 3 дня</tg-time>

(относительное время)

!{time| 
  value:now; 
  plus:3D12h30m; 
  tg_format:wDT; }

Результат:

• <tg-time>чт, 19 мар. 2026 г., 03:00</tg-time>

(день недели + дата + время)

!{time| 
  value:now; 
  plus:3D12h30m; 
  tg_format:dt;}

!{time| 
  value:now; 
  plus:12h30m; 
  tg_format:r; }

!{time| 
  value:now; 
  plus:12h30m; 
  tg_format:wDT; }

!{time| 
  value:now; 
  plus:12h30m; 
  tg_format:dt;}

!{time| 
  value:now; 
  plus:2Y3D12h30m; 
  tg_format:r; }

!{time| 
  value:now; 
  plus:2Y3D12h30m; 
  tg_format:wDT; }

!{time| 
  value:now; 
  plus:2Y3D12h30m; 
  tg_format:dt; }

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

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

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

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

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

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

• next — установка даты в следующий день недели

Доступные значения:

Примеры

!{time| 
  value:now; 
  plus:1h30m; }

Результат:

Текущее время + 1 час 30 минут

!{time| 
  value:now; 
  plus:2D; }

Результат: Текущее время + 2 дня

!{time| 
  value:now; 
  plus:1Y2M3D; }

Результат: Текущее время + 1 год 2 месяца 3 дня

!{time| 
  value:now; 
  minus:30m; }

!{time| 
  value:now; 
  minus:7D; }

!{time| 
  value:2025-01-01T00:00:00Z; 
  plus:1Y; 
  output_format:DD.MM.YYYY; }

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

• 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

Примеры

!{time| 
  value:now; 
  setYear:2030; 
  setMonth:1; 
  setDay:1; 
  setHour:12; 
  setMinute:0; 
  setSecond:0; 
  output_timezone:UTC; }

Результат:

2030-01-01T09:00:00Z

(если текущий пояс MSK+3, то 12:00 MSK → 09:00 UTC)

!{time| 
  value:now; 
  setHour:9; 
  setMinute:30; 
  setSecond:0; 
  output_timezone:America/New_York; 
  output_format:YYYY-MM-DD hh:mm:ss zz; }

Результат:

2026-03-17 02:30:00 -04:00

(сегодня в 9:30 MSK → время в Нью-Йорке)

!{time| 
  value:2025-12-31T23:00:00Z; 
  setDay:25; 
  setMonth:12; 
  output_timezone:Europe/London; 
  output_format:DD.MM.YYYY hh:mm; }

Результат:

25.12.2025 23:00

(дата изменена, время осталось в London)

!{time| 
  value:now; 
  setYear:2030; 
  setMonth:1; 
  setDay:1; 
  setHour:12; s
  etMinute:0; 
  setSecond:0; 
  output_timezone:UTC; }

!{time| 
 value:now; 
 setYear:2024; 
 setMonth:2; 
 setDay:29; 
 input_timezone:UTC; 
 output_format:DD.MM.YYYY; }

!{time| 
 value:2026-03-17T10:00:00+03:00; 
 setHour:0; 
 setMinute:0; 
 setSecond:0; 
 output_timezone:+05:00; 
 output_format:YYYY-MM-DD hh:mm:ss zz; }

!{time| 
 value:now; 
 setMonth:12; 
 setDay:31; 
 setHour:23; 
 setMinute:59; 
 timezone2:UTC; 
 output_format:DD.MM.YYYY hh:mm; }

!{time| 
 value:2026-06-15T00:00:00; 
 input_format:YYYY-MM-DDThh:mm:ss; 
 input_timezone:America/New_York; 
 setHour:12; 
 output_timezone:Europe/Moscow; 
 output_format:DD.MM.YYYY hh:mm zzz; }

!{time| 
 value:now; 
 setYear:2025; 
 setMonth:1; 
 setDay:1; 
 setHour:0; 
 setMinute:0; 
 timezone1:+9; 
 timezone2:UTC; 
 output_format:YYYY-MM-DD hh:mm:ss; }

!{time| 
 value:2026-03-17T15:30:00Z; 
 setMinute:45; 
 output_timezone:+03:00; 
 output_format:hh:mm:ss zz; }

!{time| 
 value:now; 
 setYear:2030; 
 setMonth:1; 
 setDay:1; 
 setHour:0; 
 setMinute:0; 
 setSecond:0; 
 input_timezone:UTC; 
 output_timezone:Asia/Tokyo; 
 output_format:DDDD, MMMM D, YYYY hh:mm; }

Округление

• 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

Примеры

!{time| 
  value:now; 
  round:hour; }

Результат:

Текущее время, округлённое до ближайшего часа (например, 14:30 → 15:00, 14:15 → 14:00)

!{time| 
  value:now; 
  round:day; }

Результат:

Текущее время, округлённое до ближайшего дня (до 12:00: если сейчас 14:30 → завтра 00:00, если 10:00 → сегодня 00:00)

!{time| 
  value:now; 
  truncate:day; 
  output_format:DD.MM.YYYY hh:mm:ss; }

Результат:

Сегодня в 00:00:00

!{time| 
  value:now; 
  truncate:month; 
  output_format:DD.MM.YYYY; }

Результат:

Первый день текущего месяца (01.03.2026)

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

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

1. Получение входного времени (value:now или value с input_format/format1 и input_timezone/timezone1)
2. Установка компонентов (setYear, setMonth, setDay, setHour, setMinute, setSecond)
3. Счет следующего дня недели (next)
4. Арифметика (plus, minus)
5. Округление (round, truncate)
6. Изменение часового пояса (output_timezone/timezone2)
7. Форматирование вывода (output_format/format2)
8. Обёртка в <tg-time> (tg_format/format3)

Примечания

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