uuidv7.h File Reference

uuidv7.h - Single-file C/C++ UUIDv7 Library More...

#include <stddef.h>
#include <stdint.h>

Go to the source code of this file.

Macros
Status codes returned by uuidv7_generate()
#define	UUIDV7_STATUS_UNPRECEDENTED   (0)
	Indicates that the unix_ts_ms passed was used because no preceding UUID was specified.
#define	UUIDV7_STATUS_NEW_TIMESTAMP   (1)
	Indicates that the unix_ts_ms passed was used because it was greater than the previous one.
#define	UUIDV7_STATUS_COUNTER_INC   (2)
	Indicates that the counter was incremented because the unix_ts_ms passed was no greater than the previous one.
#define	UUIDV7_STATUS_TIMESTAMP_INC   (3)
	Indicates that the previous unix_ts_ms was incremented because the counter reached its maximum value.
#define	UUIDV7_STATUS_CLOCK_ROLLBACK   (4)
	Indicates that the monotonic order of generated UUIDs was broken because the unix_ts_ms passed was less than the previous one by more than ten seconds.
#define	UUIDV7_STATUS_ERR_TIMESTAMP   (-1)
	Indicates that an invalid unix_ts_ms is passed.
#define	UUIDV7_STATUS_ERR_TIMESTAMP_OVERFLOW   (-2)
	Indicates that the attempt to increment the previous unix_ts_ms failed because it had reached its maximum value.

Functions
Low-level primitives
static int8_t	uuidv7_generate (uint8_t *uuid_out, uint64_t unix_ts_ms, const uint8_t *rand_bytes, const uint8_t *uuid_prev)
	Generates a new UUIDv7 from the given Unix time, random bytes, and previous UUID.
static int	uuidv7_status_n_rand_consumed (int8_t status)
	Determines the number of random bytes consumsed by uuidv7_generate() from the UUIDV7_STATUS_* code returned.
static void	uuidv7_to_string (const uint8_t *uuid, char *string_out)
	Encodes a UUID in the 8-4-4-4-12 hexadecimal string representation.
static int	uuidv7_from_string (const char *string, uint8_t *uuid_out)
	Decodes the 8-4-4-4-12 hexadecimal string representation of a UUID.
High-level APIs that require platform integration
int	uuidv7_new (uint8_t *uuid_out)
	Generates a new UUIDv7 with the current Unix time.
static int	uuidv7_new_string (char *string_out)
	Generates an 8-4-4-4-12 hexadecimal string representation of new UUIDv7.

Detailed Description

uuidv7.h - Single-file C/C++ UUIDv7 Library

Version

v0.1.6

Author

LiosK

Copyright

Licensed under the Apache License, Version 2.0

See also

https://github.com/LiosK/uuidv7-h

Function Documentation

uuidv7_from_string()

static int uuidv7_from_string ( const char * string, uint8_t * uuid_out )

inlinestatic

Decodes the 8-4-4-4-12 hexadecimal string representation of a UUID.

Parameters

string	37-byte (36 digits + NUL) character array representing the 8-4-4-4-12 hexadecimal string representation.
uuid_out	16-byte byte array where the decoded UUID is stored.

Returns

Zero on success or non-zero integer on failure.

uuidv7_generate()

static int8_t uuidv7_generate ( uint8_t * uuid_out, uint64_t unix_ts_ms, const uint8_t * rand_bytes, const uint8_t * uuid_prev )

inlinestatic

Generates a new UUIDv7 from the given Unix time, random bytes, and previous UUID.

Parameters

uuid_out	16-byte byte array where the generated UUID is stored.
unix_ts_ms	Current Unix time in milliseconds.
rand_bytes	At least 10-byte byte array filled with random bytes. This function consumes the leading 4 bytes or the whole 10 bytes per call depending on the conditions. uuidv7_status_n_rand_consumed() maps the return value of this function to the number of random bytes consumed.
uuid_prev	16-byte byte array representing the immediately preceding UUID, from which the previous timestamp and counter are extracted. This may be NULL if the caller does not care the ascending order of UUIDs within the same timestamp. This may point to the same location as uuid_out; this function reads the value before writing.

Returns

One of the UUIDV7_STATUS_* codes that describe the characteristics of generated UUIDs. Callers can usually ignore the status unless they need to guarantee the monotonic order of UUIDs or fine-tune the generation process.

uuidv7_new()

int uuidv7_new

(

uint8_t *

uuid_out

)

Generates a new UUIDv7 with the current Unix time.

This declaration defines the interface to generate a new UUIDv7 with the current time, default random number generator, and global shared state holding the previously generated UUID. Since this single-file library does not provide platform-specific implementations, users need to prepare a concrete implementation (if necessary) by integrating a real-time clock, cryptographically strong random number generator, and shared state storage available in the target platform.

Parameters

uuid_out

16-byte byte array where the generated UUID is stored.

Returns

One of the UUIDV7_STATUS_* codes that describe the characteristics of generated UUIDs or an implementation-dependent code. Callers can usually ignore the UUIDV7_STATUS_* code unless they need to guarantee the monotonic order of UUIDs or fine-tune the generation process. The implementation-dependent code must be out of the range of int8_t and negative if it reports an error.

uuidv7_new_string()

static int uuidv7_new_string ( char * string_out )

inlinestatic

Generates an 8-4-4-4-12 hexadecimal string representation of new UUIDv7.

Parameters

string_out

Character array where the encoded string is stored. Its length must be 37 (36 digits + NUL) or longer.

Returns

Return value of uuidv7_new().

Note

Provide a concrete uuidv7_new() implementation to enable this function.

uuidv7_status_n_rand_consumed()

static int uuidv7_status_n_rand_consumed ( int8_t status )

inlinestatic

Determines the number of random bytes consumsed by uuidv7_generate() from the UUIDV7_STATUS_* code returned.

Parameters

status

UUIDV7_STATUS_* code returned by uuidv7_generate().

Returns

4 if status is UUIDV7_STATUS_COUNTER_INC or 10 otherwise.

uuidv7_to_string()

static void uuidv7_to_string ( const uint8_t * uuid, char * string_out )

inlinestatic

Encodes a UUID in the 8-4-4-4-12 hexadecimal string representation.

Parameters

uuid	16-byte byte array representing the UUID to encode.
string_out	Character array where the encoded string is stored. Its length must be 37 (36 digits + NUL) or longer.