package core:time/datetime
Source

⌘K
Ctrl+K
or
/

    Types

    Date ¶
    Source

    Date :: struct {
	year:  i64,
	month: i8,
	day:   i8,
}
     

    A type representing a date.

    The minimum and maximum values for a year can be found in MIN_DATE and MAX_DATE constants. The month field can range from 1 to 12, and the day ranges from 1 to however many days there are in the specified month.

    Related Procedures With Parameters
    Related Procedures With Returns
    Related Constants

    DateTime ¶
    Source

    DateTime :: struct {
	using date: Date,
	using time: Time,
	tz:   ^TZ_Region,
}
     

    A type representing datetime.

    Related Procedures With Parameters
    Related Procedures With Returns
    Procedures Through `using` From Date
    Procedures Through `using` From Time

    Delta ¶
    Source

    Delta :: struct {
	days:    i64,
	seconds: i64,
	nanos:   i64,
}
     

    A type representing a difference between two instances of datetime.

    Note: All fields are i64 because we can also use it to add a number of seconds or nanos to a moment, that are then normalized within their respective ranges.

    Related Procedures With Parameters
    Related Procedures With Returns

    Error ¶
    Source

    Error :: enum int {
	None, 
	Invalid_Year, 
	Invalid_Month, 
	Invalid_Day, 
	Invalid_Hour, 
	Invalid_Minute, 
	Invalid_Second, 
	Invalid_Nano, 
	Invalid_Ordinal, 
	Invalid_Delta, 
}
     

    Possible errors returned by datetime functions.

    Related Procedures With Returns

    Month ¶
    Source

    Month :: enum i8 {
	January   = 1, 
	February, 
	March, 
	April, 
	May, 
	June, 
	July, 
	August, 
	September, 
	October, 
	November, 
	December, 
}
     

    Type representing one of the months.

    Ordinal ¶
    Source

    Ordinal :: i64
     

    Type representing a mononotic day number corresponding to a date.

    Ordinal 1 = Midnight Monday, January 1, 1 A.D. (Gregorian)
        |   Midnight Monday, January 3, 1 A.D. (Julian)

    Every other ordinal counts days forwards, starting from the above date.

    Related Procedures With Parameters
    Related Procedures With Returns

    TZ_Date_Kind ¶
    Source

    TZ_Date_Kind :: enum int {
	No_Leap, 
	Leap, 
	Month_Week_Day, 
}

    TZ_RRule ¶
    Source

    TZ_RRule :: struct {
	has_dst:    bool,
	std_name:   string,
	std_offset: i64,
	std_date:   TZ_Transition_Date,
	dst_name:   string,
	dst_offset: i64,
	dst_date:   TZ_Transition_Date,
}

    TZ_Record ¶
    Source

    TZ_Record :: struct {
	time:       i64,
	utc_offset: i64,
	shortname:  string,
	dst:        bool,
}

    TZ_Region ¶
    Source

    TZ_Region :: struct {
	name:       string,
	records:    []TZ_Record,
	shortnames: []string,
	rrule:      TZ_RRule,
}

    TZ_Transition_Date ¶
    Source

    TZ_Transition_Date :: struct {
	type:  TZ_Date_Kind,
	month: u8,
	week:  u8,
	day:   u16,
	time:  i64,
}

    Time ¶
    Source

    Time :: struct {
	hour:   i8,
	minute: i8,
	second: i8,
	nano:   i32,
}
     

    A type representing a time within a single day within a nanosecond precision.

    Related Procedures With Parameters
    Related Procedures With Returns

    Weekday ¶
    Source

    Weekday :: enum i8 {
	Sunday    = 0, 
	Monday, 
	Tuesday, 
	Wednesday, 
	Thursday, 
	Friday, 
	Saturday, 
}
     

    Type representing one of the weekdays.

    Related Procedures With Returns

    Constants

    MAX_DATE ¶
    Source

    MAX_DATE :: Date{year = 25_252_734_927_766_552, month = 12, day = 31}
     

    Maximum valid value for date

    The value is chosen such that a conversion date -> ordinal -> date is always safe.

    MAX_ORD ¶
    Source

    MAX_ORD: i64 : Ordinal(9_223_372_036_854_774_869)
     

    Maximum value for an ordinal

    MIN_DATE ¶
    Source

    MIN_DATE :: Date{year = -25_252_734_927_766_552, month = 1, day = 1}
     

    Minimum valid value for date.

    The value is chosen such that a conversion date -> ordinal -> date is always safe.

    MIN_ORD ¶
    Source

    MIN_ORD: i64 : Ordinal(-9_223_372_036_854_775_234)
     

    Minimum value for an ordinal

    Variables

    This section is empty.

    Procedures

    add_days_to_date ¶
    Source

    add_days_to_date :: proc "contextless" (a: Date, days: i64) -> (date: Date, err: Error) {…}
     

    Add certain amount of days to a date.

    This procedure adds the specified amount of days to a date and returns a new date. The new date would have happened the specified amount of days after the specified date.

    Related Procedure Groups

    add_delta_to_date ¶
    Source

    add_delta_to_date :: proc "contextless" (a: Date, delta: Delta) -> (date: Date, err: Error) {…}
     

    Add delta to a date.

    This procedure adds a delta to a date, and returns a new date. The new date would have happened the time specified by delta after the specified date.

    Note: The delta is assumed to be normalized. That is, if it contains seconds or milliseconds, regardless of the amount only the days will be added.

    Related Procedure Groups

    add_delta_to_datetime ¶
    Source

    add_delta_to_datetime :: proc "contextless" (a: DateTime, delta: Delta) -> (datetime: DateTime, err: Error) {…}
     

    Add delta to datetime.

    This procedure adds a delta to a datetime, and returns a new datetime. The new datetime would have happened the time specified by delta after the specified datetime.

    Related Procedure Groups

    components_to_date ¶
    Source

    components_to_date :: proc "contextless" (#any_int year, #any_int month, #any_int day: i64) -> (date: Date, err: Error) {…}
     

    Obtain a date from date components.

    This procedure converts date components, specified by a year, a month and a day, into a date object. If the provided date components don't represent a valid date, an error is returned.

    components_to_datetime ¶
    Source

    components_to_datetime :: proc "contextless" (
	#any_int year, #any_int month, #any_int day, #any_int hour, #any_int minute, #any_int second: i64, 
	#any_int nanos:                         i64 = i64(0), 
) -> (datetime: DateTime, err: Error) {…}
     

    Obtain datetime from components.

    This procedure converts date components and time components into a datetime object. If the provided date components or time components don't represent a valid datetime, an error is returned.

    components_to_ordinal ¶
    Source

    components_to_ordinal :: proc "contextless" (#any_int year, #any_int month, #any_int day: i64) -> (ordinal: i64, err: Error) {…}
     

    Obtain an ordinal from date components.

    This procedure converts the specified date, provided by its individual components, into an ordinal. If the specified date is not a valid date, an error is returned.

    components_to_time ¶
    Source

    components_to_time :: proc "contextless" (#any_int hour, #any_int minute, #any_int second: i64, #any_int nanos: i64 = i64(0)) -> (time: Time, err: Error) {…}
     

    Obtain time from time components.

    This procedure converts time components, specified by an hour, a minute, a second and nanoseconds, into a time object. If the provided time components don't represent a valid time, an error is returned.

    date_to_ordinal ¶
    Source

    date_to_ordinal :: proc "contextless" (date: Date) -> (ordinal: i64, err: Error) {…}
     

    Obtain an ordinal from a date.

    This procedure converts the specified date into an ordinal. If the specified date is not a valid date, an error is returned.

    day_number ¶
    Source

    day_number :: proc "contextless" (date: Date) -> (day_number: i64, err: Error) {…}
     

    Obtain the day number in a year

    This procedure returns the number of the day in a year, starting from 1. If the date is not a valid date, an error is returned.

    day_of_week ¶
    Source

    day_of_week :: proc "contextless" (ordinal: i64) -> (day: Weekday) {…}
     

    Calculate the weekday from an ordinal.

    This procedure takes the value of an ordinal and returns the day of week for that ordinal.

    days_remaining ¶
    Source

    days_remaining :: proc "contextless" (date: Date) -> (days_remaining: i64, err: Error) {…}
     

    Obtain the remaining number of days in a year.

    This procedure returns the number of days between the specified date and December 31 of the same year. If the date is not a valid date, an error is returned.

    is_leap_year ¶
    Source

    is_leap_year :: proc "contextless" (#any_int year: i64) -> (leap: bool) {…}
     

    Check if a year is a leap year.

    last_day_of_month ¶
    Source

    last_day_of_month :: proc "contextless" (#any_int year: i64, #any_int month: i8) -> (day: i8, err: Error) {…}
     

    Obtain the last day of a given month on a given year.

    This procedure returns the amount of days in a specified month on a specified date. If the specified year or month is not valid, an error is returned.

    new_year ¶
    Source

    new_year :: proc "contextless" (#any_int year: i64) -> (new_year: Date, err: Error) {…}
     

    Obtain the new year date of a given year.

    This procedure returns the January 1st date of the specified year. If the year is not valid, an error is returned.

    normalize_delta ¶
    Source

    normalize_delta :: proc "contextless" (delta: Delta) -> (normalized: Delta, err: Error) {…}
     

    Normalize the delta.

    This procedure normalizes the delta in such a way that the number of seconds is between 0 and the number of seconds in the day and nanoseconds is between 0 and 10^9.

    If the value for days overflows during this operation, an error is returned.

    ordinal_to_date ¶
    Source

    ordinal_to_date :: proc "contextless" (ordinal: i64) -> (date: Date, err: Error) {…}
     

    Obtain date using an Ordinal.

    This provedure converts the specified ordinal into a date. If the ordinal is not a valid ordinal, an error is returned.

    ordinal_to_datetime ¶
    Source

    ordinal_to_datetime :: proc "contextless" (ordinal: i64) -> (datetime: DateTime, err: Error) {…}
     

    Obtain an datetime from an ordinal.

    This procedure converts the value of an ordinal into a datetime. Since the ordinal only has the amount of days, the resulting time in the datetime object will always have the time equal to 00:00:00.000.

    subtract_dates ¶
    Source

    subtract_dates :: proc "contextless" (a, b: Date) -> (delta: Delta, err: Error) {…}
     

    Calculate the difference between two dates.

    This procedure calculates the difference between two dates a - b, and returns a delta between the two dates in days. If either a or b is not a valid date, an error is returned.

    Related Procedure Groups

    subtract_datetimes ¶
    Source

    subtract_datetimes :: proc "contextless" (a, b: DateTime) -> (delta: Delta, err: Error) {…}
     

    Calculate the difference between two datetimes.

    This procedure calculates the difference between two datetimes, a - b, and returns a delta between the two dates. The difference is returned in all three fields of the Delta struct: the difference in days, the difference in seconds and the difference in nanoseconds.

    If either a or b is not a valid datetime, an error is returned.

    Related Procedure Groups

    subtract_deltas ¶
    Source

    subtract_deltas :: proc "contextless" (a, b: Delta) -> (delta: Delta, err: Error) {…}
     

    Calculate a difference between two deltas.

    Related Procedure Groups

    unsafe_date_to_ordinal ¶
    Source

    unsafe_date_to_ordinal :: proc "contextless" (date: Date) -> (ordinal: i64) {…}
     

    Obtain an ordinal from a date.

    This procedure converts a date into an ordinal. If the date is not a valid date, the result is unspecified.

    unsafe_ordinal_to_date ¶
    Source

    unsafe_ordinal_to_date :: proc "contextless" (ordinal: i64) -> (date: Date) {…}
     

    Obtain a date from an ordinal.

    This procedure converts an ordinal into a date. If the ordinal is outside of its valid range, the result is unspecified.

    unsafe_ordinal_to_year ¶
    Source

    unsafe_ordinal_to_year :: proc "contextless" (ordinal: i64) -> (year: i64, day_ordinal: i64) {…}
     

    Obtain a year and a day of the year from an ordinal.

    This procedure returns the year and the day of the year of a given ordinal. Of the ordinal is outside of its valid range, the result is unspecified.

    validate_date ¶
    Source

    validate_date :: proc "contextless" (date: Date) -> (err: Error) {…}
     

    Check for errors in date formation.

    This procedure validates all fields of a date, and if any of the fields is outside of allowed range, an error is returned.

    Related Procedure Groups

    validate_datetime ¶
    Source

    validate_datetime :: proc "contextless" (datetime: DateTime) -> (err: Error) {…}
     

    Check for errors in datetime formation.

    This procedure checks whether all fields of date and time in the specified datetime are valid, and if not, an error is returned.

    Related Procedure Groups

    validate_hour_minute_second ¶
    Source

    validate_hour_minute_second :: proc "contextless" (#any_int hour, #any_int minute, #any_int second, #any_int nano: i64) -> (err: Error) {…}
     

    Check for errors in time formed by its components.

    This procedure checks whether the time formed by its components is valid, and if not an error is returned.

    Related Procedure Groups

    validate_ordinal ¶
    Source

    validate_ordinal :: proc "contextless" (ordinal: i64) -> (err: Error) {…}
     

    Check for errors in Ordinal

    This procedure checks if the ordinal is in a valid range for roundtrip conversions with the dates. If not, an error is returned.

    Related Procedure Groups

    validate_time ¶
    Source

    validate_time :: proc "contextless" (time: Time) -> (err: Error) {…}
     

    Check for errors in time formation

    This procedure checks whether time has all fields in valid ranges, and if not an error is returned.

    Related Procedure Groups

    validate_year_month_day ¶
    Source

    validate_year_month_day :: proc "contextless" (#any_int year, #any_int month, #any_int day: i64) -> (err: Error) {…}
     

    Check for errors in date formation given date components.

    This procedure checks whether a date formed by the specified year month and a day is a valid date. If not, an error is returned.

    Related Procedure Groups

    year_end ¶
    Source

    year_end :: proc "contextless" (#any_int year: i64) -> (year_end: Date, err: Error) {…}
     

    Obtain the end year of a given date.

    This procedure returns the December 31st date of the specified year. If the year is not valid, an error is returned.

    year_range ¶
    Source

    year_range :: proc(#any_int year: i64, allocator := context.allocator) -> (range: []Date) {…}
     

    Obtain the range of dates for a given year.

    This procedure returns dates, for every day of a given year in a slice.

    Procedure Groups

    add ¶
    Source

     

    Add days to a date, delta to a date or delta to datetime.

    sub ¶
    Source

     

    Calculate a difference between two datetimes, dates or deltas.

    validate ¶
    Source

     

    Check for errors in date, time or datetime.

    Source Files

    Generation Information

    Generated with odin version dev-2025-10 (vendor "odin") Windows_amd64 @ 2025-10-28 21:13:07.732545500 +0000 UTC