yoshida yoshida DEV
Open the editor

Docs Format Expressions

Expressions: Dates and Times

On this page

Expressions have no clock. The render receives one instant from whoever starts it, so the same project always gives the same output. Dates and times are text in ISO form, so a text param, a card value or a render value can be used directly.

Accepted text

KindFormExample
dateYYYY-MM-DD2026-10-08
timeHH:MM or HH:MM:SS14:05, 14:05:09
date-timeYYYY-MM-DDTHH:MM or YYYY-MM-DDTHH:MM:SS, optionally followed by Z2026-10-08T14:05:09Z

Years are 1 to 9999, the date must exist in the calendar, hours are 0 to 23, and minutes and seconds are 0 to 59. Anything else is error 3105, at render time.

Z marks a UTC time. The functions on this page never convert between time zones: they keep the time as it is written, and only do the arithmetic or formatting asked for.

Render values

These are read from the render, not computed by a function:

NameTypeValue
render.nowtextThe instant the render starts, in UTC, as YYYY-MM-DDTHH:MM:SSZ. Given with --now on the command line
render.datetextThe date YYYY-MM-DD in the project's time zone (see below)
render.timetextThe time HH:MM:SS in the project's time zone

render.date and render.time are the local date and time: the UTC instant from render.now with the utc_offset added. render.now itself is always UTC. With --date alone on the command line, the time is 00:00:00 and no offset applies (see Command Line).

Time zone

A project can set its time zone as a fixed offset from UTC, in hours, in utc_offset in yoshida.json:

{
  "format": 1,
  "utc_offset": 2
}
  • The value is a number of hours from -14 to 14, and it may be fractional: 5.5 is 5 hours 30 minutes. The default is 0.
  • It applies to render.date and render.time only. render.now stays UTC.
  • It is a fixed offset. It does not follow daylight saving time, and named zones such as Europe/Berlin are not supported. A project for a zone with summer time sets 2 in summer and 1 in winter. See Known gaps.
  • yoshida render --utc-offset HOURS changes it for one run.

Formatting

date_fmt(value, pattern)

(text, text) -> text. Writes a date, a time or a date-time with a pattern of tokens. Other characters are copied as they are.

  • date_fmt('2026-10-08', 'D MMMM YYYY') is 8 October 2026.
  • date_fmt('2026-10-08', 'dddd D MMM') is Thursday 8 Oct.
  • date_fmt(render.time, 'HH:mm') is the time without seconds.
  • A text that is not a date, time or date-time is error 3105. A date token (such as YYYY) applied to a time-only text is also error 3105.
  • A date-only value reads as midnight for time tokens, so date_fmt('2026-10-08', 'HH:mm') is 00:00 and date_fmt('2026-10-08', 'h A') is 12 AM. H gives 0, hh and h give 12, A gives AM and a gives am.

Tokens (the pattern is shown with 8 October 2026, 14:05:09):

TokenOutputExample
YYYYyear, four digits2026
YYlast two digits of the year26
MMMMmonth nameOctober
MMMshort month nameOct
MMmonth, two digits10
Mmonth10 (1 in January)
DDday of the month, two digits08
Dday of the month8
ddddweekday nameThursday
dddshort weekday nameThu
HHhour, 00 to 2314
Hhour, 0 to 2314 (9 for 09:00)
hhhour on a 12-hour clock, 01 to 1202
hhour on a 12-hour clock, 1 to 122
AAM or PMPM
aam or pmpm
mmminute, two digits05
sssecond, two digits09

Notes on the tokens:

  • The longest token wins, so MMMM is tried before MMM and MM.
  • Tokens are case-sensitive: MM is the month and mm the minute. HH, H, hh and h are hours.
  • The single letters M, D, H, h, A and a are tokens, so they change any word they appear in. Put other words inside [...]: date_fmt(t, '[at] h A') gives at 2 PM, not pm.
  • Text inside square brackets is copied without the brackets, so date_fmt(d, '[Day] D') gives Day 8. Note that D inside the brackets is not a token.
  • A single m or s is not a token. Write mm or ss.
  • Only English month and weekday names are written. See Known gaps.

Parts of a date or time

year(value), month(value), day(value), weekday(value)

(text) -> number. The year; the month (1 to 12); the day of the month (1 to 31); and the weekday, from 1 for Monday to 7 for Sunday (ISO numbering).

  • weekday('2026-10-08') is 4 (a Thursday).
  • year(render.date) is the year of the render.
  • A time-only text is error 3105.

hour(value), minute(value)

(text) -> number. The hour (0 to 23) and the minute (0 to 59). A date-only text gives 0.

  • hour(render.time) is the hour of the render, in the project's time zone.

Arithmetic

add_days(value, n)

(text, number) -> text. Adds n days to a date or a date-time. n is floored. The result has the same form as the input: a date stays a date, and a date-time keeps its Z.

  • add_days('2026-10-08', 30) is 2026-11-07.
  • A time-only text is error 3105. So is a result outside years 1 to 9999.

Example: a date a fixed number of days from the card's release date, shown as text:

"text": "{date_fmt(add_days(release, 14), 'D MMMM YYYY')}"

days_between(a, b)

(text, text) -> number. The whole number of days from the date part of a to the date part of b: b - a. The result is negative when b is earlier.

  • days_between('2026-10-15', '2026-12-25') is 71.
  • days_between(render.date, release) counts the days until a release date.
  • A time-only text is error 3105.

add_hours(value, h)

(text, number) -> text. Adds h hours to a date or a date-time, and gives a date-time as YYYY-MM-DDTHH:MM:SS. A date counts as midnight. A fractional h is rounded to whole seconds. The Z of the input is kept.

  • add_hours('2026-10-08T22:00:00Z', 5) is 2026-10-09T03:00:00Z.
  • add_hours('2026-10-08', 5) is 2026-10-08T05:00:00.
  • A time-only text is error 3105. So is a result outside years 1 to 9999.

Example: the UTC time of the render shown in another zone. The offset is fixed, so this does not follow daylight saving time either:

"text": "Live at {date_fmt(render.now, 'HH:mm')} UTC, {date_fmt(add_hours(render.now, -5), 'HH:mm')} in New York"

render.now is always UTC, so this works whatever utc_offset is set to.

↑↓ to moveEnter to openEsc to close