Module:TimeSpan

TimeSpan Module Documentation

The 'TimeSpan' module provides functionality for working with time spans in Lua.

Constructor

TimeSpan.new(days, hours, minutes, seconds, milliseconds)

Creates a new 'TimeSpan' object representing the specified time components.

• Parameters:

 * `'days'`: Number of days (default: `0`).
 * `'hours'`: Number of hours (default: `0`).
 * `'minutes'`: Number of minutes (default: `0`).
 * `'seconds'`: Number of seconds (default: `0`).
 * `'milliseconds'`: Number of milliseconds (default: `0`).

• Returns: 'TimeSpan' object.

TimeSpan.fromSeconds(seconds)

Creates a new 'TimeSpan' object from a total number of seconds.

• Parameters:

 * `'seconds'`: Total number of seconds.

• Returns: 'TimeSpan' object representing the specified duration in seconds.

TimeSpan.fromMilliseconds(milliseconds)

Creates a new 'TimeSpan' object from a total number of milliseconds.

• Parameters:

 * `'milliseconds'`: Total number of milliseconds.

• Returns: 'TimeSpan' object representing the specified duration in milliseconds.

Methods

TimeSpan:getDays()

Gets the number of days in the 'TimeSpan'.

• Returns: Number of days as an integer.

TimeSpan:getHours()

Gets the number of hours in the 'TimeSpan'.

• Returns: Number of hours as an integer.

TimeSpan:getMinutes()

Gets the number of minutes in the 'TimeSpan'.

• Returns: Number of minutes as an integer.

TimeSpan:getSeconds()

Gets the number of seconds in the 'TimeSpan'.

• Returns: Number of seconds as an integer.

TimeSpan:getMilliseconds()

Gets the number of milliseconds in the 'TimeSpan'.

• Returns: Number of milliseconds as an integer.

TimeSpan:totalDays()

Gets the total number of days represented by the 'TimeSpan' (including fractional days).

• Returns: Total number of days as a floating-point number.

TimeSpan:totalHours()

Gets the total number of hours represented by the 'TimeSpan' (including fractional hours).

• Returns: Total number of hours as a floating-point number.

TimeSpan:totalMinutes()

Gets the total number of minutes represented by the 'TimeSpan' (including fractional minutes).

• Returns: Total number of minutes as a floating-point number.

TimeSpan:totalSeconds()

Gets the total number of seconds represented by the 'TimeSpan' (including fractional seconds).

• Returns: Total number of seconds as a floating-point number.

TimeSpan:totalMilliseconds()

Gets the total number of milliseconds represented by the 'TimeSpan' (including fractional milliseconds).

• Returns: Total number of milliseconds as a floating-point number.

TimeSpan:toString()

Converts the 'TimeSpan' object to a string representation.

• Returns: String representation of the 'TimeSpan' in the format `'d.hh:mm:ss.fff'`, where `'d'` is days, `'hh'` is hours, `'mm'` is minutes, `'ss'` is seconds, and `'fff'` is milliseconds.

Example Usage

To use the 'TimeSpan' module in your Lua scripts, follow these examples:

local TimeSpan = require('TimeSpan')

-- Create a new TimeSpan representing 1 day, 2 hours, 30 minutes, 15 seconds, and 500 milliseconds
local ts = TimeSpan.new(1, 2, 30, 15, 500)

-- Get the string representation of the TimeSpan
local tsString = ts:toString()

-- Output the TimeSpan string representation
print(tsString)  -- Output: "1.02:30:15.500"

-- Get specific components of the TimeSpan
print("Days:", ts:getDays())  -- Output: 1
print("Hours:", ts:getHours())  -- Output: 2
print("Minutes:", ts:getMinutes())  -- Output: 30
print("Seconds:", ts:getSeconds())  -- Output: 15
print("Milliseconds:", ts:getMilliseconds())  -- Output: 500

-- Get the total number of hours represented by the TimeSpan
local totalHours = ts:totalHours()
print("Total Hours:", totalHours)  -- Output: 26.507638888889

-- Get the total number of minutes represented by the TimeSpan
local totalMinutes = ts:totalMinutes()
print("Total Minutes:", totalMinutes)  -- Output: 1590.4583333333

---

local TimeSpan = {}

-- Metatable to make instances of TimeSpan readonly
local TimeSpan_mt = {
    __index = TimeSpan,
    __newindex = function()
        error("Attempt to modify readonly TimeSpan", 2)
    end
}

local MillisecondsPerSecond =	1000
local MillisecondsPerMinute =	60000
local MillisecondsPerHour = 	3600000
local MillisecondsPerDay =  	86400000
 
local SecondsPerMinute =		60
local SecondsPerHour =			3600
local SecondsPerDay =			86400
 
local MinutesPerHour =			60
local MinutesPerDay =			1440 
 
local HoursPerDay = 			24     

function TimeSpan.new(days, hours, minutes, seconds, milliseconds)
    local totalMilliseconds =  (days or 0)	  *	MillisecondsPerDay +
                               (hours or 0)   *	MillisecondsPerHour +
                               (minutes or 0) * MillisecondsPerMinute +
                               (seconds or 0) * MillisecondsPerSecond +
                               (milliseconds or 0)

    local self = {
        _totalMilliseconds = totalMilliseconds
    }

    setmetatable(self, TimeSpan_mt)
    return self
end

function TimeSpan:getDays()
    return math.floor(self._totalMilliseconds / MillisecondsPerDay)
end

function TimeSpan:getHours()
    return math.floor(self._totalMilliseconds / MillisecondsPerHour % HoursPerDay)
end

function TimeSpan:getMinutes()
    return math.floor(self._totalMilliseconds / MillisecondsPerMinute % MinutesPerHour)
end

function TimeSpan:getSeconds()
    return math.floor(self._totalMilliseconds / MillisecondsPerSecond % SecondsPerMinute)
end

function TimeSpan:getMilliseconds()
    return math.floor(self._totalMilliseconds % MillisecondsPerSecond)
end

function TimeSpan:getTotalDays()
	return self._totalMilliseconds / MillisecondsPerDay
end

function TimeSpan:getTotalHours()
	return self._totalMilliseconds / MillisecondsPerHour
end

function TimeSpan:getTotalMinutes()
	return self._totalMilliseconds / MillisecondsPerMinute
end

function TimeSpan:getTotalSeconds()
	return self._totalMilliseconds / MillisecondsPerSecond
end

function TimeSpan:getTotalMilliseconds()
	return self._totalMilliseconds
end

function TimeSpan:toString()

    local milliseconds = totalMilliseconds % 1000
    totalMilliseconds = (totalMilliseconds - milliseconds) / 1000

    local seconds = totalMilliseconds % 60
    totalMilliseconds = (totalMilliseconds - seconds) / 60

    local minutes = totalMilliseconds % 60
    totalMilliseconds = (totalMilliseconds - minutes) / 60

    local hours = totalMilliseconds % 24
    local days = (totalMilliseconds - hours) / 24

    local parts = {}
    if days > 0 then
        table.insert(parts, formatTime(days, "."))
    end
    table.insert(parts, formatTime(hours, ":"))
    table.insert(parts, formatTime(minutes, ":"))
    table.insert(parts, formatTime(seconds, ""))
    if milliseconds > 0 then
        table.insert(parts, "." .. string.format("%03d", milliseconds))
    end

    return table.concat(parts)
end

function TimeSpan:__tostring()
    return self:toString()
end

return TimeSpan