メインコンテンツまでスキップ
バージョン: v0.6.0

日時API

日付と時刻のヘルパーは、ptool.datetime および p.datetime で使用できます。

ptool.datetime は具体的なインスタントで動作します。すべての DateTime 値にはタイムゾーンまたは数値オフセットが含まれます。

ptool.datetime.now​

Unreleased - 導入されました。

ptool.datetime.now([tz]) は現在時刻を DateTime として返します。

  • tz (文字列、オプション): UTC、America/New_York、Asia/Shanghai などの IANA タイムゾーン。省略した場合は、ローカル システムのタイムゾーンが使用されます。
  • 戻り値: DateTime。
local local_now = p.datetime.now()
local utc_now = p.datetime.now("UTC")

print(local_now)
print(utc_now:format("%Y-%m-%d %H:%M:%S %Z"))

ptool.datetime.parse​

Unreleased - 導入されました。

ptool.datetime.parse(input[, options]) は日時文字列を解析し、DateTime を返します。

  • input (文字列、必須): 日時文字列。
  • options.timezone (文字列、オプション): 入力にタイムゾーンまたはオフセットが含まれていない場合にのみ使用される IANA タイムゾーン。
  • 戻り値: DateTime。

受け入れられる入力:

  • 2024-07-15T16:24:59-04:00 などのゾーン入力。
  • パーサーでサポートされている場合、括弧で囲まれたタイムゾーン注釈を含むゾーン入力。
  • 2024-07-15 16:24:59 などの単純な入力。ただし、options.timezone が指定された場合に限ります。

挙動:

  • 空の文字列は拒否されます。
  • input にすでにタイムゾーンまたはオフセットが含まれている場合、options.timezone を設定するとエラーが発生します。
  • options.timezone がないと、単純な入力は拒否されます。
local a = p.datetime.parse("2024-07-15T16:24:59-04:00")
local b = p.datetime.parse("2024-07-15 16:24:59", {
  timezone = "America/New_York",
})

print(a.offset)   -- -04:00
print(b.timezone) -- America/New_York

ptool.datetime.from_unix​

Unreleased - 導入されました。

ptool.datetime.from_unix(value[, options]) は、Unix タイムスタンプから DateTime を構築します。

  • value (整数、必須): Unix タイムスタンプ。
  • options.unit (文字列、オプション): s、ms、または ns のいずれか。デフォルトはsです。
  • options.timezone (文字列、オプション): IANA タイムゾーン。省略した場合、タイムスタンプは UTC で解釈されます。
  • 戻り値: DateTime。
local a = p.datetime.from_unix(1721075099)
local b = p.datetime.from_unix(1721075099000, {
  unit = "ms",
  timezone = "Asia/Tokyo",
})

print(a) -- 2024-07-15T20:24:59+00:00
print(b)

ptool.datetime.compare​

Unreleased - 導入されました。

ptool.datetime.compare(a, b) は 2 つの瞬間を比較します。

  • a / b (文字列|DateTime、必須): 日時文字列または DateTime オブジェクト。
  • 戻り値: -1 | 0 | 1.

文字列引数は ptool.datetime.parse(input) と同じ厳密なルールを使用して解析されるため、タイムゾーンまたはオフセットがすでに含まれている必要があります。

print(ptool.datetime.compare(
  "2024-07-15T20:24:59+00:00",
  "2024-07-15T16:24:59-04:00"
)) -- 0

ptool.datetime.is_valid​

Unreleased - 導入されました。

ptool.datetime.is_valid(input[, options]) は、日時文字列を解析できるかどうかをチェックします。

  • input (文字列、必須): 日時文字列。
  • options.timezone (文字列、オプション): 単純な入力用の IANA タイムゾーン。
  • 戻り値: boolean。
print(ptool.datetime.is_valid("2024-07-15T16:24:59-04:00")) -- true
print(ptool.datetime.is_valid("2024-07-15 16:24:59")) -- false
print(ptool.datetime.is_valid("2024-07-15 16:24:59", {
  timezone = "America/New_York",
})) -- true

DateTime​

Unreleased - 導入されました。

DateTime は、ptool.datetime.now(...)、parse(...)、または from_unix(...) によって返される具体的なインスタントを表します。

これは Lua userdata として実装されています。

フィールドとメソッド:

  • フィールド:
    • year (整数)
    • month (整数)
    • day (整数)
    • hour (整数)
    • minute (整数)
    • second (整数)
    • nanosecond (整数)
    • offset (文字列)
    • timezone (文字列)
  • メソッド:
    • dt:format(fmt) -> string
    • dt:to_string() -> string
    • dt:unix([unit]) -> integer
    • dt:in_tz(tz) -> DateTime
    • dt:compare(other) -> -1|0|1
  • メタメソッド:
    • tostring(dt)が利用可能です。
    • ==, <, <= の比較をサポートします。

format​

正規 API 名: ptool.datetime.DateTime:format。

dt:format(fmt) は、strftime スタイルのディレクティブを使用して日時をフォーマットします。

  • fmt (文字列、必須): %Y-%m-%d %H:%M:%S %Z などの形式文字列。
  • 戻り値: string。
local dt = p.datetime.parse("2024-07-15T16:24:59-04:00")
print(dt:format("%Y-%m-%d %H:%M:%S %:z"))

to_string​

正規 API 名: ptool.datetime.DateTime:to_string。

dt:to_string() は、数値オフセットを含む正規の文字列形式を返します。

  • 戻り値: string。
local dt = p.datetime.parse("2024-07-15T16:24:59-04:00")
print(dt:to_string()) -- 2024-07-15T16:24:59-04:00

unix​

正規 API 名: ptool.datetime.DateTime:unix。

dt:unix([unit]) は、その時点の Unix タイムスタンプを返します。

  • unit (文字列、オプション): s、ms、または ns のいずれか。デフォルトはsです。
  • 戻り値: integer。

注意:

  • 結果が Lua の整数範囲に収まらない場合、ns はエラーを引き起こす可能性があります。
local dt = p.datetime.parse("2024-07-15T20:24:59+00:00")
print(dt:unix())       -- seconds
print(dt:unix("ms"))   -- milliseconds

in_tz​

正規 API 名: ptool.datetime.DateTime:in_tz。

dt:in_tz(tz) は、同じ瞬間を別のタイムゾーンに変換します。

  • tz (文字列、必須): IANA タイムゾーン。
  • 戻り値: DateTime。
local dt = p.datetime.parse("2024-07-15T20:24:59+00:00")
local tokyo = dt:in_tz("Asia/Tokyo")

print(dt)
print(tokyo)

compare​

正規 API 名: ptool.datetime.DateTime:compare。

dt:compare(other) は現在の瞬間を other と比較します。

  • other (文字列|DateTime、必須): 日時文字列または別の DateTime オブジェクト。
  • 戻り値: -1 | 0 | 1.
local a = p.datetime.parse("2024-07-15T20:24:59+00:00")
local b = p.datetime.parse("2024-07-15T21:24:59+00:00")

print(a:compare(b)) -- -1
print(a < b)        -- true

注意​

  • ptool.datetime は、"tomorrow 8am" などの自然言語フレーズを解析しません。
  • タイムゾーン名は、UTC、Asia/Tokyo、America/New_York などの IANA 識別子である必要があります。
  • 比較は、表示されている実時間フィールドではなく、瞬間に基づいて行われます。