Skip to content

Latest commit

 

History

History
419 lines (293 loc) · 10.7 KB

time.md

File metadata and controls

419 lines (293 loc) · 10.7 KB
Raw

time

Date, time, and duration operations

Overview

Time is represented by either a:

  • DateTime
  • Date
  • Time

An interval of time is represented by a Duration.

DateTime, Date, Time

Parsing of DateTime values tries to be as lenient as possible to allow easy entry by hand or from various sources via cut and paste. Parsing uses the following rules:

  • If a date and time is needed but the value only contains a time, the date portion is set to today's date.
  • Days of week such as Monday are parsed but ignored. The day of week is computed from the actual date.
  • If a two digit year is used it is assumed to apply to the current century. The value of 23 is set to the year 2023 and the value of 99 is set to 2099. Use a four digit year to use 1999.

The types of Date and Time are used when only those portions of a DateTime are necessary.

All of the following formats can be parsed:

Input Stack
c 2006-01 dt Sun Jan 1 2006 12:00:00am -0700 MST
c 2006-01-02 dt Mon Jan 2 2006 12:00:00am -0700 MST
c 2006-032 dt Wed Feb 1 2006 12:00:00am -0700 MST
c 1/2 dt Mon Jan 2 2006 12:00:00am -0700 MST
c 1/2/2006 dt Mon Jan 2 2006 12:00:00am -0700 MST
c 1/2/06 dt Mon Jan 2 2006 12:00:00am -0700 MST
c 'Jan 2 2006' dt Mon Jan 2 2006 12:00:00am -0700 MST
c 'Jan 2 06' dt Mon Jan 2 2006 12:00:00am -0700 MST
c 'Fri Jan 2 2006' dt Mon Jan 2 2006 12:00:00am -0700 MST
c 'Friday Jan 2 2006' dt Mon Jan 2 2006 12:00:00am -0700 MST
c 'Jan 2' dt Mon Jan 2 2006 12:00:00am -0700 MST
c 'Fri, Jan 2' dt Mon Jan 2 2006 12:00:00am -0700 MST
c 15:04:05 dt Mon Jan 2 2006 3:04:05pm -0700 MST
c '15:04:05 PDT' dt Mon Jan 2 2006 3:04:05pm -0700 PDT
c 15:04 dt Mon Jan 2 2006 3:04:00pm -0700 MST
c 3:04PM dt Mon Jan 2 2006 3:04:00pm -0700 MST
c '3:04 PM' dt Mon Jan 2 2006 3:04:00pm -0700 MST
c 3:04a dt Mon Jan 2 2006 3:04:00am -0700 MST
c '3:04a EST' dt Mon Jan 2 2006 3:04:00am -0500 EST
c '3:04a -0500' dt Mon Jan 2 2006 3:04:00am -0500
c '3:04a EST -0500' dt Mon Jan 2 2006 3:04:00am -0500 EST

The examples above are the result if the current time is Jan 2 2006 15:04:05 -0700 MST.

Duration

A Duration is a value with hours, minutes, and seconds in the form of hourshminutesmsecondss. Zero values may be omitted. Examples:

Input Stack
4h15m30s 10m20s add 4h 25m 50s
10s add 4h 26m
34m add 5h

Index

Operation Description
add Addition, time or duration
date Formats to a common date layout
date.time, dt Formats to a common date/time layout
date.time?, dt? Parses text as a date/time
date? Parses text as a date
day.year, doy Day of year
hours Convert to hours
local.zone Sets the local time zone
local.zone? Name of the local time zone
minutes Convert to minutes, time
minutes Minutes operation
now Current date and time
now.reset, now- Cancels override of now
now= Override now value
seconds Seconds operation
seconds Convert time to seconds, time
sub Subtraction, time or duration
time Formats to a common time layout
time.zone, tz Converts time to another time zone
time? Parses text as a time

Operations

add

Adds a duration and time or adds two durations.

Stack effects:

( x:Duration y:Duration -- Duration )
( x:Duration y:DateTime -- DateTime )
( x:DateTime x:Duration -- DateTime )

Example:

Input Stack
c 3:30pm 2h + Mon Jan 2 2006 5:30:00pm -0700 MST
c 2h30m 45m + 3h 15m

date

Formats date/time x to a common date layout. Time information, if present, is discarded.

Stack effects:

( x:DateTime -- Date )

Example:

Input Stack
'2006-01-02T15:04:05 UTC' date Mon Jan 2 2006

date.time

Formats x to a common date/time layout.

Alias: dt

Stack effects:

( x:DateTime -- DateTime )

Example:

Input Stack
'2006-01-02T15:04:05 UTC' date.time Mon Jan 2 2006 3:04:05pm UTC

date.time?

Parses x as a date/time and returns true on success and false on failure.

Alias: dt?

Stack effects:

( x:Text -- Bool )

Example:

Input Stack
c '25 Jan 24 3:43pm' date.time? true
c '32 Sun 24 3:78pm' date.time? false

date?

Parses x as a date and returns true on success and false on failure.

Stack effects:

( x:Text -- Bool )

Example:

Input Stack
c '25 Jan 24' date? true
c '32 Sun 24' date? false

day.year

Day of the year for the given date x.

Alias: doy

Stack effects:

( x:DateTime -- Int/s )

Example:

Input Stack
2006-03-15 doy 74

hours

Converts the duration x into hours.

Stack effects:

( x:Duration -- Float )

Example:

Input Stack
10h20m30s hours 2 round 10.34 h

local.zone

Sets the local time zone to z. An invalid argument error is raised if the time zone is not recognized.

Stack effects:

( z:Text --  )

Example:

Input Stack
now time 3:04:05pm -0700 MST
c /est local.zone local time zone is now EST
now time 5:04:05pm -0500 EST
c /Asia/Jakarta local.zone local time zone is now Asia/Jakarta
now time 5:04:05am +0700 WIB

local.zone?

The name of the local time zone.

Stack effects:

(  -- zone:Text )

Example:

Input Stack
local.zone? time zone: MST

minutes

Converts the duration x into minutes.

Stack effects:

( x:Duration -- Float )

Example:

Input Stack
10h20m30s minutes 2 round 620.5 m

minutes

now

The current date and time. If now= has been called, that date and time will be returned instead.

Stack effects:

(  -- DateTime )

Example:

Input Stack
now Mon Jan 2 2006 3:04:05pm -0700 MST

now.reset

If the value returned by now has been mocked out with now.set, this resets now to returning the actual time.

Alias: now-

Stack effects:

(  --  )

now=

Override the value returned by now. Useful for to mocking current time while testing.

Stack effects:

( x:DateTime --  )

Example:

Input Stack
'Nov 5 1955 01:22 Nov 5 1955 01:22
now= now set to 'Sat Nov 5 1955 1:22:00am -0700 MST'
now Sat Nov 5 1955 1:22:00am -0700 MST

seconds

seconds

Converts the duration x into seconds.

Stack effects:

( x:Duration -- Float )

Example:

Input Stack
10h20m30s seconds 2 round 37230 s

sub

Subtracts a duration from a time or subtracts two durations.

Stack effects:

( x:Duration y:Duration -- Duration )
( x:DateTime y:Duration -- DateTime )
( x:DateTime y:DateTime -- Duration )

Example:

Input Stack
c 3:30pm 2h sub Mon Jan 2 2006 1:30:00pm -0700 MST
c 2h30m 45m sub 1h 45m
c 3:30pm 1:30pm sub 2h

time

Formats date/time x to a common time layout. Date information, if present, is discarded.

Stack effects:

( x:DateTime -- Time )

Example:

Input Stack
'2006-01-02T15:04:05 UTC' time 3:04:05pm UTC

time.zone

Converts the date/time x into time zone z. An illegal argument error is raised if z is an unrecognized time zone.

Alias: tz

Stack effects:

( x:DateTime z:Text -- DateTime )

Example:

Input Stack
now Mon Jan 2 2006 3:04:05pm -0700 MST
/PST tz Mon Jan 2 2006 2:04:05pm -0800 PST
tz.jakarta.asia tz Tue Jan 3 2006 5:04:05am +0700 WIB

time?

Parses x as a time and returns true on success and false on failure.

Stack effects:

( x:Text -- Bool )

Example:

Input Stack
c '3:45pm' time? true
c '3:65pm' time? false