.. _unique-ids: ****************** Unique identifiers ****************** .. highlight:: c :: #include The functions in this section let you define compile-time unique identifiers. These identifiers are simple C variables, and each one is guaranteed to be unique within the context of a single execution of your program. They are *not* appropriate for use as external identifiers --- for instance, for serializing into long-term storage or sending via a communications channel to another process. .. type:: cork_uid A unique identifier. .. macro:: cork_uid CORK_UID_NONE A unique identifier value that means "no identifier". This is guaranteed to be distinct from all other unique identifiers. It is invalid to call :c:func:`cork_uid_hash`, :c:func:`cork_uid_id`, or :c:func:`cork_uid_name` on this identifier. .. macro:: cork_uid_define(SYMBOL id) cork_uid_define_named(SYMBOL id, const char \*name) You use the :c:func:`cork_uid_define` macro to define a new unique identifier with the given C identifier *id*. The ``_define`` variant also uses *id* as the identifier's human-readable name; the ``_define_named`` variant let's you provide a separate human-readable name. Within the context of a single execution of this program, this identifier is guaranteed to be distinct from any other identifier, regardless of which library the identifiers are defined in. In the same compilation unit, you can then use the C identifier *id* to retrieve the :c:type:`cork_uid` instance for this identifier. .. note:: The unique identifier objects are declared ``static``, so they are only directly visible (using the C identifier *id*) in the same compilation unit as the :c:func:`cork_uid_define` call that created the identifier. The resulting :c:type:`cork_uid` value, however, can be passed around the rest of your code however you want. .. function:: bool cork_uid_equal(const cork_uid id1, const cork_uid id2) Return whether two :c:type:`cork_uid` values refer to the same unique identifier. .. function:: cork_hash cork_uid_hash(const cork_uid id) Return a :ref:`hash value ` for the given identifier. .. function:: const char \*cork_uid_name(const cork_uid id) Return the name of the given unique identifier. Example ======= :: #include #include cork_uid_define(test_id); int main(void) { cork_uid id = test_id; printf("Identifier %p has name %s\n", id, cork_uid_name(id)); return 0; }