Lumesh Time 模块

Lumesh `time` 模块使用文档

模块路径：time
使用 help time 查看帮助

功能描述：提供时间获取、解析、计算和格式化功能

函数目录

功能类别	函数名	调用格式	核心功能
时间获取	`now`	`time.now [format]`	获取当前时间（对象或格式化字符串）
时间获取	`display`	`time.display`	获取预格式化时间信息（多种格式的映射）
时间获取	`stamp`	`time.stamp [datetime]`	获取Unix时间戳（秒）
时间获取	`stamp_ms`	`time.stamp_ms [datetime]`	获取Unix时间戳（毫秒）
时间解析与格式化	`parse`	`time.parse [format] datetime_str`	解析时间字符串为时间对象
时间解析与格式化	`fmt`	`time.fmt format_str [datetime]`	格式化时间对象为字符串
时间解析与格式化	`to_string`	`time.to_string datetime [format]`	转换时间对象为字符串（默认RFC3339）
时间运算	`add`	`time.add duration [base_time]`	给时间增加持续时间
时间运算	`diff`	`time.diff time1 time2 unit`	计算两个时间的差值（指定单位）
时间运算	`timezone`	`time.timezone datetime offset_hours`	转换时区（按小时偏移）
时间组件获取	`year`	`time.year [datetime]`	获取年份
时间组件获取	`month`	`time.month [datetime]`	获取月份（1-12）
时间组件获取	`weekday`	`time.weekday [datetime]`	获取星期几（1-7，周一为1）
时间组件获取	`day`	`time.day [datetime]`	获取日期（1-31）
时间组件获取	`hour`	`time.hour [datetime]`	获取小时（0-23）
时间组件获取	`minute`	`time.minute [datetime]`	获取分钟（0-59）
时间组件获取	`second`	`time.second [datetime]`	获取秒数（0-59）
时间组件获取	`seconds`	`time.seconds [datetime]`	获取自午夜起的秒数
其他功能	`sleep`	`time.sleep duration`	暂停执行指定时长
其他功能	`is_leap_year`	`time.is_leap_year [year]`	判断是否为闰年
其他功能	`from_map`	`time.from_map [map]`	通过组件创建时间对象

函数详解

1. 时间获取函数

`time.now` - 获取当前时间

参数说明：

参数模式	参数类型	作用描述
无参数	-	返回当前时间的`DateTime`对象
单参数	`String`	使用指定格式返回格式化字符串

返回值：DateTime对象或String
示例：

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

`time.display` - 获取预格式化时间信息

参数说明：无参数
返回值：包含多种时间格式的映射（Map类型），键包括：

time: 24小时制时间（HH:MM:SS）
timepm: 12小时制时间（h:mm AM/PM）
date: 日期（YYYY-MM-DD）
datetime: 日期时间（YYYY-MM-DD HH:MM:SS）
rfc3339: RFC3339格式
rfc2822: RFC2822格式
week: 一年中的第几周
ordinal: 一年中的第几天
datetime_obj: 原始DateTime对象

示例：

time.display()

# 输出示例：
+------------------------------------------------+
| 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` - 获取Unix时间戳（秒）

参数说明：

参数模式	参数类型	作用描述
无参数	-	返回当前时间戳
单参数	`DateTime`或`String`	返回指定时间的时间戳

返回值：Integer（时间戳，单位秒）
示例：

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

`time.stamp_ms` - 获取Unix时间戳（毫秒）

参数说明：同time.stamp
返回值：Integer（时间戳，单位毫秒）
示例：

time.stamp_ms()             # => 1718703045123

2. 时间解析与格式化函数

`time.parse` - 解析时间字符串

参数说明：

参数	类型	作用描述
1（可选）	`String`	时间格式（默认尝试常见格式，如”%Y-%m-%d %H:%M”）
2	`String`	待解析的时间字符串

支持格式示例：

%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”

返回值：DateTime对象
示例：

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

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

`time.fmt` - 格式化时间

参数说明：

参数	类型	作用描述
1	`String`	格式字符串
2（可选）	`DateTime`或`String`	待格式化的时间（默认当前时间）

格式符号参考：

%Y：四位年份（2024）
%m：月份（01-12）
%d：日期（01-31）
%H：24小时制小时（00-23）
%M：分钟（00-59）
%S：秒（00-59）

返回值：String
示例：

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` - 转换为字符串

参数说明：

参数	类型	作用描述
1	`DateTime`	时间对象
2（可选）	`String`	格式字符串（默认RFC3339）

返回值：String
示例：

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

3. 时间运算函数

`time.add` - 增加时间间隔

参数说明：

参数	类型	作用描述
1	`String`或`Integer`…	持续时间（字符串如”1h30m”或多个数字参数）
2（可选）	`DateTime`	基准时间（默认当前时间）

持续时间格式：

1d2h30m = 1天2小时30分钟
3600s = 3600秒（1小时）
多参数模式：秒分时天（如 0 30 0 = 30分钟）

返回值：DateTime对象
示例：

time.add "1h30m"                  # => 当前时间加1小时30分钟
time.add 3600 time.now()          # => 加3600秒（1小时）
time.add 0 30 0                   # => 加30分钟（旧式多参数）

`time.diff` - 计算时间差

参数说明：

参数	类型	作用描述
1	`String`	单位（”s”秒、”m”分、”h”时、”d”天）
2	`DateTime`	时间1
3	`DateTime`	时间2

返回值：Integer（时间差，按指定单位）
示例：

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

`time.timezone` - 转换时区

参数说明：

参数	类型	作用描述
1	`Integer`	时区偏移（小时，如+8、-5）
2	`DateTime`	时间对象

返回值：DateTime对象（调整时区后的时间）
示例：

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

4. 时间组件获取函数

通用说明：

函数包括：year, month, weekday, day, hour, minute, second, seconds
参数模式：
- 无参数：获取当前时间的对应组件
- 单参数（DateTime或String）：获取指定时间的对应组件

返回值：Integer

示例：

time.month                     # => 6（当前月份）
time.weekday "2024-06-18"      # => 2（星期二）
time.seconds                   # => 55845（当前时间距离午夜秒数）

5. 其他功能函数

`time.sleep` - 暂停执行

参数说明：

参数	类型	作用描述
1	`Integer`或`String`	休眠时间（毫秒数或持续时间字符串如”1s”）

持续时间单位：

s：秒（如”30s”）
m：分钟（如”10m”）
h：小时（如”2h”）
d：天（如”1d”）

返回值：None
示例：

time.sleep 1000      # 休眠1秒
time.sleep "2m30s"   # 休眠2分30秒

`time.is_leap_year` - 判断闰年

参数说明：

参数模式	参数类型	作用描述
无参数	-	判断当前年份是否为闰年
单参数	`Integer`	判断指定年份是否为闰年

返回值：Boolean
示例：

time.is_leap_year()     # => false（2025年不是闰年）
time.is_leap_year(2024)     # => true（2024年是闰年）

`time.from_map` - 通过组件创建时间

参数说明：

参数	类型	作用描述
1	`Map`	包含年月日，时分秒的结构

返回值：DateTime对象
示例：

let m = {
  year: 2025,
  month: 3,
  day: 28,
  hour: 12,
  minute: 5,
  second: 38
}
time.from_map m
# => DateTime(2024-06-18T15:30:00)

综合使用示例

计算工作日倒计时：

# 定义目标日期
let target = (time.parse "2024-12-31 18:00")

# 计算剩余工作日（假设周六、日休息）
fn workdays_remaining(target) {
  now = (time.now())
  days = (time.diff "d" now target)   # 总天数差
  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))

定时任务示例：

# 每5秒打印一次时间
loop {
  print (time.now "%H:%M:%S")
  time.sleep "5s"
}

输出：

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

updated at 2025-06-23

# libs # datetime

Lumesh Time 模块