Home

Awesome

cuid-c

Cuids are "Collision-resistant ids optimised for horizontal scaling and binary search lookup performance."

This is an implementation of cuid in C.

All of the code is done in the cuid.h file.

API

Two API's are provided, the simplest and more convenient one is just the single function cuid().

There are macros defined for each syscall that can be overridden in order to match intended use cases. For more information on these please read the source code of cuid.h.

Pure API

An optional pure API is provided that can create cuid strings through pure functions that pass along a cuid_t state. This can be useful if you want better control over the moving parts of the cuid creation.

Define the macro CUID_PURE to enable the following functions:

On top of these a lot of customisation can be achieved by redefining the macros that the pure API uses. All of the random and counter creation/initialisation and generation functions can be overridden to match very specific needs.

Read the code of cuid.h after the CUID_PURE macro is defined if you want to know more on how to override the counter and random number generator.

Example Usage

#include "cuid.h"

// Create space for a cuid string:
char my_cuid[CUID_SIZE] = {0};

// Call the `cuid()` function and pass it the space for the cuid string.
cuid(my_cuid);

// A cuid string is now available in the `my_cuid` var.

Here is an example of the optional pure API.

#define CUID_PURE (1)
#include "cuid.h"

// Use any fingerprint function, here just a static string for example purposes
char const fingerprint[] = "iPad";

// The flow for the pure api is:
// create -> init -> read -> next -> (read -> next ->...)
cuid_t id = cuid_create(fingerprint);

// Use any specific timestamp functions, or just pass along an unsigned long
// for example purposes
unsigned long timestamp = 123456789;
id = cuid_init(id, timestamp);

// Create space for the cuid strings:
char my_first_cuid[CUID_SIZE] = {0};
char my_second_cuid[CUID_SIZE] = {0};

// Read the first cuid
cuid_read(id, my_first_cuid);

// Advance the cuid_t state (use a specific time-stamping function, here
// just increasing the timestamp for example purposes).
id = cuid_next(id, ++timestamp);

// Read the second cuid
cuid_read(id, my_second_cuid);

// The cuids `my_first_cuid` and `my_second_cuid` are different, however
// note that calling `cuid_read` multiple times without doing a `cuid_next`
// will always write the same string value to the provided array.