== timeutils.lua ==

This is a standard Lua module.  To install it on Vera, upload to `/usr/lib/lua/`.  To use it, start your code with
{{{
require "timeutils"
luup.timezone = -5      -- replace with your timezone
}}}

('''Note:''' currently it seems UI3 doesn't store the configured timezone in the `luup` table.  When this issue gets resolved, we should get rid of that manual timezone setting.


'''`timeutils.lastmidnight ([time])`'''
  Returns the timestamp of the last midnight equal or preceding the given `time`.  If no `time` is given, assumes current time.

'''`timeutils.dayseconds ([time])`'''
  Returns the number of seconds since the last midnight to the given `time`.  If no `time` is given, assumes current time.

'''`timeutils.to_secs (timestring)`'''
  Converts a string of the form `"hh:mm:ss am|pm"` to the number of seconds.  Together with `dayseconds()` it lets you write code of the form:
{{{
if timeutils.dayseconds() < timeutils.to_secs ("09:30 pm") then
    return false
end
}}}

'''`timeutils.localtoUTC ([time] [, timezone])`'''
  Returns the 'date table' (same as returned by `os.date('*t', time)`) of the UTC time corresponding to the given `time`.  If no `time` is given, assumes current time.  If no `timezone` is given, assumes Vera's configured timezone.

'''`timeutils.degrees (x [, ...])`'''
  Transforms one or more numbers expressing an angles in degrees into strings with degrees, minutes and seconds.  For example:
{{{
timeutils.degrees (23.2323)
=> 23°13'56.28"
}}}

'''`timeutils.sun_position ([time] [, place])`'''
  Returns sun's altitude and azimuth, in degrees, for the given `time` and `place`.  If no `time` is given, assumes current time.  The `place` parameter, if given, must be a table with `latitude`, `longitude` and `timezone` fields.  If no `place` is given, uses the global `luup` table, which should have those fields.

'''`timeutils.is_dark ([time] [, place])`'''
  Returns a boolean indicating if the sun is below the horizon.