ulid

C++ port of oklog/ulid and alizain/ulid.

There are 2 implementations, the first in ulid_uint128.hh uses a __uint128_t to represent a ULID.

The second in ulid_struct.hh encapsulates a 16 byte array in a struct, and uses that to represent a ULID

ulid.hh essentially (tries to) see if __uint128_t exists, in which case it imports the definition in ulid_uint128.hh, otherwise it imports the implementation in ulid_struct.hh.

The __uint128_t version seems to be faster, some benchmarks below and more extensive ones on travis.

• Usage
• API
• Benchmarks

Usage

#include <ulid.hh>

...

ulid::ULID ulid = ulid::Create(1484581420, []() { return 4; });
std::string str = ulid::Marshal(ulid);
std::cout << str << '\n'; // 0001C7STHC0G2081040G208104

API

ulid::ULID

The wrapper type for a __uint128_t / 16 byte array representing a ULID.

void ulid::EncodeTime(time_t, ULID&)

encodes passed time in first 6 bytes of a ULID.

void ulid::EncodeTimeNow(ULID&)

encodes std::time(nullptr) as time.

void ulid::EncodeTimeSystemClockNow(ULID&)

encodes std::chrono::system_clock::now() by taking the timestamp in milliseconds.

void ulid::EncodeEntropy(const std::function<uint8_t()>&, ULID&)

sets the last 10 bytes as the values generated using the passed random byte generator.

void ulid::EncodeEntropyRand(ULID&)

sets the entropy using std::rand.

void ulid::EncodeEntropyMt19937(std::mt19937& generator, ULID& ulid)

sets the entropy by generating values from a std::mt19937 generator, initializes a std::uniform_int_distribution on each invocation.

void ulid::Encode(time_t, const std::function<uint8_t()>&, ULID&)

EncodeTime + EncodeEntropy

void ulid::EncodeNowRand(time_t, const std::function<uint8_t()>&, ULID&)

EncodeTimeNow + EncodeEntropyRand

ulid::ULID ulid::Create(time_t, const std::function<uint8_t()>&)

creates a fresh ULID using the passed timestamp and generator.

void ulid::CreateNowRand()

Create:Encode::CreateNowRand:EncodeNowRand

void ulid::MarshalTo(const ULID&, char[26])

Marshals the ulid into the passed character array.

std::string ulid::Marshal(const ULID&)

Marshals and generates std::string.

void ulid::MarshalBinaryTo(const ULID&, uint8_t[16])

Marshals the ulid into the passed byte array.

std::vector<uint8_t> ulid::MarshalBinary(const ULID&)

Marshals and generates std::vector<uint8_t>.

void ulid::UnmarshalFrom(const char[26], ULID&)

Unmarshals the passed character array into the ulid.

ULID ulid::Unmarshal(const std::string&)

Creates a new ULID by Unmarshaling the passed string.

void ulid::UnmarshalBinaryFrom(const uint8_t[26], ULID&)

Unmarshals the passed byte array into the ulid.

ULID ulid::UnmarshalBinary(const std::vector<uint8_t>&)

Creates a new ULID by Unmarshaling the passed vector.

time_t ulid::Time(const ULID&)

Extracts the timestamp used to create the ULID.

Benchmarks

Ubuntu Xenial (16.04), clang++-8

From https://travis-ci.org/suyash/ulid/jobs/475187043

ulid_uint128

./ulid_uint128_bench.out --benchmark_out_format=console
2019-01-04 07:11:24
Running ./ulid_uint128_bench.out
Run on (2 X 2500 MHz CPU s)
CPU Caches:
  L1 Data 32K (x1)
  L1 Instruction 32K (x1)
  L2 Unified 256K (x1)
  L3 Unified 30720K (x1)
Load Average: 0.98, 0.51, 0.21
--------------------------------------------------------------------
Benchmark                         Time             CPU   Iterations
--------------------------------------------------------------------
EncodeTime                     23.2 ns         23.2 ns     30323833
EncodeTimeNow                  26.8 ns         26.7 ns     25925285
EncodeTimeSystemClockNow       96.4 ns         96.4 ns      7366207
EncodeEntropy                   209 ns          209 ns      3363959
EncodeEntropyRand               100 ns          100 ns      6875073
EncodeEntropyMt19937            470 ns          469 ns      1481254
Encode                          231 ns          231 ns      3022655
EncodeNowRand                   128 ns          128 ns      5346738
Create                          238 ns          238 ns      2970710
CreateNowRand                   133 ns          133 ns      5384520
MarshalTo                      37.5 ns         37.5 ns     18655071
Marshal                        83.7 ns         83.7 ns      8261322
MarshalBinaryTo                16.7 ns         16.7 ns     41790384
MarshalBinary                   157 ns          157 ns      4464307
UnmarshalFrom                  64.0 ns         63.9 ns     10822292
Unmarshal                       113 ns          113 ns      6146163
UnmarshalBinaryFrom            64.8 ns         64.8 ns     10942429
UnmarshalBinary                 248 ns          248 ns      2832217
Time                           15.0 ns         15.0 ns     46389021
CompareULIDs                   8.44 ns         8.44 ns     83106152

ulid_struct

./ulid_struct_bench.out --benchmark_out_format=console
2019-01-04 07:11:43
Running ./ulid_struct_bench.out
Run on (2 X 2500 MHz CPU s)
CPU Caches:
  L1 Data 32K (x1)
  L1 Instruction 32K (x1)
  L2 Unified 256K (x1)
  L3 Unified 30720K (x1)
Load Average: 0.99, 0.54, 0.22
--------------------------------------------------------------------
Benchmark                         Time             CPU   Iterations
--------------------------------------------------------------------
EncodeTime                     9.14 ns         9.13 ns     76851483
EncodeTimeNow                  12.6 ns         12.6 ns     55315496
EncodeTimeSystemClockNow       73.5 ns         73.5 ns      9515669
EncodeEntropy                   201 ns          201 ns      3480980
EncodeEntropyRand               196 ns          195 ns      3602452
EncodeEntropyMt19937            449 ns          449 ns      1560469
Encode                          211 ns          211 ns      3352107
EncodeNowRand                   204 ns          204 ns      3493016
Create                          217 ns          217 ns      3214903
CreateNowRand                   213 ns          213 ns      3271363
MarshalTo                      34.1 ns         34.1 ns     20540465
Marshal                        80.6 ns         80.5 ns      8743422
MarshalBinaryTo                17.6 ns         17.6 ns     39780449
MarshalBinary                   154 ns          154 ns      4503322
UnmarshalFrom                  33.3 ns         33.3 ns     20997275
Unmarshal                      88.5 ns         88.4 ns      7957903
UnmarshalBinaryFrom            17.0 ns         17.0 ns     41314026
UnmarshalBinary                 198 ns          198 ns      3541637
Time                           14.9 ns         14.9 ns     46747210
CompareULIDs                   20.6 ns         20.6 ns     34150306

For a comparison across latest 3 versions of g++ and clang++ on linux and clang++ on mac, see https://travis-ci.org/suyash/ulid/builds/475187039

Hacking

The library uses googletest for tests and benchmark as benchmarks, which are built as submodules. In order to get those dependencies, clone recursively, i.e.

git clone -r https://github.com/suyash/ulid