Sortable Unique ID

Data Structures
struct	SUID
	128-bit sortable unique identifier More...

Typedefs
typedef struct SUID	SUID
	128-bit sortable unique identifier

Functions
bool	suidEq (const SUID *a, const SUID *b)
int	suidCmp (const SUID *a, const SUID *b)
void	suidGen (SUID *out, uint8 idtype)
void	suidGenPrivate (SUID *out, uint8 idtype)
void	suidEncode (string *out, const SUID *id)
void	suidEncodeBytes (_Out_writes_all_(26) uint8 buf[26], const SUID *id)
bool	suidDecode (SUID *out, strref str)
bool	suidDecodeBytes (SUID *out, _In_reads_(26) const char buf[26])

Detailed Description

SUID (Sortable Unique ID) is a 128-bit identifier loosely based on Alizain Feerasta's ULID. It provides lexicographically sortable unique identifiers with the following structure:

• 8 bits: Application-defined ID type
• 48 bits: Timestamp (milliseconds since UNIX epoch)
• 40 bits: Host ID
• 32 bits: Random/monotonic sequence

SUIDs are designed to be:

• Sortable: IDs generated later will sort after earlier IDs
• Unique: Combination of timestamp, host ID, and random data ensures uniqueness
• Compact: 128 bits encoded as 26-character base32 strings
• Fast: Efficient generation with thread-local state

Example usage:

SUID id;
suidGen(&id, 1);  // Generate ID with type 1
 
string str = 0;
suidEncode(&str, &id);  // Encode to string
// str now contains something like: "01an4z07by79ka1307sr74wdk0"
 
SUID decoded;
if (suidDecode(&decoded, str)) {
    // Successfully decoded
}
strDestroy(&str);

See https://github.com/ulid/spec for ULID specification details.

Function Documentation

suidCmp()

int suidCmp ( const SUID *  a, const SUID *  b  )

inline

int suidCmp(const SUID *a, const SUID *b);

Compare two SUIDs for sorting order. SUIDs are compared lexicographically, with earlier timestamps sorting first.

Parameters

a	First SUID to compare
b	Second SUID to compare

Returns

Negative if a < b, 0 if a == b, positive if a > b

Definition at line 70 of file suid.h.

suidDecode()

bool suidDecode	(	SUID *	out,
		strref	str
	)

Decode a SUID from a string.

Decodes a 26-character base32 encoded string back into a SUID structure. The decoder is case-insensitive and accepts the Crockford base32 alphabet. Ambiguous characters (i/l become 1, o becomes 0) are automatically normalized.

Parameters

out	Output SUID structure to populate
str	String containing encoded SUID (must be at least 26 characters)

Returns

true if decoding succeeded, false if the string is invalid

suidDecodeBytes()

bool suidDecodeBytes	(	SUID *	out,
		_In_reads_(26) const char	buf[26]
	)

Decode a SUID from a byte buffer.

Similar to suidDecode() but reads from a 26-byte buffer instead of a string object. The buffer must contain exactly 26 bytes of valid base32 encoded data.

Parameters

out	Output SUID structure to populate
buf	Buffer containing 26 bytes of encoded SUID

Returns

true if decoding succeeded, false if the buffer contains invalid data

suidEncode()

void suidEncode	(	string *	out,
		const SUID *	id
	)

Encode a SUID into a string.

Encodes the SUID as a 26-character lowercase base32 string using the Crockford base32 alphabet (0-9, a-z excluding i, l, o, u). The encoding is lexicographically sortable - earlier SUIDs will sort before later ones when compared as strings.

Parameters

out	String to receive the encoded result (will be cleared first)
id	SUID to encode

suidEncodeBytes()

void suidEncodeBytes	(	_Out_writes_all_(26) uint8	buf[26],
		const SUID *	id
	)

Encode a SUID into a byte buffer.

Similar to suidEncode() but writes the 26-character encoded result directly to a byte buffer instead of a string object. The buffer must be at least 26 bytes long.

Parameters

buf	Output buffer for 26-byte encoded result
id	SUID to encode

suidEq()

bool suidEq ( const SUID *  a, const SUID *  b  )

inline

bool suidEq(const SUID *a, const SUID *b);

Compare two SUIDs for equality.

Parameters

a	First SUID to compare
b	Second SUID to compare

Returns

true if the SUIDs are equal, false otherwise

Definition at line 58 of file suid.h.

suidGen()

void suidGen	(	SUID *	out,
		uint8	idtype
	)

Generate a unique SUID using the system's host ID.

Generates a new SUID with the current timestamp and the machine's host ID. The host ID is derived from hardware identifiers (MAC address, disk serial, etc.) to ensure uniqueness across different machines. Multiple SUIDs generated within the same millisecond will have monotonically increasing sequence numbers.

Parameters

out	Output SUID structure to populate
idtype	Application-specific identifier (stored in high 8 bits)

suidGenPrivate()

void suidGenPrivate	(	SUID *	out,
		uint8	idtype
	)

Generate a unique SUID using a random host ID.

Similar to suidGen(), but uses a randomly generated host ID instead of the system's hardware-derived host ID. This is useful for privacy-sensitive applications where you don't want to leak hardware identifiers, or for temporary/ephemeral identifiers.

Parameters

out	Output SUID structure to populate
idtype	Application-specific identifier (stored in high 8 bits)