Xid.Net

Ported from https://github.com/rs/xid - A fast, low allocation, zero config, thread-safe 12 byte UUID generator based on the Mongo Object Id algorithm.

View on GitHub

Xid.Net - Globally Unique ID Generator

This project is a .Net port (with modifications) of https://github.com/rs/xid by Olivier Poitrey. Significant parts of the code and this readme are based on that project.

Xid.Net is a globally unique id generator library, ready to be used safely and directly in your code. It provides an interface similar to System.Guid but generates ids which are smaller (12 bytes vs 16 in raw format, 20 vs 36 when converted to a string). Generating Xids is faster than Guids, often significantly.

Xid uses the Mongo Object ID algorithm to generate globally unique ids with a different serialization (base32 vs base64) to make it shorter when transported as a string: https://docs.mongodb.org/manual/reference/object-id/.

GitHub license Build status NuGet Badge

Platforms

Install

    PM> Install-Package Xid.Net

Usage/API

Creating a Xid;

    var id = Xid.NewXid();

Converting to Xid to a string;

    var id = Xid.NewXid();
    var idString = id.ToString();

Converting a string to a Xid (TryParse method also provided);

    var idString = "9m4e2mr0ui3e8a215n4g";
    var id = Xid.Parse(idString);

Converting to Xid to a byte array;

    var id = Xid.NewXid();
    var bytes = id.ToBytes();

or

    var id = Xid.NewXid();
    var preallocatedByteArray = new byte[12];
    var bytes = id.ToBytes(preallocatedByteArray);

Getting components of a Xid;

    var xid = Xid.NewXid();
    DateTime timestamp = xid.GetTimeStamp();
    byte[] machineId = xid.GetMachineId();
    UInt16 processId = xid.GetProcessId();
    int counter = xid.GetCounter();

Also supported/other features of .Net implementation;

Xid Format, Implementation & Comparison to other UUIDs

The format of a Xid is;

The binary representation of the id is compatible with Mongo 12 byte Object IDs. The string representation uses base32 hex (without padding) for better space efficiency when stored in that form (20 bytes). The hex variant of base32 is used to retain the sortable property of the id.

Xid doesn’t use base64 because case sensitivity and the 2 non alphanum chars may be an issue when transported as a string between various systems. Base36 wasn’t used because it’s not standard, the resulting size is not predictable (not bit aligned), and it would not remain sortable. To validate a base32 xid, expect a 20 character long, all lowercase sequence using characters in the range of a to v and 0 to 9 numbers ([0-9a-v]{20}).

UUIDs are 16 bytes (128 bits) and 36 chars as string representation. Twitter Snowflake ids are 8 bytes (64 bits) but require machine/data-center configuration and/or central generator servers. Xid stands in between at 12 bytes (96 bits) with a more compact URL-safe string representation (20 chars). No configuration or central generator server is required so it can be used directly in application code.

Name Binary Size String Size Features
UUID 16 bytes 36 chars configuration free, not sortable
shortuuid 16 bytes 22 chars configuration free, not sortable
Snowflake 8 bytes up to 20 chars needs machine/DC configuration, needs central server, sortable
MongoID 12 bytes 24 chars configuration free, sortable
xid 12 bytes 20 chars configuration free, sortable

Features:

Benchmarks

32-bit
BenchmarkDotNet=v0.10.9, OS=Windows 10 Redstone 2 (10.0.15063)
Processor=Intel Core i7-6820HQ CPU 2.70GHz (Skylake), ProcessorCount=8
Frequency=2648436 Hz, Resolution=377.5813 ns, Timer=TSC
[Host] : .NET Framework 4.7 (CLR 4.0.30319.42000), 32bit LegacyJIT-v4.7.2101.1
DefaultJob : .NET Framework 4.7 (CLR 4.0.30319.42000), 32bit LegacyJIT-v4.7.2101.1

Method Mean Error StdDev
CreateXidBenchmark 36.94 ns 0.2248 ns 0.2103 ns
CreateGuidBenchmark 201.27 ns 6.9994 ns 6.5473 ns

64-bit
BenchmarkDotNet=v0.10.9, OS=Windows 10 Redstone 2 (10.0.15063)
Processor=Intel Core i7-6820HQ CPU 2.70GHz (Skylake), ProcessorCount=8
Frequency=2648436 Hz, Resolution=377.5813 ns, Timer=TSC
[Host] : .NET Framework 4.7 (CLR 4.0.30319.42000), 64bit RyuJIT-v4.7.2101.1
DefaultJob : .NET Framework 4.7 (CLR 4.0.30319.42000), 64bit RyuJIT-v4.7.2101.1

Method Mean Error StdDev
CreateXidBenchmark 23.56 ns 0.1409 ns 0.1100 ns
CreateGuidBenchmark 82.41 ns 0.2656 ns 0.2354 ns

References:

License

All source code is licensed under the MIT License. Original Xid repo license at; Xid License.