{"route":"/en-US-v0.14.1/reference/foundations/datetime/","title":"Datetime","description":"Documentation for the Datetime type.","part":null,"outline":[{"id":"summary","name":"Summary","children":[]},{"id":"example","name":"Example","children":[]},{"id":"datetime-and-duration","name":"Datetime and Duration","children":[]},{"id":"format","name":"Format","children":[]},{"id":"constructor","name":"Constructor","children":[{"id":"constructor-year","name":"year","children":[]},{"id":"constructor-month","name":"month","children":[]},{"id":"constructor-day","name":"day","children":[]},{"id":"constructor-hour","name":"hour","children":[]},{"id":"constructor-minute","name":"minute","children":[]},{"id":"constructor-second","name":"second","children":[]}]},{"id":"definitions","name":"Definitions","children":[{"id":"definitions-today","name":"Today","children":[{"id":"definitions-today-offset","name":"offset","children":[]}]},{"id":"definitions-display","name":"Display","children":[{"id":"definitions-display-pattern","name":"pattern","children":[]}]},{"id":"definitions-year","name":"Year","children":[]},{"id":"definitions-month","name":"Month","children":[]},{"id":"definitions-weekday","name":"Weekday","children":[]},{"id":"definitions-day","name":"Day","children":[]},{"id":"definitions-hour","name":"Hour","children":[]},{"id":"definitions-minute","name":"Minute","children":[]},{"id":"definitions-second","name":"Second","children":[]},{"id":"definitions-ordinal","name":"Ordinal","children":[]}]}],"body":{"kind":"type","content":{"name":"datetime","title":"Datetime","keywords":[],"oneliner":"Represents a date, a time, or a combination of both.","details":"

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

\n

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

\n

Example

\n
#let date = datetime(\n  year: 2020,\n  month: 10,\n  day: 4,\n)\n\n#date.display() \\\n#date.display(\n  "y:[year repr:last_two]"\n)\n\n#let time = datetime(\n  hour: 18,\n  minute: 2,\n  second: 23,\n)\n\n#time.display() \\\n#time.display(\n  "h:[hour repr:12][period]"\n)\n
\"Preview\"
\n

Datetime and Duration

\n

You can get a duration by subtracting two datetime:

\n
#let first-of-march = datetime(day: 1, month: 3, year: 2024)\n#let first-of-jan = datetime(day: 1, month: 1, year: 2024)\n#let distance = first-of-march - first-of-jan\n#distance.hours()\n
\"Preview\"
\n

You can also add/subtract a datetime and a duration to retrieve a new,\noffset datetime:

\n
#let date = datetime(day: 1, month: 3, year: 2024)\n#let two-days = duration(days: 2)\n#let two-days-earlier = date - two-days\n#let two-days-later = date + two-days\n\n#date.display() \\\n#two-days-earlier.display() \\\n#two-days-later.display()\n
\"Preview\"
\n

Format

\n

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

\n

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

\n\n

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

","constructor":{"path":[],"name":"datetime","title":"Construct","keywords":[],"oneliner":"Creates a new datetime.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

Creates a new datetime.

\n

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

\n

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

\n\n

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

"},{"kind":"example","content":{"body":"
#datetime(\n  year: 2012,\n  month: 8,\n  day: 3,\n).display()\n
\"Preview\"
","title":null}}],"self":false,"params":[{"name":"year","details":[{"kind":"html","content":"

The year of the datetime.

"}],"types":["int"],"strings":[],"default":null,"positional":false,"named":true,"required":false,"variadic":false,"settable":false},{"name":"month","details":[{"kind":"html","content":"

The month of the datetime.

"}],"types":["int"],"strings":[],"default":null,"positional":false,"named":true,"required":false,"variadic":false,"settable":false},{"name":"day","details":[{"kind":"html","content":"

The day of the datetime.

"}],"types":["int"],"strings":[],"default":null,"positional":false,"named":true,"required":false,"variadic":false,"settable":false},{"name":"hour","details":[{"kind":"html","content":"

The hour of the datetime.

"}],"types":["int"],"strings":[],"default":null,"positional":false,"named":true,"required":false,"variadic":false,"settable":false},{"name":"minute","details":[{"kind":"html","content":"

The minute of the datetime.

"}],"types":["int"],"strings":[],"default":null,"positional":false,"named":true,"required":false,"variadic":false,"settable":false},{"name":"second","details":[{"kind":"html","content":"

The second of the datetime.

"}],"types":["int"],"strings":[],"default":null,"positional":false,"named":true,"required":false,"variadic":false,"settable":false}],"returns":["datetime"],"scope":[]},"scope":[{"path":["datetime"],"name":"today","title":"Today","keywords":[],"oneliner":"Returns the current date.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

Returns the current date.

\n

In the CLI, this can be overridden with the --creation-timestamp\nargument or by setting the\nSOURCE_DATE_EPOCH\nenvironment variable. In both cases, the value should be given as a UNIX\ntimestamp.

"},{"kind":"example","content":{"body":"
Today's date is\n#datetime.today().display().\n
\"Preview\"
","title":null}}],"self":false,"params":[{"name":"offset","details":[{"kind":"html","content":"

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

"}],"types":["auto","int"],"strings":[],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":false}],"returns":["datetime"],"scope":[]},{"path":["datetime"],"name":"display","title":"Display","keywords":[],"oneliner":"Displays the datetime in a specified format.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

Displays the datetime in a specified format.

\n

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

\n

See the format syntax for more information.

"}],"self":true,"params":[{"name":"pattern","details":[{"kind":"html","content":"

The format used to display the datetime.

"}],"types":["auto","str"],"strings":[],"default":"auto","positional":true,"named":false,"required":false,"variadic":false,"settable":false}],"returns":["str"],"scope":[]},{"path":["datetime"],"name":"year","title":"Year","keywords":[],"oneliner":"The year if it was specified, or `{none}` for times without a date.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

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

"}],"self":true,"params":[],"returns":["none","int"],"scope":[]},{"path":["datetime"],"name":"month","title":"Month","keywords":[],"oneliner":"The month if it was specified, or `{none}` for times without a date.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

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

"}],"self":true,"params":[],"returns":["none","int"],"scope":[]},{"path":["datetime"],"name":"weekday","title":"Weekday","keywords":[],"oneliner":"The weekday (counting Monday as 1) or `{none}` for times without a date.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

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

"}],"self":true,"params":[],"returns":["none","int"],"scope":[]},{"path":["datetime"],"name":"day","title":"Day","keywords":[],"oneliner":"The day if it was specified, or `{none}` for times without a date.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

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

"}],"self":true,"params":[],"returns":["none","int"],"scope":[]},{"path":["datetime"],"name":"hour","title":"Hour","keywords":[],"oneliner":"The hour if it was specified, or `{none}` for dates without a time.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

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

"}],"self":true,"params":[],"returns":["none","int"],"scope":[]},{"path":["datetime"],"name":"minute","title":"Minute","keywords":[],"oneliner":"The minute if it was specified, or `{none}` for dates without a time.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

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

"}],"self":true,"params":[],"returns":["none","int"],"scope":[]},{"path":["datetime"],"name":"second","title":"Second","keywords":[],"oneliner":"The second if it was specified, or `{none}` for dates without a time.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

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

"}],"self":true,"params":[],"returns":["none","int"],"scope":[]},{"path":["datetime"],"name":"ordinal","title":"Ordinal","keywords":[],"oneliner":"The ordinal (day of the year), or `{none}` for times without a date.","element":false,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"

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

"}],"self":true,"params":[],"returns":["none","int"],"scope":[]}]}}}