Differences

This shows you the differences between two versions of the page.

--- token:ICUDateTime [2020/05/28 21:16] – [Using Variables with These Date/Time Tokens] Clarify use of Parameters JMichaelTX
+++ token:ICUDateTime [2026/08/20 00:44] (current) – [Using Plus 0 or 1 With Day of Week (v8+)] Clarified sentence to specify context (reader doesn't have to scroll back to section title) August
@@ Line 3: / Line 3: @@
 The //%ICUDateTime%//, //%ICUDateTimePlus%//, //%ICUDateTimeMinus%// and //%ICUDateTimeFor%// tokens return the a date formatted in a specific format.  More details are provided in the [[:Dates_and_Times|Dates and Times]] article.
-===== Fields & Format Used by These Tokens =====
+===== Required Parameters for ICUDateTime Tokens =====
+The parameters are specified between `%` signs after the main ICDDateTime token.
-* //%ICUDateTime%**format**%// - the current date and time.
+* %**ICUDateTime**%*[output date format]*%
-* //%ICUDateTimeFor%NOW()+20%**format**%// - the specified [[:unixtime]] date.
+  * Returns the current date and time in the specified format.
-* //%ICUDateTimePlus%3+6%Hours%**format**%// - the current time plus a specified number of the specified time units.
+  * Example: ''%ICUDateTime%EEE, MMM d, yyyy h:mm%'' ⇢ //Mon, Jan 2, 2023 11:17//
-* //%ICUDateTimeMinus%3+6%Hours%**format**%// - the current time minus a specified number of the specified time units.
-===== Time Units =====
+* %**ICUDateTimeFor**%*[unixtime]*%*[output date format]*%
+  * Returns Date/Time specified by the [[:unixtime]], in the user's local time zone.
+* %**ICUDateTimePlus**%*[amount of time]*%*[unit of time]*%*[output date format]*%
+  * Returns Date/Time calculated by the Current Date/Time **plus** the *[amount of time]*.
+* %**ICUDateTimeMinus**%*[amount of time]*%*[unit of time]*%*[output date format]*%
+  * Returns Date/Time calculated by the Current Date/Time **minus** the *[amount of time]*.
-The available time units for //%ICUDateTimePlus%// and //%ICUDateTimeMinus%// are:
+where:
+  * *[output date format]* must conform to the [ICU Date/Time codes](https://www.keyboardmaestro.com/action/linkthru?icudatetimereference).
+  * *[unixtime]* is the total number of seconds since the start of 1970, GMT (see [[:unixtime]]).
+  * *[unit of time]* is a unit as described below.
+  * *[amount of time]* is a calculation, being the number of *[unit of time]* units to add or subtract.
+===== Unit of Time =====
+The available time units that can be added or subtracted with //%ICUDateTimePlus%// and //%ICUDateTimeMinus%// are:
 * Seconds
@@ Line 48: / Line 62: @@
 | %ICUDateTimePlus%0%Tuesdays%EEE, MMM d, yyyy% \\ %ICUDateTimePlus%1%Tuesdays%EEE, MMM d, yyyy% \\ %ICUDateTimePlus%2%Tuesdays%EEE, MMM d, yyyy% \\ %ICUDateTimePlus%0%Wednesdays%EEE, MMM d, yyyy% \\ %ICUDateTimePlus%1%Wednesdays%EEE, MMM d, yyyy% \\ %ICUDateTimePlus%2%Wednesdays%EEE, MMM d, yyyy% \\ %ICUDateTimePlus%0%Mondays%EEE, MMM d, yyyy% \\ %ICUDateTimePlus%1%Mondays%EEE, MMM d, yyyy% \\ %ICUDateTimePlus%2%Mondays%EEE, MMM d, yyyy% \\ %ICUDateTimeMinus%0%Tuesdays%EEE, MMM d, yyyy% \\ %ICUDateTimeMinus%1%Tuesdays%EEE, MMM d, yyyy% \\ %ICUDateTimeMinus%2%Tuesdays%EEE, MMM d, yyyy% \\ %ICUDateTimeMinus%0%Wednesdays%EEE, MMM d, yyyy% \\ %ICUDateTimeMinus%1%Wednesdays%EEE, MMM d, yyyy% \\ %ICUDateTimeMinus%2%Wednesdays%EEE, MMM d, yyyy% \\ %ICUDateTimeMinus%0%Mondays%EEE, MMM d, yyyy% \\ %ICUDateTimeMinus%1%Mondays%EEE, MMM d, yyyy% \\ %ICUDateTimeMinus%2%Mondays%EEE, MMM d, yyyy% | Tue, Sep 5, 2017 \\ Tue, Sep 12, 2017 \\ Tue, Sep 19, 2017 \\ Wed, Sep 6, 2017 \\ Wed, Sep 6, 2017 \\ Wed, Sep 13, 2017 \\ Mon, Sep 11, 2017 \\ Mon, Sep 11, 2017 \\ Mon, Sep 18, 2017 \\ Tue, Sep 5, 2017 \\ Tue, Aug 29, 2017 \\ Tue, Aug 22, 2017 \\ Wed, Aug 30, 2017 \\ Wed, Aug 30, 2017 \\ Wed, Aug 23, 2017 \\ Mon, Sep 4, 2017 \\ Mon, Sep 4, 2017 \\ Mon, Aug 28, 2017 |
-Note how Plus 0 and Plus 1 are the same unless today is the same as the weekday.  Also note that Plus 0 and Minus 0 is not the same (except when today is the same as the weekday).
+Note how Plus 0 and Plus 1 //weekday// are the same unless today is the same as the //weekday//.  Also note that Plus 0 and Minus 0 //weekday// is not the same (except when today is the same as the //weekday//).
 ===== Format Specification =====
@@ Line 54: / Line 68: @@
 The **format** is a specified with an [ICU Date Time Format Specifier](http://www.stairways.com/action/linkthru?icudatetimereference) which allows you to produce the date in almost any format you desire.
-Keep in mind that TIME is in GMT and the output of ICUDateTimeFor is in local time, so when doing this sort of thing it is best to use midday instead of midnight:
+You can use the *Insert ICU Date Field* menu in the *Edit* menu to insert various ICU Date Field format tokens. The *Insert ICU Date Field by Name…* menu item may be particularly helpful to quickly insert field components.
+Keep in mind that [[:unixtime]] is in GMT and the output of ICUDateTimeFor is in local time, so when doing this sort of thing it is best to use midday instead of midnight:
 ```
@@ Line 64: / Line 80: @@
 ===== Using Variables with These Date/Time Tokens =====
-You can use a number, Variable, and formula using Variables, in the _numeric_ parameters, like the amount of time in the  ICUDateTimePlus token, which has this format: \\
+You can use any [[manual:Calculations|calculation]] in the _numeric_ parameters, like the *[amount of time]* and *[unit of time]* fields.
-%**ICUDateTimePlus**%<color blue><amount of time></color>%<color #22b14c>[unit of time]</color>%<color #22b14c>[output date format]</color>%
-where \\
-  * angle brackets <color blue>< ></color> denote a numeric parameter, may use a Variable and/or formula
-  * square brackets <color #22b14c>[ ]</color> denote a text-only parameter, cannot use a Variable
 The _text-only_ parameters must be plain text, and be a valid choice for that parameter.