Penlight Documentation

# Class `pl.Date`

Date and Date Format classes.

See the Guide.

NOTE: the date module is deprecated! see https://github.com/lunarmodules/Penlight/issues/285

Dependencies: pl.class, pl.stringx, pl.utils

## Functions

Date:set (t) | set the current time of this Date object.
Date.tzone (ts) | get the time zone offset from UTC.
Date:toUTC () | convert this date to UTC.
Date:toLocal () | convert this UTC date to local.
Date:year (y) | set the year.
Date:month (m) | set the month.
Date:day (d) | set the day.
Date:hour (h) | set the hour.
Date:min (min) | set the minutes.
Date:sec (sec) | set the seconds.
Date:yday (yday) | set the day of year.
Date:year (y) | get the year.
Date:month () | get the month.
Date:day () | get the day.
Date:hour () | get the hour.
Date:min () | get the minutes.
Date:sec () | get the seconds.
Date:yday () | get the day of year.
Date:weekday_name (full) | name of day of week.
Date:month_name (full) | name of month.
Date:is_weekend () | is this day on a weekend?.
Date:add (t) | add to a date object.
Date:last_day () | last day of the month.
Date:diff (other) | difference between two Date objects.
Date:__tostring () | long numerical ISO data format version of this date.
Date:__eq (other) | equality between Date objects.
Date:__lt (other) | ordering between Date objects.
Date:__sub () | difference between Date objects.
Date:__add (other) | add a date and an interval.
Date.Interval (t) | Date.Interval constructor
Date.Interval:__tostring () | If it's an interval then the format is '2 hours 29 sec' etc.
Date.Format (fmt.) | Date.Format constructor.
Date.Format:parse (str) | parse a string into a Date object.
Date.Format:tostring (d) | convert a Date object into a string.
Date.Format:US_order (yesno) | force US order in dates like 9/11/2001

## Methods

pl.date:Date (t, ...) | Date constructor.

## Functions

Date:set (t)
  set the current time of this Date object.

  ### Parameters:

  - t integer seconds since epoch
Date.tzone (ts)
  get the time zone offset from UTC.

  ### Parameters:

  - ts integer seconds ahead of UTC
Date:toUTC ()
  convert this date to UTC.
Date:toLocal ()
  convert this UTC date to local.
Date:year (y)
  set the year.

  ### Parameters:

  - y integer Four-digit year
Date:month (m)
  set the month.

  ### Parameters:

  - m integer month
Date:day (d)
  set the day.

  ### Parameters:

  - d integer day
Date:hour (h)
  set the hour.

  ### Parameters:

  - h integer hour
Date:min (min)
  set the minutes.

  ### Parameters:

  - min integer minutes
Date:sec (sec)
  set the seconds.

  ### Parameters:

  - sec integer seconds
Date:yday (yday)
  set the day of year.

  ### Parameters:

  - yday integer day of year
Date:year (y)
  get the year.

  ### Parameters:

  - y integer Four-digit year
Date:month ()
  get the month.
Date:day ()
  get the day.
Date:hour ()
  get the hour.
Date:min ()
  get the minutes.
Date:sec ()
  get the seconds.
Date:yday ()
  get the day of year.
Date:weekday_name (full)
  name of day of week.

  ### Parameters:

  - full boolean abbreviated if true, full otherwise.

  ### Returns:

  string name
Date:month_name (full)
  name of month.

  ### Parameters:

  - full integer abbreviated if true, full otherwise.

  ### Returns:

  string name
Date:is_weekend ()
  is this day on a weekend?.
Date:add (t)
  add to a date object.

  ### Parameters:

  - t a table containing one of the following keys and a value: one of year,month,day,hour,min,sec

  ### Returns:

  this date
Date:last_day ()
  last day of the month.

  ### Returns:

  int day
Date:diff (other)
  difference between two Date objects.

  ### Parameters:

  - other Date Date object

  ### Returns:

  Date.Interval object
Date:__tostring ()
  long numerical ISO data format version of this date.
Date:__eq (other)
  equality between Date objects.

  ### Parameters:

  - other
Date:__lt (other)
  ordering between Date objects.

  ### Parameters:

  - other
Date:__sub ()
  difference between Date objects.
Date:__add (other)
  add a date and an interval.

  ### Parameters:

  - other either a Date.Interval object or a table such as passed to Date:add
Date.Interval (t)
  Date.Interval constructor

  ### Parameters:

  - t integer an interval in seconds
Date.Interval:__tostring ()
  If it's an interval then the format is '2 hours 29 sec' etc.
Date.Format (fmt.)
  Date.Format constructor.

  ### Parameters:

  - fmt. string A string where the following fields are significant:
    - d day (either d or dd)
    - y year (either yy or yyy)
    - m month (either m or mm)
    - H hour (either H or HH)
    - M minute (either M or MM)
    - S second (either S or SS)

    Alternatively, if fmt is nil then this returns a flexible date parser that tries various date/time schemes in turn:

    - ISO 8601, like `2010-05-10 12:35:23Z` or `2008-10-03T14:30+02`
    - times like 15:30 or 8.05pm (assumed to be today's date)
    - dates like 28/10/02 (European order!) or 5 Feb 2012
    - month name like march or Mar (case-insensitive, first 3 letters); here the day will be 1 and the year this current year

    A date in format 3 can be optionally followed by a time in format 2. Please see test-date.lua in the tests folder for more examples.

  ### Usage:

      df = Date.Format("yyyy-mm-dd HH:MM:SS")

Date.Format:parse (str)
  parse a string into a Date object.

  ### Parameters:

  - str string a date string

  ### Returns:

  date object
Date.Format:tostring (d)
  convert a Date object into a string.

  ### Parameters:

  - d a date object, or a time value as returned by os.time

  ### Returns:

  string
Date.Format:US_order (yesno)
  force US order in dates like 9/11/2001

  ### Parameters:

  - yesno

## Methods

pl.date:Date (t, ...)
  Date constructor.

  ### Parameters:

  - t

    this can be either

    - `nil` or empty - use current date and time
    - number - seconds since epoch (as returned by os.time). Resulting time is UTC
    - Date - make a copy of this date
    - table - table containing year, month, etc as for os.time. You may leave out year, month or day, in which case current values will be used.
    - year (will be followed by month, day etc)
  - ... true if Universal Coordinated Time, or two to five numbers: month,day,hour,min,sec

generated by LDoc 1.5.0