Time Conversion

There are several operational time functions in Lua that we can use to calculate or convert timestamps. Note that the os.* functions operate with userdata formats and os.ts.* functions operate with Unix Epoch Time formats. The os.ts.* are the standard Lua functions. See os.time, os.date, os.ts.time and os.ts.date - iNTERFACEWARE Help Center for more details on the difference between these two categories.

Below are helpful code snippets using time conversions have come up in previous support tickets:

Convert to Unix Epoch Format

local testtime = '2020-04-19 19:26:08.000'

local result = {
      year=testtime:sub(1,4),
      month=testtime:sub(6,7),
      day=testtime:sub(9,10),
      hour=testtime:sub(12,13),
      min=testtime:sub(15,16),
      sec=testtime:sub(18,19)   
}
   
local time = os.ts.time(result)
local newtime = os.ts.date('%Y-%m-%d %X',tostring(time)) -- back to normal format, e.g. '2020-04-19 19:26:08'

Adding/Subtracting Time

-- Adding/subtracting time options    
-- 1) Get current time or use a given time
-- Unix Epoch Time approach (recommended)
local currUnixTime = os.ts.time() 
local givenUnixTime = os.ts.time(result)
-- Table approach (can be problematic if addition/subtraction affects the larger/smaller time interval
local currTableTime = os.date('*t')  -- alt: os.ts.date 
local givenTableTime = os.date('*t',os.time(result)) -- alt: os.ts.date and os.ts.time
   
-- 2) Add/Subtract (here, subtract 24 hours)
-- Unix Epoch Time approach
local newUnixTime = currUnixTime - 24*60*60   -- swap for givenUnixTime as desired 
-- Table approach
local newTableTime = currTableTime            -- swap for givenTableTime as desired
newTableTime.day = newTableTime.day - 1
   
-- 3) Convert to desired format
-- Unix Epoch Time approach
local unixToString = os.ts.date('%Y-%m-%d %I:%M:%S %p',newUnixTime) -- returns '2021-06-21 03:19:30 PM'; alt, use '*t' to convert to a table  
-- Table approach
local tableToUnix = os.ts.time(newTableTime)
local tableToUserdata = os.time(newTableTime)
   
-- Condensed example using Unix Epoch Time approach and converting to string
local subtractedTime = os.ts.date('%Y-%m-%d %I:%M:%S %p',os.ts.time() - 24*60*60)

Convert UTC to OS Time Zone

-- Returns difference in seconds between local and utc time
-- os.difftime accounts for daylight saving: https://help.interfaceware.com/api/#os_difftime
local function getTimezoneOffset()
   return os.difftime(
      os.time(os.ts.date("*t")),  -- local time from OS
      os.time(os.ts.gmdate("*t")) -- utc time
   )
end

-- Can be updated to accept any string format
local function convertToEpoch(utcDateTimeString)
   return os.ts.time{
      day   = utcDateTimeString:sub(9,10),
      month = utcDateTimeString:sub(6,7),
      year  = utcDateTimeString:sub(1,4),
      hour  = utcDateTimeString:sub(12,13),
      min   = utcDateTimeString:sub(15,16),
      sec   = utcDateTimeString:sub(18,19)
   }
end

local function convertFromUtcToLocal(utcDateTimeString)
   -- Offset epoch time based on time zone offset
   local localEpochTime = convertToEpoch(utcDateTimeString) + getTimezoneOffset()
   -- Returned format can be changed from '%c' - https://help.interfaceware.com/api/#os_ts_date
   return os.ts.date('%c', localEpochTime)
end

function main()
   local utcDateTimeString = '1994-11-05T13:15:30Z'

   -- Accepts UTC date/time string and returns a 
   --   formatted date/time string in local timezone
   local localDateTimeString = convertFromUtcToLocal(utcDateTimeString)
   trace(localDateTimeString)

end

Get timezone offset

local date = os.ts.date()
local t, d = dateparse.parse(date..' EST')
trace(d.tz_offset) -- Offset in minutes (-300)
trace(d.tz_offset/6*10) -- (-500)

Accounting for DST

Generally, this is best done through the os.difftime() function with the os.ts.date() functions (as in the examples above or via the isdst flag returned from os.ts.date('*t')). However, if you are converting a given timestamp on a server in UTC (or a non-DST timezone) and no time offset details are provided, these approaches will not work as the local server time cannot be used to identify if it falls within the DST period.

In this case, the timestamp can be used to calculate whether it falls within DST.

local dateparse = require 'date.parse'

--[[
DST runs from the 2nd Sunday in March until the first Sunday in November.
The time change happens at 2am.
]]
local DST = {
   ['start'] = {
      -- 2nd Sunday can happen any day from 8th to 14th, so if a given weekday falls on a certain calendar day
      -- that puts the prior Sunday within that range, that date is DST
      -- e.g. Monday the 9th means the 8th was a Sunday which has to be the 2nd Sunday of the month
      -- Below: [weekday] = min calendar day to "force" DST
      [2] = 9,
      [3] = 10,
      [4] = 11,
      [5] = 12,
      [6] = 13,
      [7] = 14
   },
   ['end'] = {
      -- Similar logic as above minus 1 week for the 1st Sunday
      [2] = 2,
      [3] = 3,
      [4] = 4,
      [5] = 5,
      [6] = 6,
      [7] = 7
   },
}

local function checkDST(date)      
   local usrdata,datetable = dateparse.parse(date)
   local dst = false -- Check true conditions only
   -- Start of DST
   if datetable.month == 3 then
      if datetable.day > 14 then 
         -- Past latest possible date for 2nd Sunday
         dst = true 
      elseif datetable.wday == 1 and datetable.day > 7 and datetable.hour >= 2 then 
         -- Past 2am on second sunday
         dst = true                  
      elseif DST.start[datetable.wday] ~= nil and datetable.day >= DST.start[datetable.wday] then 
         -- For other weekdays, check calculation
         dst = true       
      end
   elseif datetable.month > 3 and datetable.month < 11 then 
      dst=true
   -- End of DST
   elseif datetable.month == 11 then
      if datetable.day <= 7 then
         if datetable.wday == 1 and datetable.hour < 2 then
            dst = true            
         elseif DST['end'][datetable.wday] ~= nil and datetable.day < DST['end'][datetable.wday] then 
            dst = true
         end
      end
   end
   return dst, datetable
end