package core:time/datetime
Overview
Calendrical conversions using a proleptic Gregorian calendar.
Implemented using formulas from: Calendrical Calculations Ultimate Edition, Reingold & Dershowitz
Index
Variables (0)
This section is empty.
Procedures (31)
- add_days_to_date
- add_delta_to_date
- add_delta_to_datetime
- components_to_date
- components_to_datetime
- components_to_ordinal
- components_to_time
- date_to_ordinal
- day_number
- day_of_week
- days_remaining
- is_leap_year
- last_day_of_month
- new_year
- normalize_delta
- ordinal_to_date
- ordinal_to_datetime
- subtract_dates
- subtract_datetimes
- subtract_deltas
- unsafe_date_to_ordinal
- unsafe_ordinal_to_date
- unsafe_ordinal_to_year
- validate_date
- validate_datetime
- validate_hour_minute_second
- validate_ordinal
- validate_time
- validate_year_month_day
- year_end
- year_range
Types
Date ¶
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
- add_days_to_date
- add_delta_to_date
- date_to_ordinal
- day_number
- days_remaining
- subtract_dates
- unsafe_date_to_ordinal
- validate_date
- add (procedure groups)
- sub (procedure groups)
- validate (procedure groups)
Related Procedures With Returns
Related Constants
DateTime ¶
A type representing datetime.
Related Procedures With Parameters
- add_delta_to_datetime
- subtract_datetimes
- validate_datetime
- add (procedure groups)
- sub (procedure groups)
- validate (procedure groups)
Related Procedures With Returns
Procedures Through `using` From Date
- add_days_to_date
- add_delta_to_date
- date_to_ordinal
- day_number
- days_remaining
- subtract_dates
- unsafe_date_to_ordinal
- validate_date
Procedures Through `using` From Time
Delta ¶
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
- add_delta_to_date
- add_delta_to_datetime
- normalize_delta
- subtract_deltas
- add (procedure groups)
- sub (procedure groups)
Related Procedures With Returns
Error ¶
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
- add_days_to_date
- add_delta_to_date
- add_delta_to_datetime
- components_to_date
- components_to_datetime
- components_to_ordinal
- components_to_time
- date_to_ordinal
- day_number
- days_remaining
- last_day_of_month
- new_year
- normalize_delta
- ordinal_to_date
- ordinal_to_datetime
- subtract_dates
- subtract_datetimes
- subtract_deltas
- validate_date
- validate_datetime
- validate_hour_minute_second
- validate_ordinal
- validate_time
- validate_year_month_day
- year_end
- add (procedure groups)
- sub (procedure groups)
- validate (procedure groups)
Month ¶
Month :: enum i8 { January = 1, February, March, April, May, June, July, August, September, October, November, December, }
Type representing one of the months.
Ordinal ¶
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)
TZ_Date_Kind ¶
TZ_Date_Kind :: enum int { No_Leap, Leap, Month_Week_Day, }
TZ_RRule ¶
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_Transition_Date ¶
TZ_Transition_Date :: struct { type: TZ_Date_Kind, month: u8, week: u8, day: u16, time: i64, }
Time ¶
A type representing a time within a single day within a nanosecond precision.
Related Procedures With Parameters
- validate_time
- validate (procedure groups)
Related Procedures With Returns
Weekday ¶
Weekday :: enum i8 { Sunday = 0, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, }
Type representing one of the weekdays.
Related Procedures With Returns
Constants
MAX_DATE ¶
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.
MIN_DATE ¶
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.
Variables
This section is empty.
Procedures
add_days_to_date ¶
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.
add_delta_to_date ¶
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.
add_delta_to_datetime ¶
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.
components_to_date ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
Check if a year is a leap year.
last_day_of_month ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.
subtract_datetimes ¶
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.
subtract_deltas ¶
Calculate a difference between two deltas.
unsafe_date_to_ordinal ¶
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 ¶
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 ¶
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 ¶
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.
validate_datetime ¶
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.
validate_hour_minute_second ¶
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.
validate_ordinal ¶
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.
validate_time ¶
Check for errors in time formation
This procedure checks whether time has all fields in valid ranges, and if not an error is returned.
validate_year_month_day ¶
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.
year_end ¶
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 ¶
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 ¶
add :: proc{ add_days_to_date, add_delta_to_date, add_delta_to_datetime, }
Add days to a date, delta to a date or delta to datetime.
sub ¶
sub :: proc{ subtract_datetimes, subtract_dates, subtract_deltas, }
Calculate a difference between two datetimes, dates or deltas.
validate ¶
validate :: proc{ validate_date, validate_year_month_day, validate_ordinal, validate_hour_minute_second, validate_time, validate_datetime, }
Check for errors in date, time or datetime.
Source Files
Generation Information
Generated with odin version dev-2024-12 (vendor "odin") Windows_amd64 @ 2024-12-06 21:12:13.594877300 +0000 UTC