User Tools

Site Tools


token:ICUDateTime

ICU Date/Time Tokens

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 article.

Required Parameters for ICUDateTime Tokens

The parameters are specified between % signs after the main ICDDateTime token.

  • %ICUDateTime%[output date format]%
    • Returns the current date and time in the specified format.
  • %ICUDateTimeFor%<Seconds in Unix Time>%[output date format]%
    • Returns Date/Time specified by the Unix Time, 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>

where

  • angle brackets < > denote a numeric parameter, may use a Variable and/or formula
  • square brackets [ ] 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.
  • [output date format] must conform to the ICU Date/Time codes.
  • <Seconds in Unix Time> is the total number of seconds since the start of 1970, GMT.
  • <amount of time> is an integer in the units of what you specific in the [unit of time] parameter.
  • [unit of time] must be a time unit from the below list.

Unit of Time

The available time units for %ICUDateTimePlus% and %ICUDateTimeMinus% are:

  • Seconds
  • Minutes
  • Hours
  • Days
  • Weeks
  • Months
  • Years
  • Sundays
  • Mondays
  • Tuesdays
  • Wednesdays
  • Thursdays
  • Fridays
  • Saturdays

Using Plus 0 or 1 With Day of Week (v8+)

  • If the Time Unit is a day of the week (Sundays thru Saturdays)
    • If you use a Plus 0 (%ICUDateTimePlus%0%),
      it will return the next appropriate day for that day of week, possibly returning today if it is the same day of week as entered;
      • So if Today is Tuesday, and you use %ICUDateTimePlus%0%Tuesdays%, then it will return Today's date.
      • Whereas, if you use %ICUDateTimePlus%0%Wednesdays%, it will return tomorrow's date.
    • If you use Plus 1 (%ICUDateTimePlus%1%),
      it will return the next appropriate day, strictly after Today.

Examples

For example, if today is Tuesday, September 5, 2017, you would get these results:

TokenResult
%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).

Format Specification

The format is a specified with an ICU Date Time Format Specifier 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:

%ICUDateTimeFor% TIME(2015, 8, 23,12,0,0) %EEE, MMM d, yyyy%

which will generally work anywhere since at midday GMT, the entire world (almost) is on the same date. Otherwise, folks with negative GMT offsets (which includes all of the Americas for example) will get the wrong result.

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:

%ICUDateTimePlus%<amount of time>%[unit of time]%[output date format]%

where

  • angle brackets < > denote a numeric parameter, may use a Variable and/or formula
  • square brackets [ ] 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.

Examples

%ICUDateTimePlus%3%Days%MM/dd/yyyy%
%ICUDateTimePlus%myAmountOfTime%Days%yyyyMMdd%
%ICUDateTimePlus%myBaseNumber + 3%Months%yyyy-MM-dd%

Also See

Localization

Prior to Mojave, and after Keyboard Maestro 9.0, dates should be in your chosen language. Unfortunately Apple changed Mojave and later to make the system return dates only in the Keyboard Maestro localized language (ie, English), regardless of your chosen locale. Keyboard Maestro 9.0 works around this by claiming to be in all locales, even though it is really only localized for English itself.

See Also

Actions

Functions

Tokens

Topics

Forum

token/ICUDateTime.txt · Last modified: 2020/05/28 17:59 by JMichaelTX