# adjust_timedate

Definition: | include builtins\timedate.e timedate td = adjust_timedate(timedate 1 td, atom delta)
Description: | returns a timedate adjusted by the specified delta in seconds.
pwa/p2js: | Supported.
Comments: | The delta parameter is normally the result of a call to timedelta(). If the timedate has a timezone with a daylight savings rule, it automatically toggles on or off as the date crosses the start and end dates, with the appropriate (additional) time shift. While the day of year is automatically recalculated, note however this routine assumes that td[DT_DOW] is actually td[DT_MSEC] and applies any fraction of a second in delta accordingly. Hence in some rare cases you may need to explicitly zero that field to prevent the seconds clocking over (or not). As per the example below, while format_timedate() does not actually use or believe the content of td[DT_DOW], you might need that commented out day_of_week() call, or similar, should you be using it directly. 1 The input td parameter is not actually immediately validated as a timedate, which can help with "normalising" nonsensical months and day 0 as shown in the last 3 lines below. While fairly obviously you would rarely want to literally ask for the 13th month, you might very well want month+/-1 or +/-6. A day of zero is also permitted (in/at the start of this specific routine only) to mean the last day of the previous month, removing any fuss over how many days there are in each month. Obviously y/13/0 translates to (y-1)/21/31, and similar. The td parameter is however fully validated after adjusting the year/month/day0 (only), so you cannot for example specify the 99th of January, since that sort of thing would no doubt mess up leap days, and rather than put say 300 hours directly in the td, that would want to go in the timedelta() instead.
Example: |
    include builtins\timedate.e
    timedate td = parse_date_string("1/1/2015",{"D/M/YYYY"})
    ?format_timedate(td,"Dddd, Mmmm dst, yyyy")
    -- displays "Thursday, January 1st, 2015"
    td = adjust_timedate(td,timedelta(days:=4))
    --td[DT_DOW] = day_of_week(td[DT_YEAR],td[DT_MONTH],td[DT_DAY])
    ?format_timedate(td,"Dddd, Mmmm dst, yyyy")
    -- displays "Monday, January 5th, 2015"
    --td = {2024,14,0,0,0,0,0,0} -- boom (typecheck error)
    td = adjust_timedate({2024,14,0,0,0,0,0,0},0) -- ok!
    ?td -- {2025,1,31,0,0,0,0,31} (trailing 31 is [DT_DOY], btw)
See Also: | timedate, the timedate type, timedelta, parse_date_string, format_timedate