Standard Library/dates

This script defines date and time utilities and is included in the J standard library. Definitions are loaded into the z locale.

Definitions

C	calendar
G	getdate
I	isotimestamp
T	timestamp, todate, todayno, tsdiff, tsrep, tstamp
V	valdate
W	weekday, weeknumber, weeksinyear

---

timestamp

v

format time stamps as: 23 May 1998 16:06:39

calendar (verb)

Returns calendar for year, as a list of months

Syntax:

[opt] calendar year [months]

right argument is one or more numbers: year, months If no months are given, it defaults to all months.

optional left argument is startday of week,

0=sunday (default)
1=monday

Example:

   calendar 2014 3 4
┌─────────────────────┬─────────────────────┐
│         Mar         │         Apr         │
│ Su Mo Tu We Th Fr Sa│ Su Mo Tu We Th Fr Sa│
│                    1│        1  2  3  4  5│
│  2  3  4  5  6  7  8│  6  7  8  9 10 11 12│
│  9 10 11 12 13 14 15│ 13 14 15 16 17 18 19│
│ 16 17 18 19 20 21 22│ 20 21 22 23 24 25 26│
│ 23 24 25 26 27 28 29│ 27 28 29 30         │
│ 30 31               │                     │
└─────────────────────┴─────────────────────┘

getdate (verb)

Get date from character string. Useful for input forms with date entry fields.

Syntax:

[opt] getdate string

date forms permitted:
   1986 5 23
   May 23 1986
   23 May 1986

optional x:
 0 = days first - default (23 5 1986)
 1 = months first (5 23 1986)

Other characters allowed: ,-/:

If not given, century defaults to current

Only first 3 characters of month are tested.

Example:

   getdate '23/5/86'
2086 5 23
   getdate 'may 23, 1986'
1986 5 23
   getdate '1986-5-23'
1986 5 23

isotimestamp (verb)

Format time stamps as: 2000-05-23 16:06:39.268

y is one or more time stamps in 6!:0 format.

todate (verb)

Converts day numbers to dates, converse todayno

This conversion is exact and provides a means of performing exact date arithmetic.

y = day numbers
x = optional:
  0 - result in form <yyyy mm dd> (default)
  1 - result in form <yyyymmdd>
  2 - result in form <yyyy mm dd hh MM ss>

Example:

   todate 72460
1998 5 23

   todate 0 1 2 3 + todayno 1992 2 27
1992 2 27
1992 2 28
1992 2 29
1992 3  1

todayno (verb)

Converts dates to day numbers, converse todate

y = dates

x = optional:
  0 - dates in form YYYY MM DD (default)
  1 - dates in form YYYYMMDD
  2 - dates in form YYYY MM DD HH MM SS

0 = todayno 1800 1 1, or earlier

Example:

   todayno 1998 5 23
72460

tsdiff (verb)

Return differences between pairs of dates.

Syntax:

end tsdiff begin

 end, begin are vectors or matrices in form YYYY MM DD
 end dates should be later than begin dates

method is to subtract dates on a calendar basis to determine integral number of months plus the exact number of days remaining. This is converted to payment periods, where # days remaining are calculated as: (# days)%365

Example:

   1994 10 1 tsdiff 1986 5 23
8.35799

tsrep (verb)

Timestamp representation as a single number.

Syntax:

[opt] timerep times

 opt=0 convert timestamps to numbers (default)
     1 convert numbers to timestamps

timestamps are in 6!:0 format, or matrix of same.

Example:

   tsrep 1800 1 1 0 0 0
0
   x: tsrep 1995 5 23 10 24 57.24
6165887097240

tstamp (verb)

Same as timestamp

valdate (verb)

Validate dates.

Syntax:

valdate dates

dates is 3-element vector
      or 3-column matrix
      in form YYYY MM DD

returns 1 if valid

weekday (verb)

Returns weekday from date, 0=Sunday ... 6=Saturday. Arguments as for todayno

Example:

   weekday 1997 5 23
5
   1 weekday 19970523
5

weeknumber (verb)

Gives the year and weeknumber of date.

A week belongs to a year iff 4 days of the week belong to that year. see iso 8601 calendar

y = dates In the ISO 8601 calendar a week starts on monday.

Example:

   weeknumber 2005 1 2
2004 53
   weeknumber 2005 1 3
2005 1

weeksinyear (verb)

Gives number of weeks in year

y = years

In the ISO 8601 calendar a week starts on monday.

Example:

  weeksinyear 2000 +i.10
52 52 52 52 53 52 52 52 52 53