> For the complete documentation index, see [llms.txt](https://pretender.gitbook.io/time-utility-module-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pretender.gitbook.io/time-utility-module-documentation/tutorials/basic-usage.md).

# Basic Usage

### GetCurrentDateUnit:

The code below will print out the date today, the day of this week, the month of the date, the day of the month, and the year of the date.

```lua
local TimeUtilityModule = require('MODULE PATH GOES HERE')

local AllDateUnit = TimeUtilityModule.GetCurrentDateUnit('All')
local DayOfWeek, Month, DayOfMonth, Year = TimeUtilityModule.GetCurrentDateUnit('DayOfWeek'), TimeUtilityModule.GetCurrentDateUnit('Month'), TimeUtilityModule.GetCurrentDateUnit('DayOfMonth'), TimeUtilityModule.GetCurrentDateUnit('Year')

print(AllDateUnit) --- Monday February 12 2024
print(DayOfWeek) --- Monday
print(Month) --- February
print(DayOfMonth) --- 12
print(Year) --- 2024
```

### FormatSecondToTime:

The function below will format 60 seconds, 120 seconds, 30 seconds, and 210 seconds into the correct time unit.

{% code fullWidth="false" %}

```lua
local TimeUtilityModule = require('MODULE PATH GOES HERE')

local one_minute = 60
local two_minute = one_minute * 2
local thirty_seconds = 30

print(TimeUtilityModule.FormatSecondToTime(one_minute, 'Colons') -- 1:00
print(TimeUtilityModule.FormatSecondToTime(two_minute, 'Colons') -- 2:00
print(TimeUtilityModule.FormatSecondToTime(thirty_seconds, 'Colons') -- 30
print(TimeUtilityModule.FormatSecondToTime(one_minute + two_minute + thirty_seconds, 'Colons') -- 3:30

print(TimeUtilityModule.FormatSecondToTime(one_minute, 'Time_Units') -- 1 minute
print(TimeUtilityModule.FormatSecondToTime(two_minute, 'Time_Units') -- 2 minutes
print(TimeUtilityModule.FormatSecondToTime(thirty_seconds, 'Time_Units') -- 30 seconds
print(TimeUtilityModule.FormatSecondToTime(one_minute + two_minute + thirty_seconds, 'Time_Units') -- 3 minutes 30 seconds
```

{% endcode %}

### ConvertTimeUnitToSecond:

The code below will convert 10 seconds, 1 minute, 1 hour, 1 day, 1 week, 1 month, 1 year, 1 decade, and 1 millennium to the second unit.

```lua
local TimeUtilityModule = require('MODULE PATH GOES HERE')

local ten_seconds_to_seconds = TimeUtilityModule.ConvertTimeUnitToSecond(10, 'second')
local one_minute_to_seconds = TimeUtilityModule.ConvertTimeUnitToSecond(1, 'minute')
local one_hour_to_seconds = TimeUtilityModule.ConvertTimeUnitToSecond(1, 'hour')
local one_day_to_seconds = TimeUtilityModule.ConvertTimeUnitToSecond(1, 'day')
local one_week_to_seconds = TimeUtilityModule.ConvertTimeUnitToSecond(1, 'week')
local one_month_to_seconds = TimeUtilityModule.ConvertTimeUnitToSecond(1, 'month')
local one_year_to_seconds = TimeUtilityModule.ConvertTimeUnitToSecond(1, 'year')
local one_decade_to_seconds = TimeUtilityModule.ConvertTimeUnitToSecond(1, 'decade')
local one_century_to_seconds = TimeUtilityModule.ConvertTimeUnitToSecond(1, 'century')
local one_millennium_to_seconds = TimeUtilityModule.ConvertTimeUnitToSecond(1, 'millennium')

print(ten_seconds_to_seconds) -- 10
print(one_minute_to_seconds) -- 60
print(one_hour_to_seconds) -- 3600
print(one_day_to_seconds) -- 86400
print(one_week_to_seconds) -- 604800
print(one_month_to_seconds) -- 2505600
print(one_year_to_seconds) -- 31622400
print(one_decade_to_seconds) -- 315360000
print(one_century_to_seconds) -- 3153600000
print(one_millennium_to_seconds) -- 31536000000
```

### MarkTimestamp:

This function is a custom `wait()`function. Basically what it does is use a repeat loop to yield the code until the `os.time()` is equal to the sum of the marked timestamp and the given second(s).

```lua
local TimeUtilityModule = require('MODULE PATH GOES HERE')

local function CustomWait(second)
    second = tonumber(second)
	
    TimeUtilityModule.MarkTimestamp('CustomWaitFunction') --- mark the timestamp when the function is called.
	
    if type(second) ~= 'number' then error('Argument #1 expect to be a number but got '..type(second)..' instead!!') return end --- don't run the function because the second is not a number.
	
    repeat task.wait() --- task.wait() here to prevent the code to crash studio.
         --- yield with the repeat loop until os.time is equal to the sum of marked timestamp and given second(s). 
    until os.time() == TimeUtilityModule.GetMarkedTimestamp('CustomWaitFunction') + second
    TimeUtilityModule.UpdateMarkedTimestamp('CustomWaitFunction') --- update the current marked timestamp.
end

CustomWait(10)
print('10 seconds has passed!!')
CustomWait(10)
print('20 seconds has passed!!')
```

### ViewMarkedTimeStamps:

The code below will let you see all the marked timestamps after MarkTimestamp "A" and then wait for 3 seconds then MarkTimestamp "B" and ViewMarkedTimestamps.

{% code fullWidth="false" %}

```lua
local TimeUtilityModule = require('MODULE PATH GOES HERE')

local function CustomWait(second)
    second = tonumber(second)

    TimeUtilityModule.MarkTimestamp('CustomWaitFunction') --- mark the timestamp when the function is called.

    if type(second) ~= 'number' then error('Argument #1 expect to be a number but got '..type(second)..' instead!!') return end --- don't run the function because the second is not a number.

    repeat task.wait() --- task.wait() here to prevent the code to crash studio.
        --- yield with the repeat loop until os.time is equal to the sum of marked timestamp and given second(s). 
    until os.time() == TimeUtilityModule.GetMarkedTimestamp('CustomWaitFunction') + second
    TimeUtilityModule.UpdateMarkedTimestamp('CustomWaitFunction') --- update the current marked timestamp.
end

CustomWait(0)
TimeUtilityModule.MarkTimestamp('A')
CustomWait(3)
TimeUtilityModule.MarkTimestamp('B')
TimeUtilityModule.ViewMarkedTimestamps()

--[[

Output:

CustomWaitFunction: 1707706378 (Ignore this)
A: 1707706375
B: 1707706378

--]]
```

{% endcode %}

### GetElapsedSecondSinceTimestamp

The code below will count elapsed second(s) since the timestamp got marked.

{% code fullWidth="false" %}

```lua
local TimeUtilityModule = require('MODULE PATH GOES HERE')

TimeUtilityModule.MarkTimestamp('NewStamp')

while true do
    task.wait(1)
    print(TimeUtilityModule.GetElapsedSecondSinceTimestamp('NewStamp'))
end --- 1, 2, 3, 4, 5, and the numbers goes on in seconds
```

{% endcode %}

### GetMarkedTimestamp

The code below will get the marked timestamp by marking a timestamp name "Test1' and calling the GetMarkedTimestamp function from the module.

{% code fullWidth="false" %}

```lua
local TimeUtilityModule = require('MODULE PATH GOES HERE')

TimeUtilityModule.MarkTimestamp('Test1')
print(TimeUtilityModule.GetMarkedTimestamp('Test1')) --- print the marked timestamp time when the script run.
```

{% endcode %}

### UpdateMarkedTimestamp

The code below will mark a timestamp name "TestStamp" and then update the time stamp and print it after 5 seconds have passed.

{% code fullWidth="false" %}

```lua
local TimeUtilityModule = require('MODULE PATH GOES HERE')

TimeUtilityModule.MarkTimestamp('TestStamp')

print(TimeUtilityModule.GetMarkedTimestamp('TestStamp')) --- 1707711699
task.wait(5)
TimeUtilityModule.UpdateMarkedTimestamp('TestStamp')
print(TimeUtilityModule.GetMarkedTimestamp('TestStamp')) --- 1707711704
```

{% endcode %}

### instead