Back to Index
Overview
Using and changing time in Formulas is super useful. Say you want to get the net value of your "Banana Fund", between two dates. We need some way to specify the date range we are interested.
In addition to specifying the time, we sometimes want to specify times relative to other times, for example: "now" or "time a note was taken".
Say you want to know how much was put into the "Banana Fund" for the last week and you want those times to continue to refer to the last week in perpetuity.
For that we need a special time function that always refers to "now". Any formula can reference "now" and it's done like this:
$$()(time now)
Another useful relative time is the time of a note. It's also available in any formula:
$$()(time note)
It's easy to see the power of these functions in context:
$$()(bean
"Banana Fund"
-
-
(subtract-time (time now) weeks 1)
(time now))
The above note will always show the cash flow in the "Volcano Fund" for one week leading up to now.
We can change that so it's relative to the time the note was taken:
$$()(bean
"Banana Fund"
-
-
(subtract-time (time note) weeks 1)
(time note))
The only change is (time now) becomes (time note). The note above will always show the net value of the "Banana Fund" for one week prior to when the note was taken.
Reference
All time functions use GMT.
TIME
(TIME Type|ISO Date-time String)
Type: now, note or ISO Date-time String
Examples:
$$()(time note) The time of the current note
$$()(time now) The time of now (GMT)
$$()(time "2022-01-30") This time is assumed to be in your local time zone and will be converted to GMT
ADD-TIME
(ADD-TIME Time Unit Amount)
Adds an amount of a specific unit of time to a time
Time: Any valid time from the time function
Unit: years, quarters, months, weeks, days, hours, minutes, seconds
Amount: years, quarters, months, weeks, days, hours, minutes, seconds
Examples:
$$()(add-time (time now) days 7) 7 days after now
$$()(add-time (time note) years 1) 1 year after note
SUBTRACT-TIME
(SUBTRACT-TIME Time Unit Amount)
Subtracts an amount of a specific unit of time from a time
Time: Any valid time from the time function
Unit: years, quarters, months, weeks, days, hours, minutes, seconds
Amount: years, quarters, months, weeks, days, hours, minutes, seconds
Examples:
$$()(subtract-time (time now) days 7) 7 days before now
$$()(subtract-time (time note) years 1) 1 year before note
CHANGE-TIME
(CHANGE-TIME Time Change Unit)
Changes given time to the beginning or end of a specific time-unit. For example:
- change the time of a specific note to the beginning of the week
- change now to the beginning of the year, could be used to calculate YTD values
Time: Any valid time from the time function
Change: start-of, end-of
Unit: year, quarter, month, week, day, hour, minute, second
Examples:
$$()(change-time (time now) end-of day) last second of the current day
$$()(change-time (time note) start-of year) start of the year for the current note
DIFF-TIME
(DIFF-TIME Start-time End-time Unit)
Calculates the difference between two times by the specified unit, rounded to the nearest integer.
Start-time: Any valid time from the time function
End-time: Any valid time from the time function
Unit: years, quarters, months, weeks, days, hours, minutes, second
Example:
$$()(diff-time (time note) (time now) days) the difference between the time of a note and now