This first edition was written for Lua 5.0. While still largely relevant for later versions, there are some differences.
The third edition targets Lua 5.2 and is available at Amazon and other bookstores.
By buying the book, you also help to support the Lua project.


22.1 – Date and Time

Two functions, time and date, do all date and time queries in Lua.

The time function, when called without arguments, returns the current date and time, coded as a number. (In most systems, that number is the number of seconds since some epoch.) When called with a table, it returns the number representing the date and time described by the table. Such date tables have the following significant fields:

yeara full year
month01-12
day01-31
hour01-31
min00-59
sec00-59
isdsta boolean, true if daylight saving

The first three fields are mandatory; the others default to noon (12:00:00) when not provided. In a Unix system (where the epoch is 00:00:00 UTC, January 1, 1970) running in Rio de Janeiro (which is three hours west of Greenwich), we have the following examples:

    -- obs: 10800 = 3*60*60 (3 hours)
    print(os.time{year=1970, month=1, day=1, hour=0})
      --> 10800
    print(os.time{year=1970, month=1, day=1, hour=0, sec=1})
      --> 10801
    print(os.time{year=1970, month=1, day=1})
      --> 54000   (obs: 54000 = 10800 + 12*60*60)

The date function, despite its name, is a kind of a reverse of the time function: It converts a number representing the date and time back to some higher-level representation. Its first parameter is a format string, describing the representation we want. The second is the numeric date-time; it defaults to the current date and time.

To produce a date table, we use the format string "*t". For instance, the following code

    temp = os.date("*t", 906000490)
produces the table
    {year = 1998, month = 9, day = 16, yday = 259, wday = 4,
     hour = 23, min = 48, sec = 10, isdst = false}
Notice that, besides the fields used by os.time, the table created by os.date also gives the week day (wday, 1 is Sunday) and the year day (yday, 1 is January 1).

For other format strings, os.date formats the date as a string, which is a copy of the format string where specific tags are replaced by information about time and date. All tags are represented by a `%´ followed by a letter, as in the next examples:

    print(os.date("today is %A, in %B"))
      --> today is Tuesday, in May
    print(os.date("%x", 906000490))
      --> 09/16/1998
All representations follow the current locale. Therefore, in a locale for Brazil-Portuguese, %B would result in "setembro" and %x in "16/09/98".

The following table shows each tag, its meaning, and its value for September 16, 1998 (a Wednesday), at 23:48:10. For numeric values, the table shows also their range of possible values:

%aabbreviated weekday name (e.g., Wed)
%Afull weekday name (e.g., Wednesday)
%babbreviated month name (e.g., Sep)
%Bfull month name (e.g., September)
%cdate and time (e.g., 09/16/98 23:48:10)
%dday of the month (16) [01-31]
%Hhour, using a 24-hour clock (23) [00-23]
%Ihour, using a 12-hour clock (11) [01-12]
%Mminute (48) [00-59]
%mmonth (09) [01-12]
%peither "am" or "pm" (pm)
%Ssecond (10) [00-61]
%wweekday (3) [0-6 = Sunday-Saturday]
%xdate (e.g., 09/16/98)
%Xtime (e.g., 23:48:10)
%Yfull year (1998)
%ytwo-digit year (98) [00-99]
%%the character `%´

If you call date without any arguments, it uses the %c format, that is, complete date and time information in a reasonable format. Note that the representations for %x, %X, and %c change according to the locale and the system. If you want a fixed representation, such as mm/dd/yyyy, use an explicit format string, such as "%m/%d/%Y".

The os.clock function returns the number of seconds of CPU time for the program. Its typical use is to benchmark a piece of code:

    local x = os.clock()
    local s = 0
    for i=1,100000 do s = s + i end
    print(string.format("elapsed time: %.2f\n", os.clock() - x))