Enum Datetime

pub enum Datetime {
    Date(Date),
    Time(Time),
    Datetime(PrimitiveDateTime),
}

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]"
)

Datetime and Duration

You can get a [duration] by subtracting two datetime:

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

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

#let date = datetime(day: 1, month: 3, year: 2024)
#let two-days = duration(days: 2)
#let two-days-earlier = date - two-days
#let two-days-later = date + two-days

#date.display() \
#two-days-earlier.display() \
#two-days-later.display()

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:

• year: Displays the year of the datetime.
  • padding: Can be either zero, space or none. Specifies how the year is padded.
  • repr Can be either full in which case the full year is displayed or last_two in which case only the last two digits are displayed.
  • sign: Can be either automatic or mandatory. Specifies when the sign should be displayed.
• month: Displays the month of the datetime.
  • padding: Can be either zero, space or none. Specifies how the month is padded.
  • repr: Can be either numerical, long or short. Specifies if the month should be displayed as a number or a word. Unfortunately, when choosing the word representation, it can currently only display the English version. In the future, it is planned to support localization.
• day: Displays the day of the datetime.
  • padding: Can be either zero, space or none. Specifies how the day is padded.
• week_number: Displays the week number of the datetime.
  • padding: Can be either zero, space or none. Specifies how the week number is padded.
  • repr: Can be either ISO, sunday or monday. In the case of ISO, week numbers are between 1 and 53, while the other ones are between 0 and 53.
• weekday: Displays the weekday of the date.
  • repr Can be either long, short, sunday or monday. In the case of long and short, the corresponding English name will be displayed (same as for the month, other languages are currently not supported). In the case of sunday and monday, the numerical value will be displayed (assuming Sunday and Monday as the first day of the week, respectively).
  • one_indexed: Can be either true or false. Defines whether the numerical representation of the week starts with 0 or 1.
• hour: Displays the hour of the date.
  • padding: Can be either zero, space or none. Specifies how the hour is padded.
  • repr: Can be either 24 or 12. Changes whether the hour is displayed in the 24-hour or 12-hour format.
• period: The AM/PM part of the hour
  • case: Can be lower to display it in lower case and upper to display it in upper case.
• minute: Displays the minute of the date.
  • padding: Can be either zero, space or none. Specifies how the minute is padded.
• second: Displays the second of the date.
  • padding: Can be either zero, space or none. Specifies how the second is padded.

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.

Variants

Date(Date)

Representation as a date.

Time(Time)

Representation as a time.

Datetime(PrimitiveDateTime)

Representation as a combination of date and time.

Implementations

impl Datetime

pub fn from_ymd(year: i32, month: u8, day: u8) -> Option<Self>

Create a datetime from year, month, and day.

pub fn from_hms(hour: u8, minute: u8, second: u8) -> Option<Self>

Create a datetime from hour, minute, and second.

pub fn from_ymd_hms( year: i32, month: u8, day: u8, hour: u8, minute: u8, second: u8, ) -> Option<Self>

Create a datetime from day and time.

pub fn from_toml_dict(dict: &Dict) -> Option<Self>

Try to parse a dictionary as a TOML date.

pub fn kind(&self) -> &'static str

Which kind of variant this datetime stores.

impl Datetime

pub fn construct( year: Option<i32>, month: Option<Month>, day: Option<u8>, hour: Option<u8>, minute: Option<u8>, second: Option<u8>, ) -> StrResult<Datetime>

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:

• If you specify year, month and day, Typst will store just a date.
• If you specify hour, minute and second, Typst will store just a time.
• If you specify all of year, month, day, hour, minute and second, Typst will store a full datetime.

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

#datetime(
  year: 2012,
  month: 8,
  day: 3,
).display()

pub fn today(engine: &mut Engine<'_>, offset: Smart<i64>) -> StrResult<Datetime>

Returns the current date.

Today's date is
#datetime.today().display().

pub fn display(&self, pattern: Smart<DisplayPattern>) -> StrResult<EcoString>

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.

pub fn year(&self) -> Option<i32>

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

pub fn month(&self) -> Option<u8>

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

pub fn weekday(&self) -> Option<u8>

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

pub fn day(&self) -> Option<u8>

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

pub fn hour(&self) -> Option<u8>

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

pub fn minute(&self) -> Option<u8>

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

pub fn second(&self) -> Option<u8>

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

pub fn ordinal(&self) -> Option<u16>

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

Trait Implementations

impl Add<Duration> for Datetime

type Output = Datetime

The resulting type after applying the + operator.

fn add(self, rhs: Duration) -> Self::Output

Performs the + operation.

impl Clone for Datetime

fn clone(&self) -> Datetime

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Datetime

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromValue for Datetime

fn from_value(value: Value) -> HintedStrResult<Self>

Try to cast the value into an instance of Self.

impl Hash for Datetime

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl IntoValue for Datetime

fn into_value(self) -> Value

Cast this type into a value.

impl NativeScope for Datetime

fn constructor() -> Option<&'static NativeFuncData>

The constructor function for the type, if any.

fn scope() -> Scope

Get the associated scope for the type.

impl NativeType for Datetime

const NAME: &'static str = "datetime"

The type’s name.

fn data() -> &'static NativeTypeData

fn ty() -> Type

Get the type for the native Rust type.

impl PartialEq for Datetime

fn eq(&self, other: &Datetime) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Datetime

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Reflect for Datetime

fn input() -> CastInfo

Describe what can be cast into this value.

fn output() -> CastInfo

Describe what this value can be cast into.

fn castable(value: &Value) -> bool

Whether the given value can be converted to T.

fn error(found: &Value) -> HintedString

Produce an error message for an unacceptable value type.

impl Repr for Datetime

fn repr(&self) -> EcoString

Return the debug representation of the value.

impl Sub<Duration> for Datetime

type Output = Datetime

The resulting type after applying the - operator.

fn sub(self, rhs: Duration) -> Self::Output

Performs the - operation.

impl Sub for Datetime

type Output = Result<Duration, EcoString>

The resulting type after applying the - operator.

fn sub(self, rhs: Self) -> Self::Output

Performs the - operation.

impl Copy for Datetime

impl StructuralPartialEq for Datetime