## LuaDate v2

### Lua Date and Time module for Lua 5.x.

### Jas Latrix

Copyright © 2005, 2006 Jas Latrix `<jastejada@yahoo.com>`

All Rights Deserved. Use at your own risk!. Shake well before using.

## 1. Introduction

LuaDate is a Lua module for date and time calculation and retrieval using the Gregorian Date system.

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

    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 recognized leap seconds.
- It assume 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 support 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 abrrieviated. If the value is a `number`, that number must be 1-12 (January-December). see table below

Table 1.

Index | Abbriviation | 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 3

#### 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. 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.2. Method(s) of date

  __call 1

#### 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

        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 later than date value of b. `a > b` is equivalent to `b < a`.
The `a <= b` operation.
  Returns `true` if date value of a is later 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 `a` to date and time value of `b`.
The `a + b` operation.
  Add the date and time value of `a` to date and time value of `b`.

`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

  adddays | addhours | addminutes | addmonths | addseconds | addticks | addyears | copy | fmt | getbias | getclockhour | getdate | getday | getfracsec | gethours | getisoweekday | getisoweeknumber | getisoyear | getminutes | getmonth | getseconds | getticks | gettime | getweekday | getweeknumber | getyear | getyearday | setday | sethours | setisoweekday | setisoweeknumber | setisoyear | setminutes | setmonth | setseconds | setticks | setyear | spandays | spanhours | spanminutes | spanseconds | spanticks | tolocal | toutc 44

#### 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 of month. 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 month value. The default value is `the current week`
  int_wday
    `integer` value. The day of month. 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 month value. The default value is `the current week`
  int_wday
    `integer` value. The day of month. 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:spanseconds() == (2*24*60*60))

#### 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.