Lumesh Time Module

Lumesh time Module Documentation

Module Path: time
Use help time to view help.

Function Description: Provides functionalities for obtaining, 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 containing various time formats (Map type), 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()

# Example Output:
+------------------------------------------------+
| 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 and 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 the 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 the 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 Utility 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 and 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 Countdown to Workdays:

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

# Calculate remaining workdays (assuming weekends are 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))

Notes

In practical use, chained calls are supported, such as:

let a = t'2025-7-13 19:45'
a.diff('d', t'2024-1-1')

In the examples, type names are used for clarity.