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/.

Platforms

.Net 4.0+
.Net Standard 1.3

Install

    PM> Install-Package Yort.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();

    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;

IFormattable
IComparable
IComparable
IEquatable
== > < >= <= and != operators
Correctly implemented Equals and GetHashCode overrides
Xid.NewXid is thread-safe

Xid Format, Implementation & Comparison to other UUIDs

The format of a Xid is;

4-byte value representing the seconds since the Unix epoch,
3-byte machine identifier,
2-byte process id, and
3-byte counter, starting with a random value.

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:

Size: 12 bytes (96 bits), smaller than UUID, larger than snowflake
Base32 hex encoded by default (20 chars when transported as printable string, still sortable)
Non configured, you don't need set a unique machine and/or data center id
K-ordered
Embedded time with 1 second precision
Unicity guaranteed for 16,777,216 (24 bits) unique ids per second and per host/process
Lock-free (i.e.: unlike UUIDv1 and v2)

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.

Yortw / Xid.Net

readme