Date & Time

Adama supports four date and time related types:

  • date for storing year, month, day
  • time for storing hour, minute
  • datetime for storing year, month, day, hour, minute, second, ms
  • timespan for storing a duration

Constants

TypeSyntaxExampleNotes
time@time $hr:$min@time 4:20Use military time for PM
date@date $year/$mo/$day@date 2023/10/31Must be valid
timespan@timespan $count $unit@timespan 30 minunits are sec, min, hr, day, week
datetime@datetime "$iso8601"@datetime "2023-04-24T17:57:19.802528800-05:00[America/Chicago]"ZonedDateTime.parse

Getting the current date/time

MethodDescriptionResult type
Time.today()Get the current datedate
Time.datetime()Get the current date and timedatetime
Time.time()Get the current time of daytime
Time.zone()Get the document's time zonestring
Time.setZone(string zone)Set the document's time zonebool
Time.now()Get the current time as a UNIX time stamplong

Time functions

MethodDescriptionResult type
Time.make(int hr, int min)make a timemaybe<time>
Time.extendWithinDay(time t, timespan s)add the timespan to the time clamping the result at midnighttime
Time.cyclicAdd(time t, timespan s)add the timespan to the time wraping around the clocktime
Time.toInt(time t)convert the time to an integerint
Time.overlaps(time a, time b, time c, time d)do the temporal ranges [a,b] and [c,d] overlapbool

Date functions

MethodDescriptionResult type
Date.make(int yr, int mo, int day)make a datemaybe<date>
Date.construct(date dy, time t, double sec, string zone)make a datetimemaybe<datetime>
Date.calendarViewOf(date d)Get the surrounding month for the given datelist<date>
Date.weekViewOf(date d)Get the surrounding week for the given datelist<date>
Date.neighborViewOf(date d, int days)Get the neighborhood for the given date inclusively starting $days in the past to $days into the futurelist<date>
Date.patternOf(bool m, bool tu, bool w, bool th, bool fr, bool sa, bool su)Convert the week pattern into an integer bitmaskint
Date.satisfiesWeeklyPattern(date d, int pattern)Does the given date align/match the patternbool
Date.inclusiveRange(date from, date to)Inclusively return a list of all dates starting at $from and ending on $tolist<date>
Date.inclusiveRangeSatisfiesWeeklyPattern(date from, date to, int pattern)Inclusively return a list of all dates starting at $from and ending on $to that align/match the patternlist<date>
Date.dayOfWeek(date d)Get the day of the week (1 = Monday, 7 = Sunday) as an integerint
Date.dayOfWeekEnglish(date d)Get the day of the week in englishstring
Date.monthNameEnglish(date d)Get the month in englishstring
Date.offsetMonth(date d, int m)Add/subtract the number of months from the given datedate
Date.offsetDay(date d, int days)Add/subtract the number of days from the given datedate
Date.periodYearsFractional(date from, date to)Get the number of years between two datesdouble
Date.periodMonths(date from, date to)Get the number of months between two datesint
Date.between(datetime from, datetime to)Get the time between two datetimestimespan
Date.format(date, string format, string lang)Format the date for the given format in the given language (time component is midnight at 0 seconds using UTC time zone)maybe<string>
Date.format(date, string format)Format the date for the given format using english (time component is midnight at 0 seconds using UTC time zone)maybe<string>

Timespan functions

MethodDescriptionResult type
TimeSpan.add(timespan a, timespan b)Add the two timespans together, also the + operator works for thistimespan
TimeSpan.multiply(timespan a, double v)Multiply the timespan by the given double, also the + operator works for thistimespan
TimeSpan.seconds(timespan a) or a.seconds()Return the timespan as secondsdouble
TimeSpan.minutes(timespan a) or a.seconds()Return the timespan as minutesdouble
TimeSpan.hours(timespan a) or a.seconds()Return the timespan as hoursdouble

DateTime functions

MethodDescriptionResult type
Date.future(datetime d, timespan t)Get the future datetime by the given timespandatetime
Date.past(datetime d, timespan t)Get the past datetime by the given timespandatetime
Date.date(datetime d)Convert the datetime to a date, throwing away the timedate
Date.time(datetime d)Convert the datetime to a time, throwing away the datetime
Date.adjustTimeZone(datetime d, String tz)Adjust the timezone if the timezone existsmaybe<datetime>
Date.format(datetime, string format, string lang)Format the datetime for the given format in the given languagemaybe<string>
Date.format(datetime, string format)Format the datetime for the given format using englishmaybe<string>
Date.withYear(datetime d, int year)Replace the yearmaybe<datetime>
Date.withMonth(datetime d, int month)Replace the monthmaybe<datetime>
Date.withDayOfMonth(datetime d, int day)Replace the day of the monthmaybe<datetime>
Date.withHour(datetime d, int hour)Replace the hourmaybe<datetime>
Date.withMinute(datetime d, int minute)Replace the minute the monthmaybe<datetime>
Date.withTime(datetime d, time t)Replace both the hour and minute and zero out seconds and millisecondsmaybe<datetime>
Date.truncateDay(datetime)Zero out the day, hour, minute, seconds, millisecondsdatetime
Date.truncateHour(datetime)Zero out the hour, minute, seconds, millisecondsdatetime
Date.truncateMinute(datetime)Zero out the minute, seconds, millisecondsdatetime
Date.truncateSeconds(datetime)Zero out the seconds, millisecondsdatetime
Date.truncateMilliseconds(datetime)Zero out the millisecondsdatetime