Date & Time
Functions for creating, parsing, formatting, and manipulating dates and times.
date
1-parameter signature
date(time)
Use datetime::parse instead.
Parse parses a formatted string and returns DateTime object it represents.
- Parameters
timeStringString representation of DateTime.
- Returns
DateTimeParsed DateTime, preserving the parsed offset.
2-parameter signature
date(time, layout)
Use datetime::parse instead.
Parse parses a formatted string and returns DateTime object it represents.
- Parameters
timeStringString representation of DateTime.layoutStringGo time layout.
- Returns
DateTimeParsed DateTime, preserving the parsed offset.
date_add
3-parameter signature
date_add(date, amount, unit)
Use datetime::add instead.
Add adds an integer number of units to a date. Subday units are elapsed time;
calendar units use Go AddDate in the input's location, normalizing month ends
rather than clamping them. A calendar day can span 23 or 25 elapsed hours.
- Parameters
dateDateTimeSource date.amountIntNumber of units to add; may be negative.unitStringMillisecond, second, minute, hour, day, week, month, or year; plurals are accepted.
- Returns
DateTimeCalculated date, retaining the input's location.
date_compare
3-parameter signature
date_compare(left, right, start)
Use datetime::same for precision equality; it has different semantics from component ranges.
date_compare requires every component from start through millisecond to match.
The component order is year, month, week, day, hour, minute, second, millisecond.
Each input uses its own calendar; week includes the ISO week-year.
- Parameters
leftDateTimeFirst date.rightDateTimeSecond date.startStringCoarsest component in the inclusive range.
- Returns
BooleanWhether all selected components match.- Throws
InvalidArgumentThe unit is unknown.
4-parameter signature
date_compare(left, right, start, end)
Use datetime::same for precision equality; it has different semantics from component ranges.
date_compare requires every component in the inclusive start/end range to match.
The component order is year, month, week, day, hour, minute, second, millisecond.
Each input uses its own calendar; week includes the ISO week-year.
- Parameters
leftDateTimeFirst date.rightDateTimeSecond date.startStringCoarsest component in the inclusive range.endStringFinest component; must not be coarser than start.
- Returns
BooleanWhether all selected components match.- Throws
InvalidArgumentA unit is unknown or the range is reversed.
date_day
1-parameter signature
date_day(date)
Use datetime::day instead.
Day returns the day of date as a number.
- Parameters
dateDateTimeSource DateTime.
- Returns
IntA day number.
date_dayofweek
1-parameter signature
date_dayofweek(date)
Use datetime::day_of_week instead.
DayOfWeek returns number of the weekday from the date. Sunday is the 0th day of week.
- Parameters
dateDateTimeSource DateTime.
- Returns
IntNumber of the weekday.
date_dayofyear
1-parameter signature
date_dayofyear(date)
Use datetime::day_of_year instead.
DayOfYear returns the day of year number of date.
The return value range from 1 to 365 (366 in a leap year).
- Parameters
dateDateTimeSource DateTime.
- Returns
IntA day of year number.
date_days_in_month
1-parameter signature
date_days_in_month(date)
Use datetime::days_in_month instead.
DaysInMonth returns the number of days in the input's local calendar month.
- Parameters
dateDateTimeSource date.
- Returns
IntNumber of calendar days in the month, including leap days.
date_diff
3-parameter signature
date_diff(left, right, unit)
Use datetime::diff instead; it always returns a Float.
date_diff returns signed whole elapsed units for right - left, truncated toward zero.
- Parameters
leftDateTimeStarting instant.rightDateTimeEnding instant.unitStringMillisecond, second, minute, or hour; plurals are accepted. Calendar units are rejected.
- Returns
IntSigned whole elapsed units.- Throws
InvalidArgumentThe unit is unknown or is a calendar unit.RangeErrorThe elapsed interval cannot fit a runtime Duration.
4-parameter signature
date_diff(left, right, unit, asFloat)
Use datetime::diff instead; it always returns a Float without an asFloat flag.
date_diff returns signed elapsed units for right - left, optionally fractional.
- Parameters
leftDateTimeStarting instant.rightDateTimeEnding instant.unitStringMillisecond, second, minute, or hour; plurals are accepted. Calendar units are rejected.asFloatBooleanTrue returns fractional units; false truncates toward zero.
- Returns
Int | FloatSigned elapsed units.- Throws
InvalidArgumentThe unit is unknown or is a calendar unit.RangeErrorThe elapsed interval cannot fit a runtime Duration.
date_format
2-parameter signature
date_format(date, format)
Use datetime::format instead.
Format renders a DateTime using a Go time layout.
- Parameters
dateDateTimeSource DateTime object.formatStringGo time layout.
- Returns
StringFormatted date.
date_hour
1-parameter signature
date_hour(date)
Use datetime::hour instead.
Hour returns the hour of date as a number.
- Parameters
dateDateTimeSource DateTime.
- Returns
IntAn hour number.
date_leapyear
1-parameter signature
date_leapyear(date)
Use datetime::is_leap_year instead.
IsLeapYear returns true if date is in a leap year else false.
- Parameters
dateDateTimeSource DateTime.
- Returns
BooleanWhether the date is in a leap year.
date_millisecond
1-parameter signature
date_millisecond(date)
Use datetime::millisecond instead.
Millisecond returns the millisecond of date as a number.
- Parameters
dateDateTimeSource DateTime.
- Returns
IntA millisecond number.
date_minute
1-parameter signature
date_minute(date)
Use datetime::minute instead.
Minute returns the minute of date as a number.
- Parameters
dateDateTimeSource DateTime.
- Returns
IntA minute number.
date_month
1-parameter signature
date_month(date)
Use datetime::month instead.
Month returns the month of date as a number.
- Parameters
dateDateTimeSource DateTime.
- Returns
IntA month number.
date_quarter
1-parameter signature
date_quarter(date)
Use datetime::quarter instead.
Quarter returns which quarter date belongs to.
- Parameters
dateDateTimeSource DateTime.
- Returns
IntA quarter number.
date_second
1-parameter signature
date_second(date)
Use datetime::second instead.
Second returns the second of date as a number.
- Parameters
dateDateTimeSource DateTime.
- Returns
IntA second number.
date_subtract
3-parameter signature
date_subtract(date, amount, unit)
Use datetime::subtract instead.
Subtract subtracts an integer number of units from a date. Subday units are
elapsed time; calendar units use Go AddDate in the input's location, normalizing
month ends rather than clamping them. A calendar day can span 23 or 25 hours.
- Parameters
dateDateTimeSource date.amountIntNumber of units to subtract; may be negative.unitStringMillisecond, second, minute, hour, day, week, month, or year; plurals are accepted.
- Returns
DateTimeCalculated date, retaining the input's location.
date_year
1-parameter signature
date_year(date)
Use datetime::year instead.
Year returns the year extracted from the given date.
- Parameters
dateDateTimeSource DateTime.
- Returns
IntA year number.
now
0-parameter signature
now()
Use datetime::now instead.
Now returns new DateTime object with Time equal to time.Now().
- Parameters
- None
- Returns
DateTimeNew DateTime object.
datetime::add
3-parameter signature
datetime::add(date, amount, unit)
Add adds an integer number of units to a date. Subday units are elapsed time;
calendar units use Go AddDate in the input's location, normalizing month ends
rather than clamping them. A calendar day can span 23 or 25 elapsed hours.
- Parameters
dateDateTimeSource date.amountIntNumber of units to add; may be negative.unitStringMillisecond, second, minute, hour, day, week, month, or year; plurals are accepted.
- Returns
DateTimeCalculated date, retaining the input's location.
datetime::day
1-parameter signature
datetime::day(date)
Day returns the day of date as a number.
- Parameters
dateDateTimeSource DateTime.
- Returns
IntA day number.
datetime::day_of_week
1-parameter signature
datetime::day_of_week(date)
DayOfWeek returns number of the weekday from the date. Sunday is the 0th day of week.
- Parameters
dateDateTimeSource DateTime.
- Returns
IntNumber of the weekday.
datetime::day_of_year
1-parameter signature
datetime::day_of_year(date)
DayOfYear returns the day of year number of date.
The return value range from 1 to 365 (366 in a leap year).
- Parameters
dateDateTimeSource DateTime.
- Returns
IntA day of year number.
datetime::days_in_month
1-parameter signature
datetime::days_in_month(date)
DaysInMonth returns the number of days in the input's local calendar month.
- Parameters
dateDateTimeSource date.
- Returns
IntNumber of calendar days in the month, including leap days.
datetime::diff
3-parameter signature
datetime::diff(left, right, unit)
Diff returns the signed elapsed difference right - left in fixed units.
It uses checked runtime subtraction, limited to Duration's roughly 292-year range.
- Parameters
leftDateTimeStarting instant.rightDateTimeEnding instant.unitStringMillisecond, second, minute, or hour; plurals are accepted. Calendar units are rejected.
- Returns
FloatSigned fractional elapsed units; reversing arguments reverses the sign.- Throws
TypeErrorAn argument has an invalid type.InvalidArgumentThe unit is unknown or is a calendar unit.RangeErrorThe elapsed interval cannot fit a runtime Duration.
datetime::format
2-parameter signature
datetime::format(date, format)
Format renders a DateTime using a Go time layout.
- Parameters
dateDateTimeSource DateTime object.formatStringGo time layout.
- Returns
StringFormatted date.
datetime::hour
1-parameter signature
datetime::hour(date)
Hour returns the hour of date as a number.
- Parameters
dateDateTimeSource DateTime.
- Returns
IntAn hour number.
datetime::is_leap_year
1-parameter signature
datetime::is_leap_year(date)
IsLeapYear returns true if date is in a leap year else false.
- Parameters
dateDateTimeSource DateTime.
- Returns
BooleanWhether the date is in a leap year.
datetime::millisecond
1-parameter signature
datetime::millisecond(date)
Millisecond returns the millisecond of date as a number.
- Parameters
dateDateTimeSource DateTime.
- Returns
IntA millisecond number.
datetime::minute
1-parameter signature
datetime::minute(date)
Minute returns the minute of date as a number.
- Parameters
dateDateTimeSource DateTime.
- Returns
IntA minute number.
datetime::month
1-parameter signature
datetime::month(date)
Month returns the month of date as a number.
- Parameters
dateDateTimeSource DateTime.
- Returns
IntA month number.
datetime::now
0-parameter signature
datetime::now()
Now returns new DateTime object with Time equal to time.Now().
- Parameters
- None
- Returns
DateTimeNew DateTime object.
datetime::parse
1-parameter signature
datetime::parse(time)
parse reads an RFC3339 datetime String.
- Parameters
timeStringString representation of DateTime.
- Returns
DateTimeParsed DateTime, preserving the parsed offset.
2-parameter signature
datetime::parse(time, layout)
parse reads a datetime String using the supplied Go time layout.
- Parameters
timeStringString representation of DateTime.layoutStringGo time layout.
- Returns
DateTimeParsed DateTime, preserving the parsed offset.
datetime::quarter
1-parameter signature
datetime::quarter(date)
Quarter returns which quarter date belongs to.
- Parameters
dateDateTimeSource DateTime.
- Returns
IntA quarter number.
datetime::same
3-parameter signature
datetime::same(left, right, unit)
Same compares each input's own local calendar through the requested precision.
Offset and location identity are ignored. Week compares ISO week-year and week
number; other units require all enclosing calendar fields to match.
- Parameters
leftDateTimeFirst date.rightDateTimeSecond date.unitStringPrecision: year, month, week, day, hour, minute, second, or millisecond; plurals are accepted.
- Returns
BooleanWhether the local calendar values match through that precision.- Throws
TypeErrorAn argument has an invalid type.InvalidArgumentThe unit is unknown.
datetime::second
1-parameter signature
datetime::second(date)
Second returns the second of date as a number.
- Parameters
dateDateTimeSource DateTime.
- Returns
IntA second number.
datetime::subtract
3-parameter signature
datetime::subtract(date, amount, unit)
Subtract subtracts an integer number of units from a date. Subday units are
elapsed time; calendar units use Go AddDate in the input's location, normalizing
month ends rather than clamping them. A calendar day can span 23 or 25 hours.
- Parameters
dateDateTimeSource date.amountIntNumber of units to subtract; may be negative.unitStringMillisecond, second, minute, hour, day, week, month, or year; plurals are accepted.
- Returns
DateTimeCalculated date, retaining the input's location.
datetime::year
1-parameter signature
datetime::year(date)
Year returns the year extracted from the given date.
- Parameters
dateDateTimeSource DateTime.
- Returns
IntA year number.