.. index:: single: datep
.. _datep/0:

.. rst-class:: right

**protocol**

``datep``
=========

Date protocol.

| **Availability:** 
|    ``logtalk_load(dates(loader))``

| **Author:** Paulo Moura
| **Version:** 2:3:0
| **Date:** 2026-04-08

| **Compilation flags:**
|    ``static``


| **Dependencies:**
|   (none)


| **Remarks:**
|    (none)

| **Inherited public predicates:**
|    (none)

.. contents::
   :local:
   :backlinks: top

Public predicates
-----------------

.. index:: today/3
.. _datep/0::today/3:

``today/3``
^^^^^^^^^^^

Returns current date.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``today(Year,Month,Day)``
| **Mode and number of proofs:**
|    ``today(-integer,-integer,-integer)`` - ``one``


------------

.. index:: leap_year/1
.. _datep/0::leap_year/1:

``leap_year/1``
^^^^^^^^^^^^^^^

True if the argument is a leap year.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``leap_year(Year)``
| **Mode and number of proofs:**
|    ``leap_year(+integer)`` - ``zero_or_one``


------------

.. index:: name_of_day/3
.. _datep/0::name_of_day/3:

``name_of_day/3``
^^^^^^^^^^^^^^^^^

Name and short name of day using ISO weekday numbering (Monday=1, ..., Sunday=7).

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``name_of_day(Index,Name,Short)``
| **Mode and number of proofs:**
|    ``name_of_day(?integer,?atom,?atom)`` - ``zero_or_more``


------------

.. index:: name_of_month/3
.. _datep/0::name_of_month/3:

``name_of_month/3``
^^^^^^^^^^^^^^^^^^^

Name and short name of month.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``name_of_month(Index,Name,Short)``
| **Mode and number of proofs:**
|    ``name_of_month(?integer,?atom,?atom)`` - ``zero_or_more``


------------

.. index:: days_in_month/3
.. _datep/0::days_in_month/3:

``days_in_month/3``
^^^^^^^^^^^^^^^^^^^

Number of days in a month.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``days_in_month(Month,Year,Days)``
| **Mode and number of proofs:**
|    ``days_in_month(?integer,+integer,?integer)`` - ``zero_or_more``


------------

.. index:: valid/3
.. _datep/0::valid/3:

``valid/3``
^^^^^^^^^^^

True if the arguments represent a valid date.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``valid(Year,Month,Day)``
| **Mode and number of proofs:**
|    ``valid(@integer,@integer,@integer)`` - ``zero_or_one``


------------

.. index:: date_time_to_unix/2
.. _datep/0::date_time_to_unix/2:

``date_time_to_unix/2``
^^^^^^^^^^^^^^^^^^^^^^^

Converts a UTC date-time term ``date_time(Year,Month,Day,Hours,Minutes,Seconds)`` to Unix epoch seconds.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``date_time_to_unix(DateTime,UnixTime)``
| **Mode and number of proofs:**
|    ``date_time_to_unix(+compound,-integer)`` - ``zero_or_one``


------------

.. index:: unix_to_date_time/2
.. _datep/0::unix_to_date_time/2:

``unix_to_date_time/2``
^^^^^^^^^^^^^^^^^^^^^^^

Converts Unix epoch seconds to a UTC date-time term ``date_time(Year,Month,Day,Hours,Minutes,Seconds)``.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``unix_to_date_time(UnixTime,DateTime)``
| **Mode and number of proofs:**
|    ``unix_to_date_time(+integer,-compound)`` - ``one``


------------

.. index:: add_duration/3
.. _datep/0::add_duration/3:

``add_duration/3``
^^^^^^^^^^^^^^^^^^

Adds a duration to a datetime. Duration can be integer seconds, ``duration(Days,Hours,Minutes,Seconds)``, or a calendar-aware ``duration(Years,Months,Days,Hours,Minutes,Seconds)``. For the 6-arity form, 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. January 31 plus one month gives February 28 or 29), and the remaining day and time delta is then applied via fixed-length arithmetic.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``add_duration(DateTime,Duration,ResultDateTime)``
| **Mode and number of proofs:**
|    ``add_duration(+compound,+nonvar,-compound)`` - ``zero_or_one``


------------

.. index:: subtract_duration/3
.. _datep/0::subtract_duration/3:

``subtract_duration/3``
^^^^^^^^^^^^^^^^^^^^^^^

Subtracts a duration from a datetime. Duration can be integer seconds, ``duration(Days,Hours,Minutes,Seconds)``, or a calendar-aware ``duration(Years,Months,Days,Hours,Minutes,Seconds)``. For the 6-arity form, the year and month delta is subtracted first using calendar arithmetic with end-of-month day clamping, and the remaining day and time delta is then subtracted via fixed-length arithmetic.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``subtract_duration(DateTime,Duration,ResultDateTime)``
| **Mode and number of proofs:**
|    ``subtract_duration(+compound,+nonvar,-compound)`` - ``zero_or_one``


------------

.. index:: duration_between/3
.. _datep/0::duration_between/3:

``duration_between/3``
^^^^^^^^^^^^^^^^^^^^^^

Computes the difference between two datetimes as integer seconds, as ``duration(Days,Hours,Minutes,Seconds)``, or as a calendar-aware ``duration(Years,Months,Days,Hours,Minutes,Seconds)``. For the 6-arity form, the year and month components count the largest whole number of calendar months between the two datetimes (consistent with the day-clamping semantics of ``add_duration/3``), and the remaining days and time fields are the exact residual. For backward intervals all fields are negative.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``duration_between(StartDateTime,EndDateTime,Duration)``
| **Mode and number of proofs:**
|    ``duration_between(+compound,+compound,?term)`` - ``zero_or_one``


------------

.. index:: utc_to_local/3
.. _datep/0::utc_to_local/3:

``utc_to_local/3``
^^^^^^^^^^^^^^^^^^

Converts a UTC datetime to a local datetime using an explicit timezone offset atom (``Z`` or ``±HH:MM``).

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``utc_to_local(UTCDateTime,Offset,LocalDateTime)``
| **Mode and number of proofs:**
|    ``utc_to_local(+compound,+atom,-compound)`` - ``zero_or_one``


------------

.. index:: local_to_utc/3
.. _datep/0::local_to_utc/3:

``local_to_utc/3``
^^^^^^^^^^^^^^^^^^

Converts a local datetime to UTC using an explicit timezone offset atom (``Z`` or ``±HH:MM``).

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``local_to_utc(LocalDateTime,Offset,UTCDateTime)``
| **Mode and number of proofs:**
|    ``local_to_utc(+compound,+atom,-compound)`` - ``zero_or_one``


------------

.. index:: format_date_time/4
.. _datep/0::format_date_time/4:

``format_date_time/4``
^^^^^^^^^^^^^^^^^^^^^^

Formats a date-time using an explicit UTC offset in seconds. Supported format identifiers are ``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``. RFC 3339, ISO 8601, Atom, and the ``date_*`` and ``date_time_*`` styles require a four-digit non-negative year. Formats that include numeric offsets require an offset expressible in whole minutes. HTTP-date and RFC 1123 output are always normalized to GMT. The style presets are English-only presentation formats. Fails if the format or date-time are not valid.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``format_date_time(DateTime,OffsetSeconds,Format,String)``
| **Mode and number of proofs:**
|    ``format_date_time(+compound,+integer,+atom,-atom)`` - ``zero_or_one``


------------

.. index:: day_of_year/2
.. _datep/0::day_of_year/2:

``day_of_year/2``
^^^^^^^^^^^^^^^^^

Computes the day of year (1-366) for a ``date(Year,Month,Day)`` or ``date_time(...)`` term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``day_of_year(DateLike,DayOfYear)``
| **Mode and number of proofs:**
|    ``day_of_year(+compound,?integer)`` - ``zero_or_one``


------------

.. index:: day_of_year_date/3
.. _datep/0::day_of_year_date/3:

``day_of_year_date/3``
^^^^^^^^^^^^^^^^^^^^^^

Computes the calendar date corresponding to a year and day of year (1-366) as ``date(Year,Month,Day)``.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``day_of_year_date(Year,DayOfYear,Date)``
| **Mode and number of proofs:**
|    ``day_of_year_date(+integer,+integer,-compound)`` - ``zero_or_one``


------------

.. index:: month_weekday_date/5
.. _datep/0::month_weekday_date/5:

``month_weekday_date/5``
^^^^^^^^^^^^^^^^^^^^^^^^

Computes the calendar date for the nth or last weekday in a month as ``date(Year,Month,Day)``. Week values 1-4 select the nth weekday and week value 5 selects the last one. Weekday uses ISO numbering (Monday=1, ..., Sunday=7).

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``month_weekday_date(Year,Month,Week,Weekday,Date)``
| **Mode and number of proofs:**
|    ``month_weekday_date(+integer,+integer,+integer,+integer,-compound)`` - ``zero_or_one``


------------

.. index:: week_of_year_iso/2
.. _datep/0::week_of_year_iso/2:

``week_of_year_iso/2``
^^^^^^^^^^^^^^^^^^^^^^

Computes ISO week for a ``date(Year,Month,Day)`` or ``date_time(...)`` term as ``week(Week,Year)``.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``week_of_year_iso(DateLike,ISOWeek)``
| **Mode and number of proofs:**
|    ``week_of_year_iso(+compound,?compound)`` - ``zero_or_one``


------------

.. index:: weekday/2
.. _datep/0::weekday/2:

``weekday/2``
^^^^^^^^^^^^^

Computes ISO weekday number (Monday=1, ..., Sunday=7) for a ``date(Year,Month,Day)`` or ``date_time(...)`` term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``weekday(DateLike,Weekday)``
| **Mode and number of proofs:**
|    ``weekday(+compound,?integer)`` - ``zero_or_one``


------------

.. index:: normalize_date_time/2
.. _datep/0::normalize_date_time/2:

``normalize_date_time/2``
^^^^^^^^^^^^^^^^^^^^^^^^^

Normalizes a datetime term by carrying overflows/underflows in date and time fields.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``normalize_date_time(DateTime,NormalizedDateTime)``
| **Mode and number of proofs:**
|    ``normalize_date_time(+compound,-compound)`` - ``one``


------------

.. index:: valid_date_time/1
.. _datep/0::valid_date_time/1:

``valid_date_time/1``
^^^^^^^^^^^^^^^^^^^^^

True iff a datetime term is valid in strict mode.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``valid_date_time(DateTime)``
| **Mode and number of proofs:**
|    ``valid_date_time(@compound)`` - ``zero_or_one``


------------

.. index:: before/2
.. _datep/0::before/2:

``before/2``
^^^^^^^^^^^^

True iff ``DateTime1`` represents an instant strictly before ``DateTime2``.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``before(DateTime1,DateTime2)``
| **Mode and number of proofs:**
|    ``before(+compound,+compound)`` - ``zero_or_one``


------------

.. index:: after/2
.. _datep/0::after/2:

``after/2``
^^^^^^^^^^^

True iff ``DateTime1`` represents an instant strictly after ``DateTime2``.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``after(DateTime1,DateTime2)``
| **Mode and number of proofs:**
|    ``after(+compound,+compound)`` - ``zero_or_one``


------------

.. index:: same_instant/2
.. _datep/0::same_instant/2:

``same_instant/2``
^^^^^^^^^^^^^^^^^^

True iff ``DateTime1`` and ``DateTime2`` represent the same instant (equal Unix epoch seconds).

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``same_instant(DateTime1,DateTime2)``
| **Mode and number of proofs:**
|    ``same_instant(+compound,+compound)`` - ``zero_or_one``


------------

.. index:: compare_date_time/3
.. _datep/0::compare_date_time/3:

``compare_date_time/3``
^^^^^^^^^^^^^^^^^^^^^^^

Three-way comparison of two datetime terms. ``Order`` is unified with ``<``, ``=``, or ``>``. Suitable for use with ``sort/3``.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``compare_date_time(Order,DateTime1,DateTime2)``
| **Mode and number of proofs:**
|    ``compare_date_time(?atom,+compound,+compound)`` - ``zero_or_one``


------------

Protected predicates
--------------------

(none)

Private predicates
------------------

(none)

Operators
---------

(none)

.. seealso::

   :ref:`date <date/0>`, :ref:`timep <timep/0>`

