Addons/types/datetime

User Guide \| Installation \| Development \| Categories \| Git \| Build Log

types/datetime - utilities for working with dates and times

Addon for extending the dates.ijs system script (J6.02) or stdlib.ijs script (J7).
Conversion between Georgian time stamps, Julian day number, J day number, Microsoft date, Linux date
Date/time arithmetic
Custom formatting of dates and times

Browse history, source and examples using github

Installation

Use JAL/Package Manager to install the types/datetime addon.

Usage

Ensure that the addon script is loaded:

   require 'types/datetime'

Convert between different numerical representations of dates and times:

   ]Now=: 6!:0 ''
2010 10 21 15 18 53.468               NB. 6-item vector
   todayno 3{. Now                    NB. using original todayno verb from the dates script (# days since 1800 1 1)
76994
   todayno Now                        NB. but doesn't handle full vector
|length error: todayno
|   'y m d'    =.<"_1|:a
   toDayNo Now                        NB. the Addon's version gives the time as a decimal fraction of a day
76994.638
   1 toDayNo 20101021.151853468       NB. toDayNo optionally accepts this alternative input format
76994.638
   toDayNo Now
76994.638
   0j10": toDayNo Now                 NB. the J day number *display* depends on your Print Precision setting
76994.6381188426
   (toDayNumber Now) = 1 toDayNo 20101021.151853468
1
   toDateTime toDayNo Now
2010 10 21 15 18 53.468
   1 toDateTime toDayNo Now           NB. again the displayed number depends on Print Precision
20101021
   0j5": toJulian toDayNo Now         NB. convert from J day number to Julian day number
2455491.63812
   fromJulian toJulian toDayNo Now
76994.638

Do simple date arithmetic:

   2008 2 28 20 30 0 tsPlus 5 0 0     NB. add 5 hours to timestamp (leap years handled)
2008 2 29 1 30 0
   2009 3 1 1 30 0 tsMinus 5 0 0      NB. subtract 5 hours from timestamp
2009 2 28 20 30 0

Format numeric dates/times in custom string formats.

   'DDDD, DD MMM YYYY, hh:mm:ss' fmtDateTime toDayNo Now
Thursday, 21 Oct 2010, 15:18:53
   'Ti\me i\s: hh:mm:ss' fmtTime 86400 * 1|toDayNo Now
Time is: 15:18:53

To see more examples of usage, inspect the test_datetime.ijs script

Available Nouns/Verbs

J0Date	n	Add to J's dayno to get Julian dayno
MS0Date	n	Add to Microsoft date to get a J dayno
Linux0DateTime	n	Add to Linux-style date to get a J dayno
toDayNo	v	Extends verb "todayno" to handle time
toDateTime	v	Extends verb "todate" to handle time
toJulian	v	Converts J day number to Julian day number
fromJulian	v	Converts Julian day number to J day number
tsPlus	v	Adds time (y) to timestamp (x)
tsMinus	v	Subtract time (y) from timestamp (x)
daysDiff	v	Difference in days from timestamp y to timestamp x
tsDiff	v	Time periods elapsed <Y M D H m s> from timestamp y to timestamp x
fmtDate	v	Format a date in a given format
fmtTime	v	Format a time (in seconds) in a given format.
fmtDateTime	v	Formats combined date and time strings

J0Date

J0Date (n) Add to J's dayno to get Julian dayno

Note that for astronomical use the start of a Julian day
is noon so for an accurate representation of a Julian day/time
combination 2378496.5 should be added instead.

MS0Date

MS0Date (n) Add to Microsoft date to get a J dayno

Note that the first date supported by Microsoft Excel is 1900 1 1
but dates between 1900 1 1 and 1900 1 28 will not convert properly
because Excel incorrectly denotes 1900 as a leap year,
http://support.microsoft.com/kb/214326

Linux0DateTime

Linux0DateTime (n) Add to Linux-style date to get a J dayno

Example use:

   1 tsrep (1e3*1682521200)+tsrep 6{.todate Linux0DateTime_rgsdatetime_
2023 4 26 15 0 0

Here, 1682521200 is an example linux epoch.

toDayNo

toDayNo (v) Extends verb "todayno" to handle time

eg: toDayNo 6!:0 ''
result: numeric array as J day numbers, decimals represent time
y is: numeric array in date/time format specified by x
x is: optional boolean specifying input format. Default 0.
     0 : date/time format <yyyy mm dd hh mm ss.sss>
     1 : date/time format <yyyymmdd.hhmmss.sss>
Dates before 1800 1 1 are not supported

toDateTime

toDateTime (v) Extends verb "todate" to handle time

eg: 1 toDateTime toDayNo 6!:0 ''
result: numeric array in date/time format specified by x
y is: array of J day numbers
x is: optional boolean specifying output format. Default 0.
     0 : date/time format <yyyy mm dd hh mm ss.sss>
     1 : date/time format <yyyymmdd.hhmmss.sss>
Dates before 1800 1 1 are not supported

toJulian

toJulian (v) Converts J day number to Julian day number

eg: toJulian toDayNo 6!:0 ''
Dates before 1800 1 1 are not supported
Add another 0.5 to get true Julian Day number where noon is
regarded as the "start" of the day.

fromJulian

fromJulian (v) Converts Julian day number to J day number

eg: fromJulian toJulian toDayNo 6!:0 ''
Dates before 1800 1 1 are not supported

tsPlus

tsPlus (v) Adds time (y) to timestamp (x)

eg: 2009 2 28 20 30 0 tsPlus 5 0 0     NB. add 5 hours to timestamp
eg: 2009 2 28 20 30 0 tsPlus 34 5 0 0  NB. add 34 days, 5 hours to timestamp
result: array of resulting numeric timestamp(s) in <Y M D h m s> format
y is: array of numeric time(s) to add to x. Format: [[[[[Y] M] D] h] m] s
x is: array of numeric timestamps to add y to. Format: Y [M [D [h [m [s]]]]]

tsMinus

tsMinus (v) Subtract time (y) from timestamp (x)

eg: 2009 3 1 1 30 0 tsMinus 5 0 0   NB. subtract 5 hours from timestamp
result: array of resulting numeric timestamp(s) in <Y M D h m s> format
y is: array of numeric time(s) to subtract from x. Format: [[[[[Y] M] D] h] m] s
x is: array of numeric timestamps to subtract y from. Format: Y [M [D [h [m [s]]]]]

daysDiff

daysDiff (v) Difference in days from timestamp y to timestamp x

form: endtimestamp daysDiff starttimestamp
result: numeric array of time difference for x-y in <Days.fraction of days> format
y is: numeric start date,time in <Y M D h m s> format
x is: numeric end date,time in <Y M D h m s> format

tsDiff

tsDiff (v) Time periods elapsed <Y M D H m s> from timestamp y to timestamp x

form: endtimestamp tsDiff starttimestamp
result: numeric array of time difference for x-y in <Y M D h m s> format
y is: numeric start date,time in <Y M D h m s> format
x is: numeric end date,time in <Y M D h m s> format

fmtDate

fmtDate (v) Format a date in a given format

eg: '\Date is: DDDD, D MMM, YYYY' fmtDate toDayNumber 6!:0''
result: formated date string (or array of boxed, formated date strings)
y is: numeric array of dates given as Day Numbers
x is: optional format string specifing format of result
     Use the following codes to specify the date format:
     D: 1   DD: 01   DDD: Sun   DDDD: Sunday
     M: 1   MM: 01   MMM: Jan   MMMM: January
            YY: 09              YYYY: 2009
    To display any of the letters (DMY) that are codes,
    "escape" them with '\'

fmtTime

fmtTime (v) Format a time (in seconds) in a given format.

eg: 'Ti\me i\s: hh:mm:ss' fmtTime 86400 * 1|toDayNumber 6!:0 ''
result: formated time string (or array of boxed, formated time strings)
y is: numeric array of times given as time in seconds since start of the day
x is: optional format string specifing format of result
     Use the following codes to specify the date format:
     days ("d"), hours ("h"), minutes ("m"), seconds ("s"),
     fractions of a second ("c"), or AM/PM designator ("p"):
    d: 1    h: 1    m: 1    s: 1      c: 1       p: a
           hh: 01  mm: 01  ss: 01    cc: 01     pp: am
                          sss: 1.2  ccc: 001
    If no "p" designator is present, 24 hour format is used.
    To display any of the letters (dhmscp) that are codes,
    "escape" them with '\'

fmtDateTime

fmtDateTime (v) Formats combined date and time strings

Authors

Ric Sherlock

Some of the verbs in this script were derived from APL+Win functions written by Davin Church.

Suggestions for improvement/extensions and/or SVN contributions to the addon are welcome.