User Tools

Site Tools


Dates_and_Times

**This is an old revision of the document!**

Dates and Times

(Reference Page)
Keyboard Maestro offers a very full featured set of date and time tokens, formats, and calculations.

Date/Time tokens are like text expansion codes that return date/time values as text in the specified format.

Examples

The most commonly used token is for returning the current date/time in the format you like:

%ICUDateTime%format% where format is from the ICU Date/Time codes.

For example, using the Set Variable to Text Action:

Date/Time Formats

Here are some common examples:

UsageToken and FormatResults
International%ICUDateTime%yyyy/MM/dd%2015/11/28
Australia
Europe
%ICUDateTime%dd/MM/yyyy%28/11/2015
United States%ICUDateTime%EEE, MMM d, yyyy%Sat, Nov 28, 2015
United States%ICUDateTime%MM/dd/yyyy%11/28/2015
Use in File Name%ICUDateTime%yyyy-MM-dd-HHmmssA%2015-11-28-15210755267426

You can embed most any characters you want with the Format Codes.

Format Codes

Here are a few of the commonly used format codes.
For the complete list of codes, see the ICU Date/Time codes.

Period Format
Code
ExampleResults
Year y1) yy
yyyy
96
1996
Month M M
MM
MMM
MMMM
9
09
Sep
September
Day d d
dd
2
02
Weekday Name E EEE
EEEE
Tue
Tuesday
AM/PM a a
a
am
pm
Hour (am/pm) h h
hh
7
07
Hour (24 hrs) H H
HH
19
19
Minute m m
mm
4
04
Second s s
ss
5
05
Fractional Seconds S S
SSS
SSSS
1
123
1234

⚠️ Do not use capital “Y” (year of “Week of Year”) unless you really mean it or you will get oddly strange results at the beginning/end of each year.

Date/Time Tokens

Also see Wiki article ICUDateTime token

KM TokenExample
%ICUDateTime%<format>%
Returns Current Date/Time (local)
Get Current Date/Time
%ICUDateTime%EEE, MMM d, yyyy%
⇒ Sat, Nov 28, 2015
%ICUDateTimePlus%<Quantity>%<TimeUnit>%<format>%
Adds to Current Date/Time (local)
Add 3 days
%ICUDateTimePlus%3%Days%EEE, MMM d, yyyy%
⇒ Tue, Dec 1, 2015
%ICUDateTimeMinus%<Quantity>%<TimeUnit>%<format>%
Subtracts from Current Date/Time (local)
Subtract 1 month
%ICUDateTimeMinus%1%Months%EEE, MMM d, yyyy%
⇒ Wed, Oct 28, 2015
%ICUDateTimeFor%NOW()<+ or –><Seconds>%format%
Adds or Subtracts from Current Date/Time (GMT)
Add 1 hour to Current GMT
%ICUDateTimeFor%NOW()+ (60*60) %EEE, MMM d, yyyy h:mm%
⇒ Sat, Nov 28, 2015 7:14
%ICUDateTimeFor% TIME(<Year>, <Month>, <Day> [, <Hour>, <Min>, Sec>])%<format>%
Sets absolute date/time (GMT)
Set absolute date in GMT
%ICUDateTimeFor% TIME(2015, 12, 25) %EEE, MMM d, yyyy%
⇒ Thu, Dec 24, 2015

Set absolute date in LOCAL time
%ICUDateTimeFor% TIME(2015, 12, 25) - GMTOFFSET() %EEE, MMM d, yyyy%
⇒ Fri, Dec 25, 2015

where

  • <TimeUnit> is one of the following: *Seconds, Minutes, Hours, Days, Weeks, Months, Years <Quantity> is the number of <TimeUnit>s
  • <format> is the format of text returned, using the ICU Date/Time codes
  • NOW() and TIME() functions return the current time in GMT
  • <+ or –> is the operator to add (+) or subtract (–)
  • <Seconds> is the number of seconds to add/subtract
  • [ ] indicate optional terms
  • <Year>, <Month>, <Day>, <Hour>, <Min>, Sec> are in integer units for the indicated period.

Since TIME() and NOW() returns the specified date/time in GMT, you can adjust for your local time zone by subtracting the GMTOFFSET() function

%ICUDateTimeFor% TIME(2015, 12, 25) - GMTOFFSET() %EEE, MMM d, yyyy%
⇒ Fri, Dec 25, 2015

Date/Time Functions and Calculations

Mixing Functions and Tokens

You might expect %ICUDateTimeFor% TIME(2017, 1, 1) %EEE, MMM d, yyyy% to yield Sun, Jan 1, 2017.
However, it may yield Sat, Dec 31, 2016, depending on your local time zone.

Here is why:

  • The TIME() function takes and returns the values in GMT.
  • The %ICUDateTimeFor% token displays the localized time.
  • Thus, for TIME(Year, Month, Day) (which is in GMT), the ICUDateTimeFor displayed date in local time will be one less for anyone with a negative time zone offset.
  • It is best is to use TIME(Year, Month, Day, 12, 0, 0) which will give noon GMT time, and thus the same day in local time for pretty much everyone in the world (everyone with time zone differences strictly between -12 hours and +12 hours).

So, if you use %ICUDateTimeFor% TIME(2017, 1, 1 , 12, 0, 0) %EEE, MMM d, yyyy% you will now get the expected result of Sun, Jan 1, 2017

Discussion on Keyboard Maestro Forum

For a more complete discussion on the many different ways to use date and times, see KM dates & times: Notes on anchors, intervals, and translations (Aug 2015), with contributions by @ComplexPoint, @peternlewis, and others.

See Also


Actions


Forum

TBD


If you find any issues, or have any suggestions, concerning this page, please report them to Draft Rewrite of Wiki Dates and Times Article

1)
Do not use capital Y (year of “Week of Year”)!
Dates_and_Times.1480806049.txt.gz · Last modified: 2016/12/03 18:00 by JMichaelTX