This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision Next revision Both sides next revision | ||
Dates_and_Times [2016/03/03 16:39] AlainLifchitz cosmetic change |
Dates_and_Times [2017/09/07 00:11] peternlewis |
||
---|---|---|---|
Line 1: | Line 1: | ||
+ | {{:date_and_time-icon.gif|}} | ||
+ | |||
Dates and Times | Dates and Times | ||
=============== | =============== | ||
- | (Reference Page)\\ | + | |
- | {{:date_and_time-icon.gif|}} **Keyboard Maestro offers a very full featured set of date and time [[Tokens|tokens]], formats, and calculations.**\\ [[token:ICUDateTime|Date/Time tokens]] are like text expansion codes that return date/time values as text in the specified format. | + | Keyboard Maestro offers a very full featured set of date and time [[Tokens|tokens]], formats, and calculations. |
+ | |||
+ | [[token:ICUDateTime|Date/Time tokens]] are like text expansion codes that return date/time values as text in the specified format. | ||
===== Examples ===== | ===== Examples ===== | ||
+ | ==== 1. Get Current Date/Time ==== | ||
The most commonly used token is for returning the current date/time in the format you like: | 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](http://userguide.icu-project.org/formatparse/datetime#TOC-Date-Time-Format-Syntax).\\ | + | ''%ICUDateTime%**format**%'' where **format** is from the [ICU Date/Time codes](http://userguide.icu-project.org/formatparse/datetime#TOC-Date-Time-Format-Syntax). |
For example, using the [[action:Set_Variable_to_Text|Set Variable to Text]] Action:\\ | For example, using the [[action:Set_Variable_to_Text|Set Variable to Text]] Action:\\ | ||
{{:km7-set-var-to-date.png|}} | {{:km7-set-var-to-date.png|}} | ||
+ | |||
+ | ==== 2. Add Time to Date ==== | ||
+ | This example adds days to the current date using a Keyboard Maestro Variable. See below for other options.{{:add-days-current-date-km-7.3.png?nolink|}} | ||
+ | |||
+ | For more info see this Forum Topic: [Add Time to Current Date @Example](https://forum.keyboardmaestro.com/t/date-add-time-to-current-date-example/7213), which provides instructions and a complete macro. | ||
+ | |||
+ | --- | ||
Line 20: | Line 33: | ||
^Usage^Token and Format^Results^ | ^Usage^Token and Format^Results^ | ||
- | |International|%ICUDateTime%yyyy/MM/dd%|2015/11/28| | + | |[[http://www.iso.org/iso/home/standards/iso8601.htm | ISO/International]]|%ICUDateTime%yyyy-MM-dd%|2015-11-28| |
|Australia\\ Europe|%ICUDateTime%dd/MM/yyyy%|28/11/2015| | |Australia\\ Europe|%ICUDateTime%dd/MM/yyyy%|28/11/2015| | ||
|United States|%ICUDateTime%EEE, MMM d, yyyy%|Sat, Nov 28, 2015| | |United States|%ICUDateTime%EEE, MMM d, yyyy%|Sat, Nov 28, 2015| | ||
Line 29: | Line 42: | ||
###Format Codes | ###Format Codes | ||
- | Here are some commonly used format codes. See the [ICU Date/Time codes](http://userguide.icu-project.org/formatparse/datetime#TOC-Date-Time-Format-Syntax) for the full list. | ||
+ | **For the complete list** of codes, see the [ICU Date/Time codes](http://userguide.icu-project.org/formatparse/datetime#TOC-Date-Time-Format-Syntax). | ||
+ | |||
+ | **Some Commonly Used Format Codes** | ||
^Period^ Format\\ Code ^Example^Results^ | ^Period^ Format\\ Code ^Example^Results^ | ||
^Year| y((Do not use capital Y (year of "Week of Year")!)) |yy\\ yyyy|96\\ 1996| | ^Year| y((Do not use capital Y (year of "Week of Year")!)) |yy\\ yyyy|96\\ 1996| | ||
Line 42: | Line 57: | ||
^Minute| m |m\\ mm|4\\ 04| | ^Minute| m |m\\ mm|4\\ 04| | ||
^Second| s |s\\ ss|5\\ 05| | ^Second| s |s\\ ss|5\\ 05| | ||
+ | ^Fractional Second\\ (truncates)| S |S\\ SSS|1\\ 123| | ||
(!) 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. | (!) 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 ===== | + | |
+ | ===== Date/Time Tokens & Formulas ===== | ||
Also see Wiki article [[token:ICUDateTime]] token | Also see Wiki article [[token:ICUDateTime]] token | ||
- | ^KM Token^Example^ | + | ^Date/Time Token/Formula^Example^ |
|**//%ICUDateTime%<format>%//**\\ Returns Current Date/Time (local)|Get Current Date/Time\\ %ICUDateTime%EEE, MMM d, yyyy%\\ => Sat, Nov 28, 2015| | |**//%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| | |**//%ICUDateTimePlus%<Quantity>%<TimeUnit>%<format>%//**\\ Adds to Current Date/Time (local)|Add 3 days\\ %ICUDateTimePlus%**3%Days**%EEE, MMM d, yyyy%\\ => Tue, Dec 1, 2015| | ||
Line 53: | Line 71: | ||
|**//%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%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| | |**//%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| | ||
+ | |**//%ICUDateTimePlus%<Formula for Quantity>%<TimeUnit>%<format>%//**\\ Using functions to calculate date offset.|**Get Date for Selected Prior Day Number**\\ `%ICUDateTimePlus%-(DOW() + 7 - DayNum)%Days%EEE, MMM d, yyyy%`\\ If Current Date is Dec 25, 2016, and _DayNum_ is 1:\\ => Sun, Dec 18, 2016\\ where "DayNum" is the number of the weekday (can be a Variable)| | ||
*where* | *where* | ||
- | * *<TimeUnit> is one of the following: *Seconds, Minutes, Hours, Days, Weeks, Months, Years | + | * <TimeUnit> is one of the following: Seconds, Minutes, Hours, Days, Weeks, Months, Years, or a weekday, Sundays, Mondays, Tuesdays, Wednesdays, Thursdays, Fridays, Saturdays. |
* <Quantity> is the number of <TimeUnit>s | * <Quantity> is the number of <TimeUnit>s | ||
* <format> is the format of text returned, using the [ICU Date/Time codes](http://userguide.icu-project.org/formatparse/datetime#TOC-Date-Time-Format-Syntax) | * <format> is the format of text returned, using the [ICU Date/Time codes](http://userguide.icu-project.org/formatparse/datetime#TOC-Date-Time-Format-Syntax) | ||
Line 65: | Line 84: | ||
* *<Year>, <Month>, <Day>, <Hour>, <Min>, Sec> are in integer units for the indicated period.* | * *<Year>, <Month>, <Day>, <Hour>, <Min>, Sec> are in integer units for the indicated period.* | ||
- | Since [[function:TIME|TIME()]] and [[function:NOW|NOW()]] returns the specified date/time in GMT, you can adjust for your local time zone by subtracting the [[function:GMTOFFSET|GMTOFFSET()]] function | + | Since [[function:TIME|TIME()]] and [[function:NOW|NOW()]] returns the specified date/time in GMT :!: , you can adjust for your local time zone by subtracting the [[function:GMTOFFSET|GMTOFFSET()]] function |
+ | |||
+ | [[token:ICUDateTimeFor|%ICUDateTimeFor%]] [[function:TIME|TIME(2015, 12, 25)]] - [[function:GMTOFFSET|GMTOFFSET()]] %EEE, MMM d, yyyy% => Fri, Dec 25, 2015 | ||
- | %ICUDateTimeFor% TIME(2015, 12, 25) - GMTOFFSET() %EEE, MMM d, yyyy%\\ | ||
- | => Fri, Dec 25, 2015 | ||
===== Date/Time Functions and Calculations ===== | ===== Date/Time Functions and Calculations ===== | ||
Line 75: | Line 94: | ||
[Editor: Plan to put in table with descriptions] | [Editor: Plan to put in table with descriptions] | ||
- | * [[token:ShortDate|ShortDate (token)]] | + | * [[function:DAY|DAY() (function)]] |
- | * [[token:LongDate|LongDate (token)]] | + | * [[function:DOW|DOW() (function)]] |
- | * [[token:NumberDate|NumberDate (token)]] | + | * [[function:GMTOFFSET|GMTOFFSET() (function)]] |
+ | * [[function:JD2TIME|JD2TIME() (function)]] | ||
+ | * [[function:MJD2TIME|MJD2TIME() (function)]] | ||
+ | * [[function:NOW|NOW() (function)]] (unixtime) | ||
+ | * [[function:TIME|TIME() (function)]] (unixtime) | ||
+ | * [[function:TIME2JD|TIME2JD() (function)]] | ||
+ | * [[function:TIME2MJD|TIME2MJD() (function)]] | ||
+ | * [[token:ICUDateTime|%ICUDateTime% (token)]] | ||
+ | * [[token:ICUDateTimeFor|%ICUDateTimeFor% (token)]] | ||
+ | * [[token:ICUDateTimeMinus|%ICUDateTimeMinus% (token)]] | ||
+ | * [[token:ICUDateTimePlus|%ICUDateTimePlus% (token)]] | ||
+ | * [[token:LongDate|%LongDate% (token)]] (local) | ||
+ | * [[token:LongTime|%LongTime% (token)]] (local) | ||
+ | * [[token:NumberDate|%NumberDate% (token)]] (local) | ||
+ | * [[token:ShortDate|%ShortDate% (token)]] (local) | ||
+ | * [[token:ShortTime|%ShortTime% (token)]] (local) | ||
* [[JulianDate|JulianDate]] | * [[JulianDate|JulianDate]] | ||
- | * [[function:TIME2JD|TIME2JD (function)]] | ||
- | * [[function:TIME2MJD|TIME2MJD (function)]] | ||
- | * [[function:JD2TIME|JD2TIME (function)]] | ||
- | * [[function:MJD2TIME|MJD2TIME (function)]] | ||
- | * [[token:ShortTime|ShortTime (token)]] (local) | ||
- | * [[token:LongTime|LongTime (token)]] | ||
* [[unixtime]] in GMT | * [[unixtime]] in GMT | ||
+ | |||
+ | ==== Mixing Functions and Tokens ==== | ||
+ | |||
+ | You might expect [[token:ICUDateTimeFor|%ICUDateTimeFor%]] [[function:TIME|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 [[function:TIME|TIME()]] function takes and returns the values in GMT. | ||
+ | * The [[token:ICUDateTimeFor|%ICUDateTimeFor%]] token displays the localized time. | ||
+ | * Thus, for [[function:TIME|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 [[function:TIME|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 [[token:ICUDateTimeFor|%ICUDateTimeFor%]] [[function:TIME|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 ===== | ===== Discussion on Keyboard Maestro Forum ===== | ||
Line 91: | Line 132: | ||
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](https://forum.keyboardmaestro.com/t/km-dates-times-notes-on-anchors-intervals-and-translations/1935) (Aug 2015), with contributions by @[ComplexPoint](https://forum.keyboardmaestro.com/users/ComplexPoint), @[peternlewis](https://forum.keyboardmaestro.com/users/peternlewis), and others. | 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](https://forum.keyboardmaestro.com/t/km-dates-times-notes-on-anchors-intervals-and-translations/1935) (Aug 2015), with contributions by @[ComplexPoint](https://forum.keyboardmaestro.com/users/ComplexPoint), @[peternlewis](https://forum.keyboardmaestro.com/users/peternlewis), and others. | ||
- | ### Related Pages | + | ===== See Also ===== |
- | + | ||
- | TBD\\ | + | |
- | ### See Also | + | === Actions === |
- | TBD\\ | + | * [[action:Filter|Filter]] (Process Text Tokens) |
+ | * [[:Actions|See all Actions]] | ||
- | ---- | + | ==== Forum ==== |
- | If you find any issues, or have any suggestions, concerning this page, please report them to [Draft Rewrite of Wiki Dates and Times Article](https://forum.keyboardmaestro.com/t/draft-rewrite-of-wiki-dates-and-times-article/2485/1) | + | |
+ | - [KM dates & times: Notes on calculations, anchors, intervals, and translations](https://forum.keyboardmaestro.com/t/km-dates-times-notes-on-anchors-intervals-and-translations/1935) (Aug 2015) | ||
+ | - [[https://forum.keyboardmaestro.com/t/date-calculations/2165|Date Calculations]] | ||
+ | - [[https://forum.keyboardmaestro.com/t/previous-date-variables-best-way/3311/4|Previous Date Variables]] | ||
+ | - [[https://forum.keyboardmaestro.com/t/icudatetime-format-from-locale/3458/5|%ICUDateTime% format from locale]] | ||
+ | - [[https://forum.keyboardmaestro.com/t/issue-with-date-time-functions/5856|Issue with Date/Time Functions]] | ||
+ | - [[https://forum.keyboardmaestro.com/tags/date_time|Keyboard Maestro Forum topics about Dates and Times]] |