.. _library_dates:

dates

The date object implements some useful calendar date predicates.

It also provides portable predicates for date-time handling, including:

• Unix epoch conversions (date_time_to_unix/2, unix_to_date_time/2)
• date-time arithmetic with durations (add_duration/3, subtract_duration/3, duration_between/3)
• UTC/local conversion using explicit offsets (utc_to_local/3, local_to_utc/3)
• date-time formatting with explicit offsets (format_date_time/4)
• calendar utilities (day_of_year/2, week_of_year_iso/2, weekday/2)
• reverse and positional calendar utilities (day_of_year_date/3, month_weekday_date/5)
• date-time normalization and validation (normalize_date_time/2, valid_date_time/1)
• date-time comparison (before/2, after/2, same_instant/2, compare_date_time/3)

  The duration predicates accept two duration representations:

• duration(Days, Hours, Minutes, Seconds) — a fixed-length duration converted to seconds
• duration(Years, Months, Days, Hours, Minutes, Seconds) — a calendar-aware period where the year and month delta is applied first using calendar arithmetic, clamping the day to the last valid day of the resulting month when necessary (e.g. adding one month to January 31 gives February 28 or 29 depending on the year), with the remaining day and time delta applied via fixed-length arithmetic. The duration_between/3 predicate returns this form when called with a 6-arity skeleton such as duration(Yr, Mo, Da, Hr, Mi, Se).

  Date-time values are represented using the date_time/6 compound term:

• date_time(Year, Month, Day, Hours, Minutes, Seconds) The format_date_time/4 predicate currently supports the named formats rfc3339, iso8601, atom, rfc2822, rfc5322, rss, http_date, rfc1123, unix_date, common_log, date_short, date_medium, date_long, date_full, time_short, time_medium, time_long, time_full, date_time_short, date_time_medium, date_time_long, and date_time_full.

  The explicit offset argument is given in seconds. Formats that include numeric offsets require offsets representable in whole minutes. The http_date and rfc1123 formats always normalize the output to GMT.

  The style presets are currently English-only presentation formats:

• date_short -> 2026-04-08
• date_medium -> 8 Apr 2026
• date_long -> April 8, 2026
• date_full -> Tuesday, April 8, 2026
• time_short -> 13:45
• time_medium -> 13:45:30
• time_long -> 13:45:30 +01:00
• time_full -> 1:45:30 PM +01:00
• date_time_short -> 2026-04-08 13:45
• date_time_medium -> 8 Apr 2026 13:45:30
• date_time_long -> April 8, 2026 1:45:30 PM +01:00
• date_time_full -> Tuesday, April 8, 2026 1:45:30 PM +01:00 The time object implements some useful time predicates.

  Please note that the functionality of these objects depends on the chosen Prolog support for accessing the operating system time and date.

API documentation

Open the `../../apis/library_index.html#dates <../../apis/library_index.html#dates>`__ link in a web browser.

Loading

To load all entities in this library, load the loader.lgt utility file:

::

| ?- logtalk_load(dates(loader)).

Testing

To test this library predicates, load the tester.lgt file:

::

| ?- logtalk_load(dates(tester)).