ulid

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 6, 2016 License: Apache-2.0 Imports: 3 Imported by: 0

README

Universally Unique Lexicographically Sortable Identifier

Project status Build Status Go Report Card Coverage Status GoDoc Apache 2 licensed

A Go port of alizain/ulid with binary format implemented.

Background

A GUID/UUID can be suboptimal for many use-cases because:

  • It isn't the most character efficient way of encoding 128 bits
  • It provides no other information than randomness

A ULID however:

  • Is compatible with UUID/GUID's
  • 1.21e+24 unique ULIDs per millisecond (1,208,925,819,614,629,174,706,176 to be exact)
  • Lexicographically sortable
  • Canonically encoded as a 26 character string, as opposed to the 36 character UUID
  • Uses Crockford's base32 for better efficiency and readability (5 bits per character)
  • Case insensitive
  • No special characters (URL safe)

Install

go get github.com/oklog/ulid

Usage

An ULID is constructed with a time.Time and an io.Reader entropy source. This design allows for greater flexibility in choosing your trade-offs.

Please note that rand.Rand from the math package is not safe for concurrent use. Instantiate one per long living go-routine or use a sync.Pool if you want to avoid the potential contention of a locked rand.Source as its been frequently observed in the package level functions.

func ExampleULID() {
	t := time.Unix(1000000, 0)
	entropy := rand.New(rand.NewSource(t.UnixNano()))
	fmt.Println(ulid.MustNew(ulid.Timestamp(t), entropy))
	// Output: 0000XSNJG0MQJHBF4QX1EFD6Y3
}

Specification

Below is the current specification of ULID as implemented in this repository.

Components

Timestamp

  • 48 bits
  • UNIX-time in milliseconds
  • Won't run out of space till the year 10895 AD

Entropy

  • 80 bits
Encoding

Crockford's Base32 is used as shown. This alphabet excludes the letters I, L, O, and U to avoid confusion and abuse.

0123456789ABCDEFGHJKMNPQRSTVWXYZ
Binary Layout and Byte Order

The components are encoded as 16 octets. Each component is encoded with the Most Significant Byte first (network byte order).

0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                      32_bit_uint_time_high                    |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|     16_bit_uint_time_low      |       16_bit_uint_random      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                       32_bit_uint_random                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                       32_bit_uint_random                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
String Representation
 01AN4Z07BY      79KA1307SR9X4MV3
|----------|    |----------------|
 Timestamp           Entropy
  10 chars           16 chars
   48bits             80bits
   base32             base32

Test

go test ./...

Benchmarks

On a Intel Core i7 Ivy Bridge 2.7 GHz, MacOS 10.12.1 and Go 1.8.0beta1

BenchmarkNew/WithEntropy-8          20000000      62.6 ns/op    16 B/op    1 allocs/op
BenchmarkNew/WithoutEntropy-8       50000000      29.6 ns/op    16 B/op    1 allocs/op
BenchmarkMustNew/WithEntropy-8      20000000      67.4 ns/op    16 B/op    1 allocs/op
BenchmarkMustNew/WithoutEntropy-8   50000000      33.8 ns/op    16 B/op    1 allocs/op
BenchmarkParse-8                    50000000      29.8 ns/op     0 B/op    0 allocs/op
BenchmarkMustParse-8                50000000      34.6 ns/op     0 B/op    0 allocs/op
BenchmarkString-8                   20000000      61.4 ns/op    32 B/op    1 allocs/op
BenchmarkMarshal/Text-8             30000000      52.4 ns/op    32 B/op    1 allocs/op
BenchmarkMarshal/TextTo-8           100000000     22.5 ns/op     0 B/op    0 allocs/op
BenchmarkMarshal/Binary-8           300000000     4.15 ns/op     0 B/op    0 allocs/op
BenchmarkMarshal/BinaryTo-8         2000000000    1.18 ns/op     0 B/op    0 allocs/op
BenchmarkUnmarshal/Text-8           100000000     20.6 ns/op     0 B/op    0 allocs/op
BenchmarkUnmarshal/Binary-8         300000000     4.88 ns/op     0 B/op    0 allocs/op
BenchmarkNow-8                      50000000      37.6 ns/op     0 B/op    0 allocs/op
BenchmarkTimestamp-8                50000000      24.9 ns/op     0 B/op    0 allocs/op
BenchmarkTime-8                     2000000000    0.57 ns/op     0 B/op    0 allocs/op
BenchmarkSetEntropy-8               2000000000    0.86 ns/op     0 B/op    0 allocs/op

Prior Art

Documentation

Index

Examples

Constants

View Source 
const EncodedSize = 26

EncodedSize is the length of a text encoded ULID.

View Source 
const Encoding = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"

Encoding is the base 32 encoding alphabet used in ULID strings.

Variables

View Source 
var (
	// ErrDataSize is returned when parsing or unmarshaling ULIDs with the wrong
	// data size.
	ErrDataSize = errors.New("ulid: bad data size when unmarshaling")

	// ErrBufferSize is returned when marshalling ULIDs to a buffer of insufficient
	// size.
	ErrBufferSize = errors.New("ulid: bad buffer size when marshaling")

	// ErrBigTime is returned when constructing an ULID with a time that is larger
	// than MaxTime.
	ErrBigTime = errors.New("ulid: time too big")
)

Functions

func MaxTime 

func MaxTime() uint64

MaxTime returns the maximum Unix time in milliseconds that can be encoded in an ULID.

func Now 

func Now() uint64

Now is a convenience function that returns the current UTC time in Unix miliseconds. Equivalent to: 

Timestamp(time.Now().UTC())

func Timestamp 

func Timestamp(t time.Time) uint64

Timestamp converts a time.Time to Unix milliseconds.

BUG(tsenart): Because of the way time.Time is internally represented, times from the year 2262 on have undefined results.

Types

type ULID 

type ULID [16]byte

An ULID is a 16 byte Universally Unique Lexicographically Sortable Identifier 

The components are encoded as 16 octets.
Each component is encoded with the MSB first (network byte order).

0                   1                   2                   3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                      32_bit_uint_time_high                    |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|     16_bit_uint_time_low      |       16_bit_uint_random      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                       32_bit_uint_random                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                       32_bit_uint_random                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Example 
package main

import (
	"fmt"
	"math/rand"
	"time"

	"github.com/oklog/ulid"
)

func main() {
	t := time.Unix(1000000, 0)
	entropy := rand.New(rand.NewSource(t.UnixNano()))
	fmt.Println(ulid.MustNew(ulid.Timestamp(t), entropy))
}

Output:

0000XSNJG0MQJHBF4QX1EFD6Y3

func MustNew 

func MustNew(ms uint64, entropy io.Reader) ULID

MustNew is a convenience function equivalent to New that panics on failure instead of returning an error.

func MustParse 

func MustParse(ulid string) ULID

MustParse is a convenience function equivalent to Parse that panics on failure instead of returning an error.

func New 

func New(ms uint64, entropy io.Reader) (id ULID, err error)

New returns an ULID with the given Unix milliseconds timestamp and an optional entropy source. Use the Timestamp function to convert a time.Time to Unix milliseconds.

ErrBigTime is returned when passing a timestamp bigger than MaxTime. Reading from the entropy source may also return an error.

func Parse 

func Parse(ulid string) (id ULID, err error)

Parse parses a string encoded ULID, returning an error in case of failure.

func (ULID) Entropy 

func (id ULID) Entropy() []byte

Entropy returns the entropy from the ULID.

func (ULID) MarshalBinary 

func (id ULID) MarshalBinary() ([]byte, error)

MarshalBinary implements the encoding.BinaryMarshaler interface by returning the ULID as a byte slice.

func (ULID) MarshalBinaryTo 

func (id ULID) MarshalBinaryTo(dst []byte) error

MarshalBinaryTo writes the binary encoding of the ULID to the given buffer. ErrBufferSize is returned when the len(dst) != 16.

func (ULID) MarshalText 

func (id ULID) MarshalText() ([]byte, error)

MarshalText implements the encoding.TextMarshaler interface by returning the string encoded ULID.

func (ULID) MarshalTextTo 

func (id ULID) MarshalTextTo(dst []byte) error

MarshalTextTo writes the ULID as a string to the given buffer. ErrBufferSize is returned when the len(dst) != 26.

func (*ULID) SetEntropy 

func (id *ULID) SetEntropy(e []byte) error

SetEntropy sets the ULID entropy to the passed byte slice. ErrDataSize is returned if len(e) != 10.

func (*ULID) SetTime 

func (id *ULID) SetTime(ms uint64) error

SetTime sets the time component of the ULID to the given Unix time in milliseconds.

func (ULID) String 

func (id ULID) String() string

String returns a lexicographically sortable string encoded ULID (26 characters, non-standard base 32) e.g. 01AN4Z07BY79KA1307SR9X4MV3 Format: tttttttttteeeeeeeeeeeeeeee where t is time and e is entropy

func (ULID) Time 

func (id ULID) Time() uint64

Time returns the Unix time in milliseconds encoded in the ULID.

func (*ULID) UnmarshalBinary 

func (id *ULID) UnmarshalBinary(data []byte) error

UnmarshalBinary implements the encoding.BinaryUnmarshaler interface by copying the passed data and converting it to an ULID. ErrDataSize is returned if the data length is different from ULID length.

func (*ULID) UnmarshalText 

func (id *ULID) UnmarshalText(v []byte) error

UnmarshalText implements the encoding.TextUnmarshaler interface by parsing the data as string encoded ULID.

Notes

Bugs

  • Because of the way time.Time is internally represented, times from the year 2262 on have undefined results.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.