The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Data-ULID-0.1
River stage one • 2 direct dependents • 2 total dependents
/ Data::ULID

NAME

Data::ULID - Universally Unique Lexicographically Sortable Identifier

SYNOPSIS

use Data::ULID qw/ulid binary_ulid ulid_date/;

my $id = ulid();  # e.g. 01ARZ3NDEKTSV4RRFFQ69G5FAV
my $binary_id = binary_ulid($id);
my $datetime_obj = ulid_date($id);  # e.g. 2016-06-13T13:25:20

DESCRIPTION

Background

This is an implementation in Perl of the ULID identifier type introducted by Alizain Feerasta. The original implementation (in Javascript) can be found at https://github.com/alizain/ulid.

ULIDs have several advantages over UUIDs in many contexts. The advantages include:

  • Lexicographically sortable

  • The canonical representation is shorter than UUID (26 vs 36 characters)

  • Case insensitve and safely chunkable.

  • URL-safe

  • Timestamp can always be easily extracted if so desired.

Canonical representation

The canonical representation of a ULID is a 26-byte, base32-encoded string consisting of (1) a 10-byte timestamp with millisecond-resolution; and (2) a 16-byte random part.

Without paramters, the ulid() function returns a new ULID in the canonical representation, with the current time (up to the nearest millisecond) in the timestamp part.

$ulid = ulid();

Given a DateTime object as parameter, the function will set the timestamp part based on that:

$ulid = ulid($datetime_obj);

Given a binary ULID as parameter, it returns the same ULID in canonical format:

$ulid = ulid($binary_ulid);

Binary representation

The binary representation of a ULID is 16 octets long, with each component in network byte order (most significant byte first). The components are (1) a 48-bit (6-byte) timestamp in a 32-bit and a 16-bit chunk; (2) an 80-bit (10-byte) random part in a 16-bit and two 32-bit chunks.

The binary_ulid() function returns a ULID in binary representation. Like ulid(), it can take no parameters or a DateTime, but it can also take a ULID in the canonical representation and convert it to binary:

$binary_ulid = binary_ulid($canonical_ulid);

Datetime extraction

The ulid_date() function takes a ULID (canonical or binary) and returns a DateTime object corresponding to the timestamp it encodes.

$datetime = ulid_date($ulid);

DEPENDENCIES

Math::Random::Secure, Encode::Base32::GMP.

AUTHOR

Baldur Kristinsson, December 2016

VERSION

0.1 - initial version.