# Formula Time Functions

## 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 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
``````