§

Time Library

Wall-clock time-of-day for legal rules involving time constraints. Uses 24-hour format internally with no date or timezone component. Can be imported into L4 files with IMPORT time.

Location

jl4-core/libraries/time.l4

Features

  • Time construction from hours/minutes/seconds, serial numbers, strings, or DATETIME extraction
  • AM/PM support via Meridiem Indicator enum
  • Time arithmetic (add/subtract hours, minutes, seconds) with midnight wrapping
  • Time-of-day predicates (morning, afternoon, evening)
  • Serial conversion (fraction of day: 0.0 = midnight, 0.5 = noon)
  • Comparison operators and min/max functions
  • String parsing for JSON interoperability

Key Functions

Constants:

  • Midnight - 00:00:00
  • Noon - 12:00:00
  • Hours in a day, Minutes in an hour, Seconds in a minute, etc.

Time Construction:

  • Time h m s - Create time from hours, minutes, seconds
  • Time h m - Create time (seconds default to 0)
  • Time h - Create time (minutes and seconds default to 0)
  • Time h m s am / Time h m s pm - 12-hour AM/PM format
  • Time h am / Time h pm - Shorthand 12-hour format
  • Time str - Parse time string ("HH:MM:SS" or "HH:MM"), returns MAYBE TIME
  • Time dt - Extract time from DATETIME (ignores date and timezone)
  • serial Serial to time - Create time from day fraction

Time Extractors:

  • the hour of t - Get hour (0-23)
  • the minute of t - Get minute (0-59)
  • the second of t - Get second (0-59)

Time Arithmetic (wraps at midnight):

  • t plus hours n, t minus hours n
  • t plus minutes n, t minus minutes n
  • t plus seconds n, t minus seconds n

Predicates:

  • is morning - Before noon (hour < 12)
  • is afternoon - 12:00 to 17:59
  • is evening - 18:00 onwards
  • is before noon, is after noon

Comparators:

  • the earlier of t1 t2
  • the later of t1 t2
  • t1 is before t2, t1 is after t2
  • Standard comparison operators: LESS THAN, GREATER THAN, AT MOST, AT LEAST
  • TIME MINUS TIME returns difference in seconds

Example: Time Operations

-- Time Example: Wall-clock time operations
IMPORT time

-- Time construction (24-hour format)
DECIDE `office start` IS Time 9 0 0
DECIDE `lunch break` IS Time 12 30
DECIDE `end of day` IS Time 17

#EVAL `office start`   -- 09:00:00
#EVAL `lunch break`    -- 12:30:00
#EVAL `end of day`     -- 17:00:00

-- Time from string (JSON interop) - returns MAYBE TIME
DECIDE `from string` IS Time "14:30:00"
#EVAL `from string`  -- JUST OF (TIME OF 14, 30, 0.0)

-- AM/PM construction
DECIDE `early meeting` IS Time 7 30 am
DECIDE `dinner time` IS Time 7 pm

#EVAL `early meeting`  -- 07:30:00
#EVAL `dinner time`    -- 19:00:00

-- Extracting components
#EVAL `the hour of` `office start`    -- 9
#EVAL `the minute of` `lunch break`   -- 30

-- Time predicates
DECIDE `morning check` IS `office start` `is morning`
DECIDE `afternoon check` IS `lunch break` `is afternoon`
#EVAL `morning check`     -- TRUE
#EVAL `afternoon check`   -- TRUE

-- Time arithmetic (wraps at midnight)
DECIDE `plus two hours` IS `office start` `plus hours` 2
#EVAL `plus two hours`  -- 11:00:00

DECIDE `minus one hour` IS `office start` `minus hours` 1
#EVAL `minus one hour`  -- 08:00:00

-- Time comparisons
DECIDE `start before lunch` IS `office start` LESS THAN `lunch break`
#EVAL `start before lunch`  -- TRUE

DECIDE `start is before lunch` IS `office start` `is before` `lunch break`
DECIDE `lunch is after start` IS `lunch break` `is after` `office start`
#EVAL `start is before lunch`  -- TRUE
#EVAL `lunch is after start`   -- TRUE

#EVAL `the earlier of` `office start` `lunch break`  -- 09:00:00
#EVAL `the later of` `office start` `lunch break`    -- 12:30:00

-- Serial conversion (fraction of day)
#EVAL (Time 12 0 0) `Time to serial`  -- 0.5 (noon = half day)
#EVAL 0.5 `Serial to time`            -- 12:00:00

See time.l4 source for all functions.