.. index:: single: ulid_protocol
.. _ulid_protocol/0:

.. rst-class:: right

**protocol**

``ulid_protocol``
=================

Universally Unique Lexicographically Sortable Identifier (ULID) generator protocol.

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

| **Author:** Paulo Moura
| **Version:** 1:1:0
| **Date:** 2026-07-06

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


| **Dependencies:**
|   (none)


| **Remarks:**
|    (none)

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

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

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

.. index:: generate/1
.. _ulid_protocol/0::generate/1:

``generate/1``
^^^^^^^^^^^^^^

Generates a new ULID.

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

| **Template:**
|    ``generate(ULID)``
| **Mode and number of proofs:**
|    ``generate(--ulid)`` - ``one_or_error``

| **Exceptions:**
|    The representation parameter is a variable:
|        ``instantiation_error``
|    The representation parameter is not a variable but also neither ``atom``, ``chars``, nor ``codes``:
|        ``domain_error(ulid_representation,Representation)``


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

.. index:: generate/2
.. _ulid_protocol/0::generate/2:

``generate/2``
^^^^^^^^^^^^^^

Generates a new ULID from a timestamp (number of milliseconds since the Unix epoch: 00:00:00 UTC on January 1, 1970).

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

| **Template:**
|    ``generate(Milliseconds,ULID)``
| **Mode and number of proofs:**
|    ``generate(+integer,--ulid)`` - ``one_or_error``

| **Exceptions:**
|    The representation parameter is a variable:
|        ``instantiation_error``
|    The representation parameter is not a variable but also neither ``atom``, ``chars``, nor ``codes``:
|        ``domain_error(ulid_representation,Representation)``
|    ``Milliseconds`` is a variable:
|        ``instantiation_error``
|    ``Milliseconds`` is neither a variable nor an integer:
|        ``type_error(integer,Milliseconds)``
|    ``Milliseconds`` is outside the 48-bit range required by the ULID specification:
|        ``domain_error(ulid_timestamp,Milliseconds)``


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

.. index:: generate/8
.. _ulid_protocol/0::generate/8:

``generate/8``
^^^^^^^^^^^^^^

Generates a new ULID from a timestamp discrete components.

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

| **Template:**
|    ``generate(Year,Month,Day,Hours,Minutes,Seconds,Milliseconds,ULID)``
| **Mode and number of proofs:**
|    ``generate(+integer,+integer,+integer,+integer,+integer,+integer,+integer,--ulid)`` - ``one_or_error``

| **Exceptions:**
|    The representation parameter is a variable:
|        ``instantiation_error``
|    The representation parameter is not a variable but also neither ``atom``, ``chars``, nor ``codes``:
|        ``domain_error(ulid_representation,Representation)``
|    ``Milliseconds`` is a variable:
|        ``instantiation_error``
|    ``Milliseconds`` is neither a variable nor an integer:
|        ``type_error(integer,Milliseconds)``
|    ``Milliseconds`` is an integer but outside the 0..999 range:
|        ``domain_error(ulid_millisecond,Milliseconds)``
|    The timestamp is outside the 48-bit range required by the ULID specification:
|        ``domain_error(ulid_timestamp,Timestamp)``


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

.. index:: timestamp/2
.. _ulid_protocol/0::timestamp/2:

``timestamp/2``
^^^^^^^^^^^^^^^

Returns the given ULID timestamp (number of milliseconds since the Unix epoch: 00:00:00 UTC on January 1, 1970).

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

| **Template:**
|    ``timestamp(ULID,Milliseconds)``
| **Mode and number of proofs:**
|    ``timestamp(++ulid,-integer)`` - ``one_or_error``

| **Exceptions:**
|    The representation parameter is a variable:
|        ``instantiation_error``
|    The representation parameter is not a variable but also neither ``atom``, ``chars``, nor ``codes``:
|        ``domain_error(ulid_representation,Representation)``
|    ``ULID`` is a variable:
|        ``instantiation_error``
|    ``ULID`` is neither a variable nor an atom when using the ``atom`` representation:
|        ``type_error(atom,ULID)``
|    ``ULID`` is neither a variable nor a list of characters when using the ``chars`` representation:
|        ``type_error(chars,ULID)``
|    ``ULID`` is neither a variable nor a list of character codes when using the ``codes`` representation:
|        ``type_error(codes,ULID)``
|    ``ULID`` is not a valid ULID:
|        ``domain_error(ulid,ULID)``


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

.. index:: timestamp/8
.. _ulid_protocol/0::timestamp/8:

``timestamp/8``
^^^^^^^^^^^^^^^

Decodes a ULID into its timestamp discrete components.

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

| **Template:**
|    ``timestamp(ULID,Year,Month,Day,Hours,Minutes,Seconds,Milliseconds)``
| **Mode and number of proofs:**
|    ``timestamp(++ulid,-integer,-integer,-integer,-integer,-integer,-integer,-integer)`` - ``one_or_error``

| **Exceptions:**
|    The representation parameter is a variable:
|        ``instantiation_error``
|    The representation parameter is not a variable but also neither ``atom``, ``chars``, nor ``codes``:
|        ``domain_error(ulid_representation,Representation)``
|    ``ULID`` is a variable:
|        ``instantiation_error``
|    ``ULID`` is neither a variable nor an atom when using the ``atom`` representation:
|        ``type_error(atom,ULID)``
|    ``ULID`` is neither a variable nor a list of characters when using the ``chars`` representation:
|        ``type_error(chars,ULID)``
|    ``ULID`` is neither a variable nor a list of character codes when using the ``codes`` representation:
|        ``type_error(codes,ULID)``
|    ``ULID`` is not a valid ULID:
|        ``domain_error(ulid,ULID)``


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

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

(none)

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

(none)

Operators
---------

(none)

