Module V1.Temporal

Temporal validity support for time-bounded fields.

Temporal validity support for contact fields.

This module provides types and functions for managing time-bounded information in contacts, such as emails valid only during certain employment periods.

type date = Ptime.date

Date represented as a Ptime.date tuple (year, month, day).

When parsing from strings, partial dates are normalized:

  • Year: "2001" → (2001, 1, 1)
  • Year-Month: "2001-01" → (2001, 1, 1)
  • Full date: "2001-01-15" → (2001, 1, 15)

Date Conversion

val parse_date_string : string -> date option

parse_date_string s parses an ISO 8601 date string.

Accepts various formats with partial date support:

  • "2001" (year only) → (2001, 1, 1)
  • "2001-01" (year-month) → (2001, 1, 1)
  • "2001-01-15" (full date) → (2001, 1, 15)

Returns None if the string is not a valid date format.

val format_date : date -> string

format_date date formats a date as ISO 8601 (YYYY-MM-DD).

Example: format_date (2001, 1, 15) returns "2001-01-15"

Temporal Ranges

type range = {
  1. from : date option;
    (*

    Start date (inclusive). None means from the beginning.

    *)
  2. until : date option;
    (*

    End date (exclusive). None means continuing/indefinite.

    *)
}

A temporal range indicating validity period.

Range Construction

val make : ?from:date -> ?until:date -> unit -> range

make ?from ?until () creates a temporal range.

val always : range

always is a range that is always valid (no from/until bounds).

Range Queries

val valid_at : range option -> date:date -> bool

valid_at range ~date checks if range is valid at the given date.

  • None range means always valid
  • None from means valid from beginning
  • None until means valid continuing
val overlaps : range -> range -> bool

overlaps r1 r2 checks if two ranges overlap in time.

val is_current : range option -> bool

is_current range checks if range is valid at the current date. Uses today's date for the check.

List Filtering

val current : get:('a -> range option) -> 'a list -> 'a option

current ~get list returns the first current/valid item from list.

  • parameter get

    Function to extract the temporal range from an item. Returns the first item where the range is currently valid, or the first item without temporal bounds if none are current.

val at_date : get:('a -> range option) -> date:date -> 'a list -> 'a list

at_date ~get ~date list filters list to items valid at date.

  • parameter get

    Function to extract the temporal range from an item.

  • parameter date

    The date to check validity against.

val filter : get:('a -> range option) -> from:date option -> until:date option -> 'a list -> 'a list

filter ~get ~from ~until list filters list to items overlapping the period.

Returns items whose temporal range overlaps with the given period.

JSON Encoding

val json_t : range Jsont.t

json_t is the jsont encoder/decoder for temporal ranges.

Encodes as a JSON object with optional from and until fields:

 { "from": "2001-01", "until": "2003-12" }

Empty object \{\} or missing field represents always.