Lumesh Time Module

Lumesh time Module Documentation

Module Path: time
Function Description: Provides functionalities for retrieving, parsing, calculating, and formatting time.

Function Directory

Function Details

1. Time Retrieval Functions

time.now - Get Current Time

Parameter Description:

Return Value: DateTime object or String
Example:

time.now()           # => DateTime(2024-06-18T15:30:45)
time.now "%Y年%m月%d日"  # => "2024年06月18日"

time.display - Get Pre-formatted Time Information

Parameter Description: No parameters
Return Value: A mapping of various time formats (type Map), keys include:

• time: 24-hour time (HH:MM:SS)
• timepm: 12-hour time (h:mm AM/PM)
• date: Date (YYYY-MM-DD)
• datetime: Date and time (YYYY-MM-DD HH:MM:SS)
• rfc3339: RFC3339 format
• rfc2822: RFC2822 format
• week: Week number of the year
• ordinal: Day of the year
• datetime_obj: Original DateTime object

Example:

time.display()

# Output Example:
+------------------------------------------------+
| KEY           VALUE                            |
+================================================+
| datetime_obj  2025-06-01 16:38:50.279424998    |
| week          22                               |
| timepm        "4:38 PM"                        |
| rfc2822       "Sun, 1 Jun 2025 16:38:50 +0800" |
| ordinal       152                              |
| date          "2025-06-01"                     |
| rfc3339       "2025-06-01T16:38:50.279424998+08:00" |
| time          "16:38:50"                       |
| datetime      "2025-06-01 16:38:50"            |
+------------------------------------------------+

time.stamp - Get Unix Timestamp (Seconds)

Parameter Description:

Return Value: Integer (timestamp in seconds)
Example:

time.stamp()             # => 1718703045
time.stamp "2024-06-18 00:00:00"  # => 1718640000

time.stamp_ms - Get Unix Timestamp (Milliseconds)

Parameter Description: Same as time.stamp
Return Value: Integer (timestamp in milliseconds)
Example:

time.stamp_ms()             # => 1718703045123

2. Time Parsing and Formatting Functions

time.parse - Parse Time String

Parameter Description:

Supported Format Examples:

• %Y-%m-%d %H:%M → “2024-06-18 15:30”
• %Y-%m-%d %H:%M:%S
• %d/%m/%Y %H:%M:%S → “18/06/2024 15:30:45”
• %m/%d/%Y %I:%M %p → “06/18/2024 03:30 PM”

Return Value: DateTime object
Example:

time.parse "2024-06-18 15:30"
time.parse "%d/%m/%Y %-I:%M %p" "18/06/2024 3:30 PM"

# Returns
>> [DateTime] <<
2024-06-18 15:30:00

time.fmt - Format Time

Parameter Description:

Format Symbols Reference:

• %Y: Four-digit year (2024)
• %m: Month (01-12)
• %d: Day (01-31)
• %H: Hour in 24-hour format (00-23)
• %M: Minute (00-59)
• %S: Second (00-59)

Return Value: String
Example:

time.fmt "%Y-%m-%d"                      # => "2024-06-18"
time.fmt "%H:%M:%S" (time.parse "2024-06-18 15:30:45")
# => "15:30:45"

time.to_string - Convert to String

Parameter Description:

Return Value: String
Example:

time.to_string(time.now())                 # => "2024-06-18T15:30:45+08:00"
time.to_string time.now() "%Y%m%d"        # => "20240618"

3. Time Arithmetic Functions

time.add - Add Time Interval

Parameter Description:

Duration Format:

• 1d2h30m = 1 day 2 hours 30 minutes
• 3600s = 3600 seconds (1 hour)
• Multi-parameter mode: seconds minutes hours days (e.g., 0 30 0 = 30 minutes)

Return Value: DateTime object
Example:

time.add "1h30m"                  # => Current time plus 1 hour 30 minutes
time.add 3600 time.now()          # => Add 3600 seconds (1 hour)
time.add 0 30 0                   # => Add 30 minutes (old-style multi-parameter)

time.diff - Calculate Time Difference

Parameter Description:

Return Value: Integer (time difference in specified unit)
Example:

let t1 = (time.parse "2024-06-18 12:00")
let t2 = (time.parse "2024-06-18 13:30")
time.diff "m" t1 t2       # => 90 (minutes)

time.timezone - Convert Timezone

Parameter Description:

Return Value: DateTime object (time adjusted for timezone)
Example:

let utc_time = (time.parse "2024-06-18 08:00")
time.timezone 8 utc_time      # => DateTime(2024-06-18T16:00:00+08:00)

4. Time Component Retrieval Functions

General Description:

• Functions include: year, month, weekday, day, hour, minute, second, seconds
• Parameter Modes:
  • No parameters: Get the corresponding component of the current time
  • Single parameter (DateTime or String): Get the corresponding component of the specified time

Return Value: Integer

Example:

time.month                     # => 6 (current month)
time.weekday "2024-06-18"      # => 2 (Tuesday)
time.seconds                   # => 55845 (seconds since midnight)

5. Other Functionality Functions

time.sleep - Pause Execution

Parameter Description:

Duration Units:

• s: seconds (e.g., “30s”)
• m: minutes (e.g., “10m”)
• h: hours (e.g., “2h”)
• d: days (e.g., “1d”)

Return Value: None
Example:

time.sleep 1000      # Sleep for 1 second
time.sleep "2m30s"   # Sleep for 2 minutes 30 seconds

time.is_leap_year - Check for Leap Year

Parameter Description:

Return Value: Boolean
Example:

time.is_leap_year()     # => false (2025 is not a leap year)
time.is_leap_year(2024) # => true (2024 is a leap year)

time.from_map - Create Time from Components

Parameter Description:

Return Value: DateTime object
Example:

let m = {
  year: 2025,
  month: 3,
  day: 28,
  hour: 12,
  minute: 5,
  second: 38
}
time.from_map m
# => DateTime(2025-03-28T12:05:38)

Comprehensive Usage Example

Calculate Remaining Workdays Countdown:

# Define target date
let target = (time.parse "2024-12-31 18:00")

# Calculate remaining workdays (assuming weekends off)
fn workdays_remaining(target) {
  now = (time.now())
  days = (time.diff "d" now target)   # Total day difference
  weeks = (math.floor(days / 7))
  let extra_days = (days % 7)
  let weekend_days = ((weeks * 2) + (math.min extra_days 2))
  let workdays = (days - weekend_days)
  return workdays
}

print (workdays_remaining(target))

Scheduled Task Example:

# Print time every 5 seconds
loop {
  print (time.now "%H:%M:%S")
  time.sleep "5s"
}

Output:

15:30:00
15:30:05
15:30:10
...