User Tools

Site Tools


Dates_and_Times

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
Dates_and_Times [2016/07/07 01:34]
JMichaelTX ADD explanation on mixing functions and token and time zones
Dates_and_Times [2023/06/20 02:44] (current)
peternlewis [Mixing Functions and Tokens]
Line 1: Line 1:
 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.**\\  ​+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. [[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](https://www.keyboardmaestro.com/action/linkthru?​icudatetimereference).
  
 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 21: Line 29:
  
 ^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 31: Line 39:
 ###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-Syntaxfor the full list.+**For the complete list** of codes, see the [ICU Date/Time codes](https://www.keyboardmaestro.com/action/linkthru?​icudatetimereference).
  
  
 +**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 44: Line 53:
 ^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 57: Line 67:
 |**//​%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](https://www.keyboardmaestro.com/action/linkthru?​icudatetimereference)
 * [[function:​NOW|NOW()]] and [[function:​TIME|TIME()]] functions return the current time in GMT * [[function:​NOW|NOW()]] and [[function:​TIME|TIME()]] functions return the current time in GMT
 * <+ or –\> is the operator to add (+) or subtract (–) * <+ or –\> is the operator to add (+) or subtract (–)
Line 69: Line 80:
 * *<​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
  
-%ICUDateTimeFor% TIME(2015, 12, 25) - GMTOFFSET() %EEE, MMM d, yyyy%\\   +[[token:​ICUDateTimeFor|%ICUDateTimeFor%]] [[function:​TIME|TIME(2015, 12, 25)]] [[function:​GMTOFFSET|GMTOFFSET()]] %EEE, MMM d, yyyy% => Fri, Dec 25, 2015
-=> Fri, Dec 25, 2015+
  
 ===== Date/Time Functions and Calculations ===== ===== Date/Time Functions and Calculations =====
Line 101: Line 111:
 * [[unixtime]] in GMT * [[unixtime]] in GMT
  
-==== Mixing Functions and Tokens ==== +===== Mixing Functions and Tokens =====
- +
-You might expect `%ICUDateTimeFor%TIME(2017,​ 1, 1 )%EEE, MMM d, yyyy%` to yield `Sun, Jan 1, 2016`.\\  +
-However, it may yield `Sat, Dec 31, 2016`, depending on your local time zone.+
  
 +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: Here is why:
  
-* The [TIME](https://​wiki.keyboardmaestro.com/​function/TIME) function takes and returns the values in GMT. +* The [[function:TIME|TIME()]] function takes and returns the values in GMT. 
-* The [ICUDateTimeFor](https://​wiki.keyboardmaestro.com/​token/​ICUDateTime) ​token displays the localized time. +* The [[token:ICUDateTimeFor|%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. +* 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 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).+* 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 `%ICUDateTimeFor%TIME(2017,​ 1, 1 , 12, 0, 0)%EEE, MMM d, yyyy%' ​you will now get the expected result of `Sun, Jan 1, 2017`+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 =====
  
 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.
 +
 +===== 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 ===== ===== See Also =====
  
-----+==== Actions ====
  
-=== Actions === +* [[action:​Filter|Filter]] (Process Text Tokens)
- +
-* [[action:​Filter ​Clipboard|Filter ​Clipboard]] (Process Text Tokens) +
-* [[action:​Filter Variable|Filter Variable]] (Process Text Tokens)+
 * [[:​Actions|See all Actions]] * [[:​Actions|See all Actions]]
- 
----- 
  
 ==== Forum ==== ==== Forum ====
Line 138: Line 145:
 - [[https://​forum.keyboardmaestro.com/​t/​previous-date-variables-best-way/​3311/​4|Previous Date Variables]] - [[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/​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://www.google.fr/​search?​q=site:​forum.keyboardmaestro.com+Dates+Times|Keyboard Maestro Forum topics about Dates and Times]] +- [[https://​forum.keyboardmaestro.com/​tags/date_time|Keyboard Maestro Forum topics about Dates and Times]]
- +
-==== Related Pages ==== +
- +
-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](https://​forum.keyboardmaestro.com/​t/draft-rewrite-of-wiki-dates-and-times-article/​2485/​1)+
Dates_and_Times.1467869641.txt.gz · Last modified: 2016/07/07 01:34 by JMichaelTX