Get time

Purpose: Get time.

 get-time to <time var> \
     [ since-epoch ] \
     |
     (
         [ timezone <tz> ] \
         [ year <year> ] \
         [ month <month> ] \
         [ day <day> ] \
         [ hour <hour> ] \
         [ minute <minute> ] \
         [ second <second> ] \
         [ format <format> ] \
         [ from-epoch <epoch time> ]
     )

Copied!

get-time produces <time var> variable that contains string with current time by default (without "since-epoch" clause), or a number of seconds since the Epoch (1970-01-01 00:00:00 +0000 (UTC)) if "since-epoch" clause is used.

Without "since-epoch" clause

If "from-epoch" clause is used, then <epoch time> is the number of seconds since the Epoch, and get-time will assume it to be the current time (i.e. the actual current time will not be used). Otherwise, if none of "year", "month", "day", "hour", "minute" or "second" clauses are used, then the actual current time is produced. In further text, "current" time means one or the other, depending on whether "from-epoch" clause is used or not.

Use timezone to specify that time produced will be in timezone <tz>. For example if <tz> is "EST", that means Eastern Standard Time, while "MST" means Mountain Standard Time. The exact way to get a full list of timezones recognized on your system may vary, but on many systems you can use:

timedatectl list-timezones

Copied!

So for example to get the time in Phoenix, Arizona you could use "America/Phoenix" for <tz>. If timezone clause is omitted, then time is produced in "GMT" timezone by default. DST (Daylight Savings Time) is automatically adjusted.

Each variable specified with "year", "month", "day", "hour", "minute" or "second" is a time to be added or subtracted to/from current time (see above for what is "current" time). For example "year 2" means add 2 years to the current time, and "year -4" means subtract 4 years, whereas "hour -4" means subtract 4 hours, etc. So for example, a moment in time that is 2 years into the future minus 5 days minus 1 hour is:

 get-time to time_var year 2 day -5 hour -1

Copied!

<format> allows you to get the time in any string format you like, using the specifiers available in C "strftime". For example, if <format> is "%A, %B %d %Y, %l:%M %p %Z", it will produce something like "Sunday, November 28 2021, 9:07 PM MST". The default format is "UTC/GMT" format, which for instance, is suitable for use with cookie timestamps, and looks something like "Mon, 16 Jul 2012 00:03:01 GMT".

With "since-epoch" clause

In this case, <time var> is a number signifying the number of seconds since the Epoch (1970-01-01 00:00:00 +0000 (UTC)) to the present moment. Golf operates on 64 numbers and the result is always safe (account for 292 billion years into the past and the future). This option is commonly used to obtain time in a form that can be subtracted, resulting in the number of seconds between two points in time, or for any other purpose where obtaining current time is more useful if represented as a number.

Examples

To get current time in "GMT" timezone, in a format that is suitable for use with set-cookie (for example to set expiration date):

 get-time to mytime

Copied!

To get the time in the same format, only 1 year and 2 months in the future:

 get-time to mytime year 1 month 2

Copied!

An example of a future date (1 year, 3 months, 4 days, 7 hours, 15 minutes and 22 seconds into the future), in a specific format (see "strftime"):

 get-time to time_var timezone "MST" year 1 month 3 day 4 hour 7 minute 15 second 22 format "%A, %B %d %Y, %l:%M %p %Z"

Copied!

Get number of seconds sinc Jan 1, 1970:

 get-time to mytime since-epoch
 print-out mytime new-line

Copied!

Produce 2 days after Epoch time stamp of 489326400 (which is July 4th 1985 at noon), and then add 2 days to it:

 get-time to mytime from-epoch 489326400 2 day
 print-out mytime

Copied!