Introduce the `ulid` module

[TarantoolBot]

Product: Tarantool, Tarantool DB 3.1
Since: tarantool 3.6?
Root document: https://www.tarantool.io/en/doc/latest/reference/reference_lua/
SME: @ vakhov

Details

The ulid module provides support for ULIDs (Universally Unique
Lexicographically Sortable Identifiers) in Tarantool. A ULID is a
128-bit value composed of a 48-bit millisecond timestamp and an
80-bit randomness part, encoded as a 26-character Crockford Base32
string. In binary form ULIDs are represented as 16-byte values in
big-endian byte order, in accordance with the ULID specification.

The builtin generator guarantees that multiple ULIDs produced within
the same millisecond are strictly increasing, providing stable
lexicographic ordering.

API overview:

• ulid() / ulid.new() — create a new ULID object
• ulid.str() — generate and return a ULID string
• ulid.bin() — generate and return a binary ULID (16 bytes)
• ulid.fromstr(str) — parse ULID from a 26-char string
• ulid.frombin(bin) — parse ULID from 16-byte binary data
• ulid.is_ulid(x) — check if x is a ULID object
• ulid.NULL — the all-zero ULID
• methods on ULID objects:
  :str() — encode as string
  :bin() — encode as binary
  :isnil() — check if ULID is all-zero

Examples:

tarantool> ulid = require('ulid')

...
-- creating ULIDs in different formats
tarantool> u_obj = ulid.new()
tarantool> u_str = ulid.str()
tarantool> u_bin = ulid.bin()

tarantool> u_obj, u_str, u_bin

• 06DDHQAGEX77Z196F5Z4B43G0W
• 06DDHQAGEX77Z196F5Z4B43G10
• "\x01\x9A\xD8\xDDPwN\x7F\x85&y~E\x90p\t"
  ...

String and binary conversions:

tarantool> s = ulid.str()
tarantool> u = ulid.fromstr(s)
tarantool> u:str() == s

• true
  ...

tarantool> b = u:bin()
tarantool> u2 = ulid.frombin(b)
tarantool> u2 == u

• true
  ...

Using ulid.NULL:

tarantool> ulid.NULL

• 00000000000000000000000000
  ...

tarantool> ulid.NULL:isnil()

• true
  ...

Comparing ULIDs:

ULID objects implement lexicographic ordering and can be compared
directly or against ULID strings:

tarantool> a = ulid.new()
tarantool> b = ulid.new()
tarantool> a < b

• true
  ...

tarantool> a_str = a:str()
tarantool> a == a_str

• true
  ...

Invalid input:

tarantool> ulid.fromstr('not-a-ulid')

• null
  ...

tarantool> ulid.fromstr(('0'):rep(25)) -- wrong length

• null
  ...
  Requested by @vakhov in tarantool/tarantool@eaa9354.