TypstDocumentation

datetime

Represents a date, a time, or a combination of both.

Can be created by either specifying a custom datetime using this type's constructor function or getting the current date with datetime.today.

Example

#let date = datetime(
  year: 2020,
  month: 10,
  day: 4,
)

#date.display() \
#date.display(
  "y:[year repr:last_two]"
)

#let time = datetime(
  hour: 18,
  minute: 2,
  second: 23,
)

#time.display() \
#time.display(
  "h:[hour repr:12][period]"
)
Preview

Format

You can specify a customized formatting using the display method. The format of a datetime is specified by providing components with a specified number of modifiers. A component represents a certain part of the datetime that you want to display, and with the help of modifiers you can define how you want to display that component. In order to display a component, you wrap the name of the component in square brackets (e.g. [year] will display the year). In order to add modifiers, you add a space after the component name followed by the name of the modifier, a colon and the value of the modifier (e.g. [month repr:short] will display the short representation of the month).

The possible combination of components and their respective modifiers is as follows:

Keep in mind that not always all components can be used. For example, if you create a new datetime with datetime(year: 2023, month: 10, day: 13), it will be stored as a plain date internally, meaning that you cannot use components such as hour or minute, which would only work on datetimes that have a specified time.

Constructor
Question mark

Creates a new datetime.

You can specify the datetime using a year, month, day, hour, minute, and second.

Note: Depending on which components of the datetime you specify, Typst will store it in one of the following three ways:

Depending on how it is stored, the display method will choose a different formatting by default.

datetime(
year: int,month: int,day: int,hour: int,minute: int,second: int,
) -> datetime
#datetime(
  year: 2012,
  month: 8,
  day: 3,
).display()
Preview

year
int

The year of the datetime.

month
int

The month of the datetime.

day
int

The day of the datetime.

hour
int

The hour of the datetime.

minute
int

The minute of the datetime.

second
int

The second of the datetime.

Definitions
Question mark

today

Returns the current date.

datetime.today(
offset: autoint
) -> datetime
Today's date is
#datetime.today().display().
Preview

offset
auto or int

An offset to apply to the current UTC date. If set to auto, the offset will be the local offset.

Default: auto

display

Displays the datetime in a specified format.

Depending on whether you have defined just a date, a time or both, the default format will be different. If you specified a date, it will be [year]-[month]-[day]. If you specified a time, it will be [hour]:[minute]:[second]. In the case of a datetime, it will be [year]-[month]-[day] [hour]:[minute]:[second].

See the format syntax for more information.

self.display(
autostr
) -> str

pattern
auto or str
Positional
Question mark

The format used to display the datetime.

Default: auto

year

The year if it was specified, or none for times without a date.

self.year(
) -> noneint

month

The month if it was specified, or none for times without a date.

self.month(
) -> noneint

weekday

The weekday (counting Monday as 1) or none for times without a date.

self.weekday(
) -> noneint

day

The day if it was specified, or none for times without a date.

self.day(
) -> noneint

hour

The hour if it was specified, or none for dates without a time.

self.hour(
) -> noneint

minute

The minute if it was specified, or none for dates without a time.

self.minute(
) -> noneint

second

The second if it was specified, or none for dates without a time.

self.second(
) -> noneint

ordinal

The ordinal (day of the year), or none for times without a date.

self.ordinal(
) -> noneint