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

	Programming in Lua
	Part III. The Standard Libraries Chapter 22. The Operating System Library

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:

year	a full year
month	01-12
day	01-31
hour	00-23
min	00-59
sec	00-59
isdst	a 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)

    {year = 1998, month = 9, day = 16, yday = 259, wday = 4,
     hour = 23, min = 48, sec = 10, isdst = false}

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

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:

%a	abbreviated weekday name (e.g., Wed)
%A	full weekday name (e.g., Wednesday)
%b	abbreviated month name (e.g., Sep)
%B	full month name (e.g., September)
%c	date and time (e.g., 09/16/98 23:48:10)
%d	day of the month (16) [01-31]
%H	hour, using a 24-hour clock (23) [00-23]
%I	hour, using a 12-hour clock (11) [01-12]
%M	minute (48) [00-59]
%m	month (09) [01-12]
%p	either "am" or "pm" (pm)
%S	second (10) [00-61]
%w	weekday (3) [0-6 = Sunday-Saturday]
%x	date (e.g., 09/16/98)
%X	time (e.g., 23:48:10)
%Y	full year (1998)
%y	two-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))

Copyright © 2003–2004 Roberto Ierusalimschy. All rights reserved.