# timedelta

Definition: | include builtins\timedate.e atom delta = timedelta(atom weeks=0, days=0, hours=0, minutes=0, seconds=0, milliseconds=0, microseconds=0)
Description: | Returns a duration of time expressed in seconds and fractions of a second (idea cribbed from python)
pwa/p2js: | Supported.
Comments: | The result is intended to be used as a parameter to adjust_timedate(). The parameters are expected to be named: while 7 hours and 30 minutes could legally be defined using `timedelta(0,0,7,30[,0,0,0])`, it is recommended that the far more readable `timedelta(hours:=7, minutes:=30)` or `timedelta(hours:=7.5)` be used instead. Fairly obviously, -7000 hours is just as valid as +7000 hours, as is +10 weeks -3 days (together), in other words there is no and cannot be any validation of "sensible" ranges or matching "signedness" of any parameters, except perhaps for atoms that are not and do not turn into inf or nan, but even that’s not attempted or tested.
Example: |
    include builtins\timedate.e
    atom fourdays = timedelta(days:=4)
    timedate td = parse_date_string("1/8/2016",{"D/M/YYYY"})
    ?format_timedate(td,"Dddd, Mmmm dth, yyyy")                 -- displays "Monday, August 1st, 2016"
    td = adjust_timedate(td,fourdays)
    ?format_timedate(td,"Dddd, Mmmm dth, yyyy")                 -- displays "Friday, August 5th, 2016"
    td = adjust_timedate(td,-fourdays)
    ?format_timedate(td,"Dddd, Mmmm dth, yyyy")                 -- displays "Monday, August 1st, 2016"
See Also: | timedate, adjust_timedate, parse_date_string, format_timedate, elapsed
Technicalia | I considered adding a years parameter, but there would be no way to know whether it should be multiplied by 365, 366, 365.25, or something else, and besides, it is perfectly simple to get timedelta(days:=365) [or whatever] directly and play with that. The parameters are all defined as atoms to allow huge and/or fractional values to be passed. 1,000 milliseconds equal 1 second and 1,000 microseconds equal 1 millisecond (and 1,000,000 microseconds equal 1 second) - probably only useful in delta*bignumber cases. Using seconds to express timedeltas, as opposed to separate years/days/etc, imposes some minor accuracy limitations: timedeltas up to one year should be accurate to within one microsecond (10-6s) or better, timedeltas up to one thousand years should be accurate to within one millisecond (10-3s) or better, timedeltas up to one million years should be accurate to within one second or better. timedeltas up to one billion years should be accurate to within 15 minutes or better. timedeltas up to the age of the universe should be accurate to within 4 hours or better. Obviously that can almost certainly be completely ignored, for each and every possible practical purpose. Fairly obviously, I should hope, invoking `timedelta(seconds:=s)` is a rather pointless exercise, as is the perfectly legal but otherwise completely useless `timedelta()`, as they simply return s unaltered or 0 respectively. timedeltas have no notion of and will account for neither leap years nor leap seconds; an application programmer wishing to alter dates by more than 4 weeks is advised to take care of any whole months/years separately and manually, perhaps with a loop to adjust month by 12 and year by 1 until month is between 1 and 12, probably requiring standard/leap fiddles for days near the end of the month, but days and below via a timedelta, and anything like first or last Thursday of the month should probably not be using this routine at all. timedeltas have no notion of and will account for neither general relativity nor worm holes; passengers travelling near the speed of light or passing through time portals should avoid attempting to apply timedeltas to incompatible timeframes. For example, if you leave on Friday and arrive last Monday, by Tuesday the time of your departure has not become Saturday, however if last Thursday you jump back to next Sunday then you are two days older than everyone else, despite never having experienced Saturday, which should by rights make you one day younger.