Finding that I wasn't very familiar with KM date calculations and date formatting, I sketched some draft notes and examples.
(For initial simplicity, I have kept to the Unix Epoch Seconds functions, and left the Julian Day functions aside, though they are clearly indispensable for historians, and convenient for quick counts of days between two dates )
Here are some rough draft notes (now incorporating several edits and fixes suggested by Peter) on:
- Anchor date-times ( absolute calendar dates, now, and system events like start-of-session or macro launch)
- Offsets (relative date-times constructed as anchor + Interval, or the time elapsed between two dates), and
- Translations (rewriting Unix seconds as formatted date-times, converting between Unix and Julian, etc)
Working with dates and times in KM
Date-time Anchors
Now
-
NOW()
// () → intEpochSeconds %Calculate%NOW()% → 1440348448 -
(or) TIME()
// () → intGMTEpochSeconds %Calculate%TIME% → 1440405739
Calendar
-
TIME(intYear, intMonth, intDay)
// intYear → intMonth → intDay → intGMTEpochSeconds %Calculate%TIME(2015, 8, 23)% → 1440288000 -
TIME(intYear, intMonth, intDay, intHours, intMins, intSeconds)
// intYear → intMonth → intDay → // intHours → intMins → intSeconds → intGMTEpochSeconds %Calculate%TIME(2015, 8, 23, 18, 44, 0)% → 1440355440
System events
-
system start
-
SECONDS()
// () → floatSeconds %Calculate%SECONDS()% → 96789.996928 -
MILLISECONDS()
// () → floatMilliSeconds %Calculate%MILLISECONDS()% → 97488480.361 -
MICROSECONDS()
// () → intMicroSeconds %Calculate%MICROSECONDS()% → 97500344233
-
-
macro triggered
-
TRIGGERTIME()
// () → floatEpochSeconds %Calculate%TRIGGERTIME()% → 1440349785.37247396
-
-
last user input
-
IDLE()
// () → floatSeconds %Calculate%IDLE()% → 0.28027293
-
Date-time Offsets
(Date-time + interval) → new date-time
-
Relative to NOW()
-
Recognised interval strings
Seconds Minutes Hours Days Weeks Months Years -
Examples
-
tomorrow
%ICUDateTimePlus%1%Days%EEE, MMM d, yyyy% -
this coming thursday
%ICUDateTimePlus%(7+5-DOW(NOW)) MOD 7%Days%EEE, MMM d, yyyy%
Note: DOW(intEpochSeconds) → intDayOfWeek [1=Sunday] -
beginning of next month
%ICUDateTimeFor%TIME(YEAR(), MONTH()+1, 1)%EEE, MMM d, yyyy%
-
-
-
Relative to some other anchor date
-
two weeks before Sep 28 2015
%ICUDateTimeFor%TIME(2015, 9, 28-14)%EEE, MMM d, yyyy% -
Week 20 of 2016
%ICUDateTimeFor%TIME(2016, 1, 1+19*7)%EEE, MMM d, yyyy% -
Six weeks after Apr 20 2016
%ICUDateTimeFor%TIME(2016, 4, 20+6*7)%EEE, MMM d, yyyy%
-
Difference between two date-times
-
hours left till midnight
%Calculate%(TIME(YEAR(), MONTH(), DAY()+1, 0, 0, 0) - NOW() - GMTOFFSET())/3600% -
days between Jan 10 and March 15 2016
%Calculate%(TIME(2016, 3, 15) - TIME(2016, 1, 10))/(24 * 3600)% -
remaining weeks this year
%Calculate%FLOOR((TIME(YEAR(), 12, 31) - NOW()) / (7 * 24 * 3600))%
Translations
date → string
// intUnixEpochSeconds → string
%ICUDateTimeFor% 1483142400 %EEE, MMM d, yyyy%
// Note, the epoch seconds returned by TIME() are GMT,
// so pinning a day down by midday (rather than midnight) may be prudent
// ( allowing a margin for variations in time zones )
// intYear → intMonth → intDay → intHour, intMins, intSeconds, string
%ICUDateTimeFor% TIME(2015, 8, 23,12,0,0) %EEE, MMM d, yyyy%
GMT → local time
// () → intDifferenceInSeconds
%Calculate%GMTOFFSET()% → 3600
Unix epoch seconds ⇄ Julian days
// intUnixEpochSeconds → floatJulianDays
%Calculate%TIME2JD( 1483142400 )% → 2457753.5
// floatJulianDays → intUnixEpochSeconds
%Calculate%JD2TIME( 2457753.5 )% → 1483142400
