LuaDate v2

To Load the module call local date = require"date" in your script. Make sure Lua can find the source file date.lua. No global table date will be created. Use the metamethod __call to construct a dateObject see example below:

local date = require "date"
-- prints all FRIDAY the 13TH dates between year 2000 and 2010
for i = 2000, 2010 do
        -- year jan 1
        x = date(i, 1, 1)
        -- from january to december
        for j = 1, 12 do
                -- set date to 13, check if friday
                if x:setmonth(j, 13):getweekday() == 6 then
                        print(x:fmt("%A, %B %d %Y"))
                end
        end
end

--- OUTPUT ---
--> Friday, October 13 2000
--> Friday, April 13 2001
--> Friday, July 13 2001
--> Friday, September 13 2002
--> Friday, December 13 2002
--> Friday, June 13 2003
--> Friday, February 13 2004
--> Friday, August 13 2004
--> Friday, May 13 2005
--> Friday, January 13 2006
--> Friday, October 13 2006
--> Friday, April 13 2007
--> Friday, July 13 2007
--> Friday, June 13 2008
--> Friday, February 13 2009
--> Friday, March 13 2009
--> Friday, November 13 2009
--> Friday, August 13 2010

2. Limits

This module does not recognize leap seconds.
It assumes that a day has exactly 24*60*60 seconds.
The Lua number must be a double C data type
This module supports dates that are greater than Mon Jan 01 1000000 BCE 00:00:00 and less than Mon Jan 01 1000001 00:00:00.
see Local time support for local time limts

3. Local time support

This module also supports local time. Local Time is;

Local = UTC + bias

The bias is time zone offset plus the daylight savings if in effect. The bias is retrieve using the Lua function os.date and os.time. It assumes that the Lua function os.time returns the number of seconds since the start time (called "epoch"). If the time value is outside the allowable range of times, usually

Jan 01 1970
      00:00:00

to Jan 19 2038 03:14:07 the bias will be retrieve using the equivalent year inside the allowable range. Two years are considered to equivalent if they have the same leap year ness and starting weekday.

The function that needs local time support are date(true) (get the current UTC time), date(false) (get the current local time), date(num_time), dateObj:getbias(), dateObject:fmt(str) (when str has a '%Z' or '%z'),

4. Parsable date value

Parsable date value is a lua value that can be converted to a dateObject. This value must be num_time or tbl_date or str_date or bool_now argument describe in the date library __call method.

5. Parsable month value

If a function needs a month value it must be a string or a number. If the value is a string, it must be the name of the month full or abbreviated. If the value is a number, that number must be 1-12 (January-December). see table below

Table 1.

Index	Abbreviation	Full Name
1	Jan	January
2	Feb	February
3	Mar	March
4	Apr	April
5	May	May
6	Jun	June
7	Jul	July
8	Aug	August
9	Sep	September
10	Oct	October
11	Nov	November
12	Dec	December

If the value does not represent month, that is equivalent to passing a nil value.

6. date

The date module.

6.1. Function(s) of date

diff | epoch | isleapyear ₃

6.1.1. diff

Subtract the date and time value of two dateObject and returns the resulting dateObject.

Syntax

date.diff(var_date1, var_date2)

Arguments

var_date1: Required. a dateObject or parsable date value
var_date2: Required. a dateObject or parsable date value

Returns

Success	The resulting dateObject
Failure	nil.

Example

-- get the days between two dates
d = date.diff("Jan 7 1563", date(1563, 1, 2))
assert(d:spandays()==5)

6.1.2. epoch

Returns dateObject whose date and time value is the Operating System epoch.

Syntax

date.epoch()

Returns

Success	The resulting dateObject
Failure	nil.

Example

assert(date.epoch()==date("jan 1 1970"))

6.1.3. getcenturyflip

Returns the current global setting for centuryflip.

Syntax

local centuryflip = date.getcenturyflip()

Arguments

none

Returns

The currrent global centuryflip value.

Remarks

centuryflip is a global setting and hence should only be set by an application, never by a library.

Example

local centuryflip = date.getcenturyflip()

6.1.4. isleapyear

Check if a number or dateObject is a leapyear.

Syntax

date.isleapyear(var_year)

Arguments

var_year: a number or dateObject or parsable date value

Returns

true if var_year leap year. false if var_year not leap year.

Remarks

A leap year in the Gregorian calendar is defined as a year that is evenly divisible by four, except if it is divisible by 100; however, years that are divisible by 400 are leap years.

Example

d = date(1776, 1, 1)
assert(date.isleapyear(d))
assert(date.isleapyear(d:getyear()))
assert(date.isleapyear(1776))

6.1.5. setcenturyflip

Sets the global value for centuryflip. Century flip determines how 2-digit years are interpreted when parsing string values. Any value smaller than centuryflip will be considered 20xx, and values greater or equal will become 19xx.

The default value is 0, so all 2 digit years are considered 19xx.

Syntax

date.setcenturyflip(century_flip)

Arguments

century_flip: a number from 0 to 100

Returns

Nothing.

Remarks

centuryflip is a global setting and hence should only be set by an application, never by a library.

Example

date.setcenturyflip(0)
assert(date("01-01-00")==date(1900,01,01))
assert(date("01-01-50")==date(1950,01,01))
assert(date("01-01-99")==date(1999,01,01))
date.setcenturyflip(100)
assert(date("01-01-00")==date(2000,01,01))
assert(date("01-01-50")==date(2050,01,01))
assert(date("01-01-99")==date(2099,01,01))
date.setcenturyflip(50)
assert(date("01-01-00")==date(2000,01,01))
assert(date("01-01-49")==date(2049,01,01))
assert(date("01-01-50")==date(1950,01,01))
assert(date("01-01-99")==date(1999,01,01))

6.2. Method(s) of date

__call ₁

6.2.1. __call

Construct a dateObject. It has 3 method of constructing a date object.

3 or more arguments - int_year, var_month, int_day, num_hour, num_min, num_sec, int_ticks
1 argument - num_time or tbl_date or str_date or bool_now
no argument - same as date(false)

This is a metamethod of date. Remember date:__call(...) is the same as date(...).

Syntax

date(num_time)

date(tbl_date)

date(str_date)

date(bool_now)

date(int_year, var_month, int_day, [num_hour], [num_min], [num_sec], [int_ticks])

Arguments

num_time: Required number value. Represents the number of seconds in Universal Coordinated Time between the specified value and the System epoch.

tbl_date

Required table value. The constructor will look for the value of this key:

year - an integer, the full year, for example, 1969. Required if month and day is given
month - a parsable month value. Required if year and day is given
day - an integer, the day of month from 1 to 31. Required if year and month is given
hour - a number, hours value, from 0 to 23, indicating the number of hours since midnight. (default = 0)
min - a number, minutes value, from 0 to 59. (default = 0)
sec - a number, seconds value, from 0 to 59. (default = 0)

Time (hour or min or sec or msec) must be supplied if date (year and month and day) is not given, vice versa.

str_date

Required string value. It must have number/words representing date and/or time. Use commas and spaces as delimiters. Strings enclosed by parenthesis is treated as a comment and is ignored, these parentheses may be nested. The stated day of the week is ignored whether its correct or not. A string containing an invalid date is an error. For example, a string containing two years or two months is an error. Time must be supplied if date is not given, vice versa.

Time Format. Hours, minutes, and seconds are separated by colons, although all need not be specified. "10:", "10:11", and "10:11:12" are all valid. If the 24-hour clock is used, it is an error to specify "PM" for times later than 12 noon. For example, "23:15 PM" is an error.

Time Zone Format. First character is a sign "+" (east of UTC) or "-" (west of UTC). Hours and minutes offset are separated by colons:

assert( date("Jul 27 2006 03:56:28 +2:00") == date(2006,07,27,1,56,28))

Another format is [sign][number] If [number] is less than 24, it is the offset in hours e.g. "-10" = -10 hours. Otherwise it is the offset in houndred hours e.g. "+75" = "+115" = +1.25 hours.

assert(date("Jul 27 2006 -75 ") == date(2006,07,27,1,15,0))
assert(date("Jul 27 2006 -115") == date(2006,07,27,1,15,0))
assert(date("Jul 27 2006 +10 ") == date(2006,07,26,14,0,0))
assert(date("Jul 27 2006 +2  ") == date(2006,07,26,22,0,0))

Standard timezone GMT, UTC, EST, EDT, CST, CDT, MST, MDT, PST, PDT are supported.

assert(date("Jul 27 2006 GMT") == date(2006,07,27,0,0,0))
assert(date("Jul 27 2006 UTC") == date(2006,07,27,0,0,0))
assert(date("Jul 27 2006 EST") == date(2006,07,27,5,0,0))
assert(date("Jul 27 2006 EDT") == date(2006,07,27,4,0,0))
assert(date("Jul 27 2006 CST") == date(2006,07,27,6,0,0))
assert(date("Jul 27 2006 CDT") == date(2006,07,27,5,0,0))
assert(date("Jul 27 2006 MST") == date(2006,07,27,7,0,0))
assert(date("Jul 27 2006 MDT") == date(2006,07,27,6,0,0))
assert(date("Jul 27 2006 PST") == date(2006,07,27,8,0,0))
assert(date("Jul 27 2006 PDT") == date(2006,07,27,7,0,0))

Date Format. Short dates can use either a "/" or "-" date separator, but must follow the month/day/year format. 2 digit years are interpreted according to the global centuryflip setting.

assert(date("02-03-04")==date(1904,02,03))
assert(date("12/25/98")==date(1998,12,25))

Long dates of the form "July 10 1995" can be given with the year, month, and day in any order, and the year in 2-digit or 4-digit form. If you use the 2-digit form, the year must be greater than or equal to 70.

assert(date("Feb-03-04")==date(1904,02,03))
assert(date("December 25 1998")==date(1998,12,25))

Follow the year with BC or BCE to indicate that the year is before common era.

assert(date("Feb 3 0003 BC")==date(-2,02,03))
assert(date("December 25 0001 BC")==date(0,12,25))

Supported ISO 8601 Formats.

YYYY-MM-DD

where YYYY is the year, MM is the month of the year, and DD is the day of the month.

assert(date("2000-12-31")==date(2000,12,31))
assert(date(" 20001231 ")==date(2000,12,31)) -- Compact version

YYYY-DDD

where YYYY is the year, DDD is the day of the year.

assert(date("1995-035")==date(1995,02,04))
assert(date("1995035 ")==date(1995,02,04)) -- Compact version

YYYY-WDD-D

where YYYY is the year, DD is the week of the year, D is the day of the week.

assert(date("1997-W01-1")==date(1996,12,30))
assert(date("  1997W017")==date(1997,01,05)) -- Compact version

DATE HH:MM:SS.SSS

Where DATE is the date format discuss above, HH is the hour, MM is the miute, SS.SSS is the seconds (fraction is optional).

assert(date("1995-02-04 24:00:51.536")==date(1995,2,5,0,0,51.536))
assert(date("1976-W01-1 12:12:12.123")==date(1975,12,29,12,12,12.123))
assert(date("1995-035 23:59:59.99999")==date(1995,02,04,23,59,59.99999))
-- Compact version separated by latin capital letter T
assert(date("  19950205T000051.536  ")==date(1995,2,5,0,0,51.536))
assert(date("  1976W011T121212.123  ")==date(1975,12,29,12,12,12.123))
assert(date(" 1995035T235959.99999  ")==date(1995,02,04,23,59,59.99999))

DATE TIME +HH:MM, DATE TIME -HHMM, DATE TIME Z,

Where DATE and TIME is the dateand time format discuss above. First character is a sign "+" (east of UTC) or "-" (west of UTC). HH and MM is Hours and minutes offset. The Z stands for the zero offset.

assert(date("1976-W01-1 12:00Z     ")==date(1975,12,29,12))
assert(date("1976-W01-1 13:00+01:00")==date(1975,12,29,12))
assert(date("1976-W01-1 0700-0500  ")==date(1975,12,29,12))

bool_now: Required boolean value. if bool_now is false it returns the current local date and time. if bool_now is true it returns the current UTC date and time.

int_year: Required interger value. The year value.
var_month: Required. A parsable month value.
int_day: Required interger value. The day of month.
num_hour: Optional number value. Equal to the hours value. The default value is 0
num_min: Optional number value. Equal to the minutes value. The default value is 0
num_sec: Optional number value. Equal to the seconds value. The default value is 0
int_ticks: Optional interger value. Equal to the ticks value. The default value is 0

Returns

Success	the new dateObject
Failure	nil.

Example

a = date(2006, 8, 13)   assert(a == date("Sun Aug 13 2006"))
b = date("Jun 13 1999") assert(b == date(1999, 6, 13))
c = date(1234483200)    assert(c == date("Feb 13 2009"))
d = date({year=2009, month=11, day=13, min=6})
        assert(d == date("Nov 13 2009 00:06:00"))
e = date() assert(e)

7. dateObject

dateObject is a table containing date and time value. It has a metatable for manipulation and retrieval of dates and times. Use the __call method of date to construct a dateObject.

7.1. How Date and Time are stored in `dateObject`

Time is stored in dateObject as Ticks or Day Fraction. Date is stored in dateObject as Day Number. Ticks is time unit per seconds. For example, if the tick unit is 1000000. 0.25 seconds is equivalent to 250000 ticks (0.25*1000000). Day number, is the number days since the epoch, which is January 1, 0001 AD. Example.

dobj = date("15:49:59.3669")

If the tick unit is 1000000, dobj store this time as 56999366900 ticks and 0 days.

((((15*60)+49)*60)+59.3669)*1000000 == 56999366900

Example Date and Time:

dobj = date("Jan-5-0001 10:30:15")

If the tick unit is 1000000, dobj store this date and time as 37815000000 ticks and 4 days. 4 days becuase:

Day#	Date
0	Jan 1 0001
1	Jan 2 0001
2	Jan 3 0001
3	Jan 4 0001
4	Jan 5 0001
5	Jan 6 0001
...	...

The default tick unit is 1000000 (micro-second-ticks)

7.2. Supported MetaMethods

The a < b operation.: Returns true if date value of a is smaller/older than date value of b. a > b is equivalent to b < a.
The a <= b operation.: Returns true if date value of a is smaller/older than or equal to the date value of b. a >= b is equivalent to b <= a.
The a == b operation.: Returns true if date value of a is equal equal to the date value of b. a ~= b is equivalent to not (a == b).
The a .. b operation.: Equivalent to tostring(a) .. tostring(b).
The a - b operation.: Subtract the date and time value of b from date and time value of a.
The a + b operation.: Add the date and time value of b to date and time value of a.

a and b must be a parsable date value or an error rises

a = date(1521,5,2)
b = a:copy():addseconds(0.001)

assert((a - b):spanseconds() == -0.001)
assert((a + b) == (b + a))
assert(a == (b - date("00:00:00.001")) )
assert(b == (a + date("00:00:00.001")) )

b:addseconds(-0.01)

assert(a >  b and b <  a)
assert(a >= b and b <= a)
assert(a ~= b and (not(a == b)))

a = b:copy()

assert(not (a >  b and b <  a))
assert(a >= b and b <= a)
assert(a == b and (not(a ~= b)))

assert((a .. 565369) == (b .. 565369))
assert((a .. "????") == (b .. "????"))

7.3. Method(s) of dateObject

7.3.1. adddays

Add days in dateObject

Syntax

dateObject:adddays(int_days)

Arguments

int_days: Required integer value. Days to add.

Returns

Success	reference to the adjusted dateObject
Failure	nil.

Remarks

If the value is negative, the adjusted dateObject will be earlier.

Example

a = date(2000,12,30)
b = date(a):adddays(3)
c = date.diff(b,a)
assert(c:spandays() == 3)

7.3.2. addhours

Add hours in dateObject

Syntax

dateObject:addhours(num_hours)

Arguments

num_hours: Required number value. Hours to add.

Returns

Success	reference to the adjusted dateObject
Failure	nil.

Remarks

If the value is negative, the adjusted dateObject will be earlier.

Example

a = date(2000,12,30)
b = date(a):addhours(3)
c = date.diff(b,a)
assert(c:spanhours() == 3)

7.3.3. addminutes

Add minutes in dateObject

Syntax

dateObject:addminutes(num_minutes)

Arguments

num_minutes: Required number value. Minutes to add.

Returns

Success	reference to the adjusted dateObject
Failure	nil.

Remarks

If the value is negative, the adjusted dateObject will be earlier.

Example

a = date(2000,12,30)
b = date(a):addminutes(3)
c = date.diff(b,a)
assert(c:spanminutes() == 3)

7.3.4. addmonths

Add months in dateObject

Syntax

dateObject:addmonths(int_months)

Arguments

int_months: Required integer value. Months to add.

Returns

Success	reference to the adjusted dateObject
Failure	nil.

Remarks

If the value is negative, the adjusted dateObject will be earlier.

Example

a = date(2000,12,28):addmonths(3)
assert(a:getmonth() == 3)

7.3.5. addseconds

Add seconds in dateObject

Syntax

dateObject:addseconds(num_sec)

Arguments

num_sec: Required number value. Seconds to add.

Returns

Success	reference to the adjusted dateObject
Failure	nil.

Remarks

If the value is negative, the adjusted dateObject will be earlier.

Example

a = date(2000,12,30)
b = date(a):addseconds(3)
c = date.diff(b,a)
assert(c:spanseconds() == 3)

7.3.6. addticks

Add ticks in dateObject

Syntax

dateObject:addticks(num_ticks)

Arguments

num_ticks: Required number value. Ticks to add.

Returns

Success	reference to the adjusted dateObject
Failure	nil.

Remarks

If the value is negative, the adjusted dateObject will be earlier. For discussion about ticks see Section 7.1, “How Date and Time are stored in dateObject”.

Example

a = date(2000,12,30)
b = date(a):addticks(3)
c = date.diff(b,a)
assert(c:spanticks() == 3)

7.3.7. addyears

Add years in dateObject

Syntax

dateObject:addyears(int_years)

Arguments

int_years: Required integer value. Years to add.

Returns

Success	reference to the adjusted dateObject
Failure	nil.

Remarks

If the value is negative, the adjusted dateObject will be earlier.

Example

a = date(2000,12,30):addyears(3)
assert(a:getyear() == (2000+3))

7.3.8. copy

Returns a new date object having the same date and time value of dateObject

Syntax

dateObject:copy()

Example

a = date(2000,12,30)
b = a:copy()
assert(a==b)

7.3.9. fmt

Returns a formatted version of dateObject.

Syntax

dateObject:fmt(str_code)

Arguments

str_code

string value. The format string follows the same rules as the strftime standard C function.

Table 3. Format Spec

Spec	Description
'%a'	Abbreviated weekday name (Sun)
'%A'	Full weekday name (Sunday)
'%b'	Abbreviated month name (Dec)
'%B'	Full month name (December)
'%C'	Year/100 (19, 20, 30)
'%d'	The day of the month as a number (range 1 - 31)
'%g'	year for ISO 8601 week, from 00 (79)
'%G'	year for ISO 8601 week, from 0000 (1979)
'%h'	same as %b
'%H'	hour of the 24-hour day, from 00 (06)
'%I'	The hour as a number using a 12-hour clock (01 - 12)
'%j'	The day of the year as a number (001 - 366)
'%m'	Month of the year, from 01 to 12
'%M'	Minutes after the hour 55
'%p'	AM/PM indicator (AM)
'%S'	The second as a number (59, 20 , 01)
'%u'	ISO 8601 day of the week, to 7 for Sunday (7, 1)
'%U'	Sunday week of the year, from 00 (48)
'%V'	ISO 8601 week of the year, from 01 (48)
'%w'	The day of the week as a decimal, Sunday being 0
'%W'	Monday week of the year, from 00 (48)
'%y'	The year as a number without a century (range 00 to 99)
'%Y'	Year with century (2000, 1914, 0325, 0001)
'%z'	Time zone offset, the date object is assumed local time (+1000, -0230)
'%Z'	Time zone name, the date object is assumed local time
'%\b'	Year, if year is in BCE, prints the BCE Year representation, otherwise result is similar to "%Y" (1 BCE, 40 BCE) #
'%\f'	Seconds including fraction (59.998, 01.123) #
'%%'	percent character %
'%r'	12-hour time, from 01:00:00 AM (06:55:15 AM); same as "%I:%M:%S %p"
'%R'	hour:minute, from 01:00 (06:55); same as "%I:%M"
'%T'	24-hour time, from 00:00:00 (06:55:15); same as "%H:%M:%S"
'%D'	month/day/year from 01/01/00 (12/02/79); same as "%m/%d/%y"
'%F'	year-month-day (1979-12-02); same as "%Y-%m-%d"
'%c'	The preferred date and time representation; same as "%x %X"
'%x'	The preferred date representation, same as "%a %b %d %\b"
'%X'	The preferred time representation, same as "%H:%M:%\f"
'${iso}'	Iso format, same as "%Y-%m-%dT%T"
'${http}'	http format, same as "%a, %d %b %Y %T GMT"
'${ctime}'	ctime format, same as "%a %b %d %T GMT %Y"
'${rfc850}'	RFC850 format, same as "%A, %d-%b-%y %T GMT"
'${rfc1123}'	RFC1123 format, same as "%a, %d %b %Y %T GMT"
'${asctime}'	asctime format, same as "%a %b %d %T %Y"

Remarks

Only English names are supported

Example

d = date(1582,10,5)
assert(d:fmt('%D') == d:fmt("%m/%d/%y"))        -- month/day/year from 01/01/00 (12/02/79)
assert(d:fmt('%F') == d:fmt("%Y-%m-%d"))        -- year-month-day (1979-12-02)
assert(d:fmt('%h') == d:fmt("%b"))                      -- same as %b (Dec)
assert(d:fmt('%r') == d:fmt("%I:%M:%S %p"))     -- 12-hour time, from 01:00:00 AM (06:55:15 AM)
assert(d:fmt('%T') == d:fmt("%H:%M:%S"))        -- 24-hour time, from 00:00:00 (06:55:15)
assert(d:fmt('%a %A %b %B') == "Tue Tuesday Oct October")
assert(d:fmt('%C %d') == "15 05", d:fmt('%C %d'))

print(d:fmt[[
${iso} -- iso
${http} -- http
${ctime} -- ctime
${rfc850} -- rfc850
${rfc1123} -- rfc1123
${asctime} -- asctime
]])

Example (Prints the current date and time)

-- Prints the current date and time, including time zone
d = date(false);
print(d:fmt("Today is %c GMT%z"))
--> "Today is Tue Oct 31 2000 01:58:14 GMT-0330"

-- Prints the current date and time in ISO format including time zone
d = date(false);
print(d:fmt("Today is ${iso}%z"))
--> "Today is 2000-10-31T01:58:14-0330"

-- Prints the current date and time in ISO format, indicates UTC
d = date(true);
print(d:fmt("Today is ${iso}Z"))
--> "Today is 2000-10-31T05:28:14Z"

7.3.10. getbias

Assuming dateObject is a local time. Returns the time zone offset. Returns nil on failure.

Syntax

dateObject:getbias()

Example

a = date(2^16)
print(a:getbias())

7.3.11. getclockhour

Returns the hours value using a 12-hour clock in a dateObject.

Syntax

dateObject:getclockhour()

Example

a = date("10:59:59 pm")
assert(a:getclockhour()==10)

7.3.12. getdate

Returns the year, month, and day value in a dateObject.

Syntax

dateObject:getdate()

Example

a = date(1970, 1, 1)
y, m, d = a:getdate()
assert(y == 1970 and m == 1 and d == 1)

7.3.13. getday

Returns the day of month value in a dateObject

Syntax

dateObject:getday()

Example

d = date(1966, 'sep', 6)
assert(d:getday() == 6)

7.3.14. getfracsec

Returns the seconds after the minute (fractional) value in a dateObject.

Syntax

dateObject:getfracsec()

Example

d = date("Wed Apr 04 2181 11:51:06.996 UTC")
assert(d:getfracsec() == 6.996)

7.3.15. gethours

Returns the hours value in a dateObject

Syntax

dateObject:gethours()

Example

d = date("Wed Apr 04 2181 11:51:06 UTC")
assert(d:gethours() == 11)

7.3.16. getisoweekday

Returns the day of week (sunday=7, monday=1, ...saturday=6) in a dateObject.

Syntax

dateObject:getisoweekday()

Example

d = date(1970, 1, 1)
assert(d:getisoweekday() == 4)

7.3.17. getisoweeknumber

Returns the ISO 8601 week number (01 to 53) in a dateObject. Using the Year-WeekOfYear-DayOfWeek date system

Syntax

dateObject:getisoweeknumber()

Example

d = date(1975, 12, 29)
assert(d:getisoweeknumber() == 1)
assert(d:getisoyear() == 1976)
assert(d:getisoweekday() == 1)
d = date(1977, 1, 2)
assert(d:getisoweeknumber() == 53)
assert(d:getisoyear() == 1976)
assert(d:getisoweekday() == 7)

7.3.18. getisoyear

Returns the ISO 8601 year in a dateObject. Using the Year-WeekOfYear-DayOfWeek date system

Syntax

dateObject:getisoyear()

Example

d = date(1996, 12, 30)
assert(d:getisoyear() == 1997)
d = date(1997, 01, 05)
assert(d:getisoyear() == 1997)

7.3.19. getminutes

Returns the minutes after the hour value in a dateObject

Syntax

dateObject:getminutes()

Example

d = date("Wed Apr 04 2181 11:51:06 UTC")
assert(d:getminutes() == 51)

7.3.20. getmonth

Returns the month value in a dateObject

Syntax

dateObject:getmonth()

Example

d = date(1966, 'sep', 6)
assert(d:getmonth() == 9)

7.3.21. getseconds

Returns the seconds after the minute value in a dateObject

Syntax

dateObject:getseconds()

Example

d = date("Wed Apr 04 2181 11:51:06.123 UTC")
assert(d:getseconds() == 6)

7.3.22. getticks

Returns the ticks after the seconds value in a dateObject

Syntax

dateObject:getticks()

Remarks

For discussion about ticks see Section 7.1, “How Date and Time are stored in dateObject”.

Example

d = date("Wed Apr 04 2181 11:51:06.123 UTC")
assert(d:getticks() == 123000)

7.3.23. gettime

Returns the hours, minutes, seconds and ticks value in a dateObject.

Syntax

dateObject:gettime()

Example

a = date({hour=5,sec=.5,min=59})
h, m, s, t = a:gettime()
assert(t == 500000 and s == 0 and m == 59 and h == 5, tostring(a))

7.3.24. getweekday

Returns the day of week (sunday=1, monday=2, ...saturday=7) in a dateObject.

Syntax

dateObject:getweekday()

Example

d = date(1970, 1, 1)
assert(d:getweekday() == 5)

7.3.25. getweeknumber

Returns the week number value in a dateObject.

Syntax

dateObject:getweeknumber([int_wdaybase])

Arguments

int_wdaybase: Optional integer value. The starting day of week (1 for sunday, 2 for monday, ... 7 for saturday). If omitted the starting day of week is sunday.

Example

a = date("12/31/1972")
b,c = a:getweeknumber(), a:getweeknumber(2)
assert(b==53 and c==52)

7.3.26. getyear

Returns the year value in a dateObject

Syntax

dateObject:getyear()

Example

d = date(1965, 'jan', 0)
assert(d:getyear() == 1964)

7.3.27. getyearday

Returns the day of year (1-366) in a dateObject.

Syntax

dateObject:getyearday()

Example

d = date(2181, 1, 12)
assert(d:getyearday() == 12)

7.3.28. setday

Sets the day of month value in dateObject

Syntax

dateObject:setday(int_mday)

Arguments

int_mday: integer value. A numeric value equal to the day of month. The default value is the current day of month

Returns

Success	reference to the dateObject
Failure	nil.

Example

d = date(1966, 'july', 6)
d:setday(1)
assert(d == date("1966 july 1"))

7.3.29. sethours

Sets the hour value in dateObject

Syntax

dateObject:sethours(num_hour, num_min, num_sec, num_ticks)

Arguments

num_hour: number value. The hours value. The default value is the current hours value
num_min: number value. The minutes after the hours value. The default value is the current minutes value
num_sec: number value. The seconds after the minute value. The default value is the current seconds value
num_ticks: number value. The ticks after the second value. The default value is the current ticks value

Returns

Success	reference to the dateObject
Failure	nil.

Example

d = date(1984, 12, 3, 4, 39, 54)
d:sethours(1, 1, 1)
assert(d == date("1984 DEc 3 1:1:1"))

7.3.30. setisoweekday

Sets the ISO 8601 week number value in dateObject. Using the Year-WeekOfYear-DayOfWeek date system

Syntax

dateObject:setisoweekday(int_wday)

Arguments

int_wday: integer value. The day the week. The default value is the current week day

Returns

Success	reference to the dateObject
Failure	nil.

Example

d = date.isodate(1999, 52, 1)
d:setisoweekday(7)
assert(d == date(2000, 1, 02))

7.3.31. setisoweeknumber

Sets the ISO 8601 week number value in dateObject. Using the Year-WeekOfYear-DayOfWeek date system

Syntax

dateObject:setisoweeknumber(int_week, int_wday)

Arguments

int_week: integer value. The week value. The default value is the current week
int_wday: integer value. The day of the week. The default value is the current week day

Returns

Success	reference to the dateObject
Failure	nil.

Example

d = date(1999, 12, 27)
d:setisoweeknumber(51, 7)
assert(d == date(1999, 12, 26))

7.3.32. setisoyear

Sets the ISO 8601 year value in dateObject. Using the Year-WeekOfYear-DayOfWeek date system

Syntax

dateObject:setisoyear(int_year, int_week, int_wday)

Arguments

int_year: integer value. The year value. The default value is the current year
int_week: integer value. The week value. The default value is the current week
int_wday: integer value. The day of the week. The default value is the current week day

Returns

Success	reference to the dateObject
Failure	nil.

Example

d = date(1999, 12, 27)
d:setisoyear(2000, 1)
assert(d == date.isodate(2000,1,1))
assert(d:getyear() == 2000)
assert(d:getday() == 3)

7.3.33. setminutes

Sets the minutes value in dateObject

Syntax

dateObject:setminutes(num_min, num_sec, num_ticks)

Arguments

num_min: number value. The minutes after the value. The default value is the current minutes value
num_sec: number value. The seconds after the minute value. The default value is the current seconds value
num_ticks: number value. The ticks after the second value. The default value is the current ticks value

Returns

Success	reference to the dateObject
Failure	nil.

Example

d = date(1984, 12, 3, 4, 39, 54)
d:setminutes(59, 59, 500)
assert(d == date(1984, 12, 3, 4, 59, 59, 500))

7.3.34. setmonth

Sets the month value in dateObject

Syntax

dateObject:setmonth(var_month, int_mday)

Arguments

var_month: parsable month value. The default value is the current month
int_mday: integer value. The day of month. The default value is the current day of month

Returns

Success	reference to the dateObject
Failure	nil.

Example

d = date(1966, 'july', 6)
d:setmonth(1)
assert(d == date("6 jan 1966"))

7.3.35. setseconds

Sets the seconds after the minute value in dateObject

Syntax

dateObject:setseconds(num_sec, num_ticks)

Arguments

num_sec: number value. The seconds after the minute value. The default value is the current seconds value
num_ticks: number value. The ticks after the second value. The default value is the current ticks value

Returns

Success	reference to the dateObject
Failure	nil.

Example

d = date(1984, 12, 3, 4, 39, 54)
d:setseconds(59, date.ticks())
assert(d == date(1984, 12, 3, 4, 40))

7.3.36. setticks

Sets the ticks after the second value in dateObject

Syntax

dateObject:setticks(num_ticks)

Arguments

num_ticks: number value. The ticks after the second value. The default value is the current ticks value

Returns

Success	reference to the dateObject
Failure	nil.

Example

d = date(1984, 12, 3, 4, 39, 54)
d:setticks(444)
assert(d == date(1984, 12, 3, 4, 39, 54, 444))

7.3.37. setyear

Sets the year value in dateObject

Syntax

dateObject:setyear(int_year, var_month, int_mday)

Arguments

int_year: integer value. The year value. The default value is the current year
var_month: The month value. The default value is the current month
int_mday: integer value. The day of month. The default value is the current day of month

Returns

Success	reference to the dateObject
Failure	nil.

Example

d = date(1966, 'july', 6)
d:setyear(2000)
assert(d == date("jul 6 2000"))

7.3.38. spandays

Returns how many days the dateObject has

Syntax

dateObject:spandays()

Example

a = date(2181, "aPr", 4, 6, 30, 30, 15000)
b = date(a):adddays(2)
c = date.diff(b, a)
assert(c:spandays() == (2))

7.3.39. spanhours

Returns how many hours the dateObject has

Syntax

dateObject:spanhours()

Example

a = date(2181, "aPr", 4, 6, 30, 30, 15000)
b = date(a):adddays(2)
c = date.diff(b, a)
assert(c:spanhours() == (2*24))

7.3.40. spanminutes

Returns how many minutes the dateObject has

Syntax

dateObject:spanminutes()

Example

a = date(2181, "aPr", 4, 6, 30, 30, 15000)
b = date(a):adddays(2)
c = date.diff(b, a)
assert(c:spanminutes() == (2*24*60))

7.3.41. spanseconds

Returns how many seconds the dateObject has

Syntax

dateObject:spanseconds()

Example

a = date(2181, "aPr", 4, 6, 30, 30, 15000)
b = date(a):adddays(2)
c = date.diff(b, a)
assert(c:spanseconds() == (2*24*60*60))

7.3.42. spanticks

Returns how many ticks the dateObject has

Syntax

dateObject:spanticks()

Remarks

For discussion about ticks see Section 7.1, “How Date and Time are stored in dateObject”.

Example

a = date(2181, "aPr", 4, 6, 30, 30, 15000)
b = date(a):adddays(2)
c = date.diff(b, a)
assert(c:spanticks() == (2*24*60*60*1000000))

7.3.43. tolocal

Assuming dateObject is a utc time. Convert its date and time value to local time.

Syntax

dateObject:tolocal()

Example

a = date(2^16)
b = a:copy():tolocal();
print(a,b)

7.3.44. toutc

Assuming dateObject is a local time. Convert its date and time value to utc time.

Syntax

dateObject:toutc()

Example

a = date(2^16)
b = a:copy():toutc();
print(a,b)

8. History

v1 (2005): Binary module
v2 (2006): Lua module

9. Acknowledgement

http://alcor.concordia.ca/~gpkatch/gdate-method.html - Date calculation algorithms is based on this site.

LuaDate v2.2.1

Lua Date and Time module for Lua 5.x.

Jas Latrix

1. Introduction

2. Limits

3. Local time support

4. Parsable date value

5. Parsable month value

6. date

6.1. Function(s) of date

6.1.1. diff

6.1.2. epoch

6.1.3. getcenturyflip

6.1.4. isleapyear

6.1.5. setcenturyflip

6.2. Method(s) of date

6.2.1. __call

7. dateObject

7.1. How Date and Time are stored in dateObject

7.2. Supported MetaMethods

7.3. Method(s) of dateObject

7.3.1. adddays

7.3.2. addhours

7.3.3. addminutes

7.3.4. addmonths

7.3.5. addseconds

7.3.6. addticks

7.3.7. addyears

7.3.8. copy

7.3.9. fmt

7.3.10. getbias

7.3.11. getclockhour

7.3.12. getdate

7.3.13. getday

7.3.14. getfracsec

7.3.15. gethours

7.3.16. getisoweekday

7.3.17. getisoweeknumber

7.3.18. getisoyear

7.3.19. getminutes

7.3.20. getmonth

7.3.21. getseconds

7.3.22. getticks

7.3.23. gettime

7.3.24. getweekday

7.3.25. getweeknumber

7.3.26. getyear

7.3.27. getyearday

7.3.28. setday

7.3.29. sethours

7.3.30. setisoweekday

7.3.31. setisoweeknumber

7.3.32. setisoyear

7.3.33. setminutes

7.3.34. setmonth

7.3.35. setseconds

7.3.36. setticks

7.3.37. setyear

7.3.38. spandays

7.3.39. spanhours

7.3.40. spanminutes

7.3.41. spanseconds

7.3.42. spanticks

7.3.43. tolocal

7.3.44. toutc

8. History

9. Acknowledgement

7.1. How Date and Time are stored in `dateObject`