# elapsed

Definition: | string res = elapsed(atom s, min_s=0, string fmt="") -- or -- string res = elapsed_short(atom s, min_s=0, string fmt="")
Description: | Convert a time in seconds to a human-readable string.
pwa/p2js: | Supported.
Comments: | Technically this is not part of timedate but a standalone autoinclude (builtins\pelapsed.e) s: a time in seconds to convert to a human-readable string. min_s: a value, if non-zero, below which "" should be returned. fmt: optional extra formatting for non-"" results, eg " (%s)" would add/also omit the brackets in the [non-zero-min_s] "" case. This is a trivial routine designed for general purpose use/approximations; for more precise timings, such as benchmark results, sprintf("%3.2fs",s) is probably more appropriate. A type check error occurs if s exceeds 100 billion years (probably fixable, but left as is to catch bad input). The short form returns a string in the format (([minus][N year[s], ][N week[s], ][N day[s], ]|[-])[N:[0]]N:[0]N|[-]Ns) For long form results, see Examples below. To explain that short form value more explicitly: if the result contains no ':', it is seconds (and has a trailing s), eg "3s" if the result contains one ':', it is minutes:seconds (':' at [-3]), eg "2:30" if the result contains two ':', it is hours:minutes:seconds (':' at [-6,-3]), eg "2:30:00" (if you want two and a half hours to appear as "2:30", chop 3 chars off the result!) if required, the result is prefixed with "y year[s]", "w week[s]", and "d day[s]", ie in longhand, see technicalia. Negative year, week, and day values are prefixed with "minus ", negative hours/mins/secs with (just the one) "-". Neither routine makes any attempt to express duration in months, decades, centuries, or millenia.
Example: |
    procedure ees(sequence tests)
        for i=1 to length(tests) do
            atom s = tests[i]
            printf(1,"%50s vs %s\n",{elapsed(s),elapsed_short(s)})
        end for
    end procedure
    ees({12.34,120,1234,123456,120*60,60*60*24*364,60*60*24*364-1,60*60*24*365})

    -- Output, comparing std vs short forms:
    --                                           12.3s vs 12s
    --                                       2 minutes vs 2:00
    --                              20 minutes and 34s vs 20:34
    --             1 day, 10 hours, 17 minutes and 36s vs 1 day, 10:17:36
    --                                         2 hours vs 2:00:00
    --                                        52 weeks vs 52 weeks
    --  51 weeks, 6 days, 23 hours, 59 minutes and 59s vs 51 weeks, 6 days, 23:59:59
    --                                          1 year vs 1 year
Technicalia | Note the duration in seconds passed in as an argument contains absolutely no notion whatsoever of any leap years, when the last one was, when the next one might be, or any indication of which end of whenever that duration starts and ends that any such would apply, if any, and hence any years are simply calculated as exactly 365 days each. Using 365.25 is no better, and risks making some things quite glaringly 6/12/18 hours out. Likewise this routine cannot assume months of 28/29/30/31 days, and using (say) 365[or 366]/12 would again give some very strange results. Obviously you could probably do something a whole lot better (in terms of months and years) when presented with a pair of timedate values, but that is not what these two routines get given.