# 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](https://github.com/smucclaw/l4-ide/blob/main/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



```l4-file
-- 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](https://github.com/smucclaw/l4-ide/blob/main/jl4-core/libraries/time.l4) source for all functions.**