# date

Definition: | sequence s = date(bool bMsecs=false)
Description: | Return a sequence of length 8 as detailed below.
pwa/p2js: | Supported.
Comments: | The values in the sequence result are ordered to simplify sorting things into chronological order. The following constants (right hand column comments, as automatically defined in psym.e/syminit) can and should be used to make the code more readable.
                 { year,  -- 4 digit                            (DT_YEAR=1)
                  month,  -- January = 1                        (DT_MONTH=2)
                    day,  -- day of month, starting at 1        (DT_DAY=3)
                   hour,  -- 0 to 23                            (DT_HOUR=4)
                 minute,  -- 0 to 59                            (DT_MINUTE=5)
                 second,  -- 0 to 59                            (DT_SECOND=6)
        day of the week,  -- Monday = 1                         (DT_DOW=7)
     ( or  milliseconds,  -- 0 to 999                           (DT_MSEC=7) )
        day of the year}  -- January 1st = 1                    (DT_DOY=8)
Previous versions of date() returned years since 1900 in DT_YEAR and required +1900 to make it a normal 4-digit year. If you see a date such as 3918 then you need to remove the now-spurious addition of 1900 (after the date() call). The use of a named parameter when setting bMsecs to true is recommended, to make the intent clear and the code easier to read. If bMsecs is true, it returns a milliseconds value in place of the day of the week. You cannot get both milliseconds and day of the week returned in one call, but you can obtain the latter from day_of_week(). Note that the validation in timedate.e has been relaxed to accomodate this, but obviously it would still likely go wrong should you actually try to print a milliseconds value as a day of the week, not that format_timedate() ever does. [DEV] The value of msecs is currently always 0 on linux, but it should be a relatively simple matter to apply the same changes recently made to VM\pTime.e (see bitbucket) to pdate.e, namely use sys_clock_gettime instead of sys_time. You can also invoke date(DT_GMT) which returns the GMT (same as UTC) time, irrespective of location, with milliseconds. See format_timedate() for conversion of dates to human-readable strings.
Example: |
    now = date()
    -- now has: {2013,3,24,23,47,38,6,83}
    -- i.e. Friday March 24, 2013 at 11:47:38pm, day 83 of the year
Implementation: | See builtins\pdate.e (an autoinclude) for details of the actual implementation.
See Also: | day_of_week, timedate, format_timedate, time
Technicalia | As of version 0.8.1, [DT_DOW] is now 1..7 (Mon..Sun) [was Sun..Sat], bringing it into line with ISO 8601, and the earlier ISO 2015. Obviously this may require changes to some legacy code.