ulid

Documentation

Overview

Package ulid implements a Universally Unique Lexicographically Sortable Identifier (ULID).

A ULID is designed to be a drop-in replacement for a UUID. A ULID:

• is compatible with UUID/GUID's;
• 1.21e+24 unique ULIDs per millisecond;
• is lexicographically sortable;
• canonically encodes as a 26 character string (as opposed to the 36 character UUID);
• uses Crockford's base32 for better efficiency and readability - see http://www.crockford.com/wrmg/base32.html;
• is case insensitive;
• has no special characters (URL safe);
• has a monotonic sort order (correctly detects and handles the same millisecond).

The canonical spec for a ULID is at:

https://github.com/ulid/spec

This package is based on oklog's package:

https://github.com/oklog/ulid

The API has been adjusted slightly to make it similar to:

https://github.com/satori/go.uuid

Index

• Constants
• Variables
• func Compare(u ULID, v ULID) int
• func Equal(u ULID, v ULID) bool
• func MaxTime() time.Time
• type Error
  • func (e Error) Error() string
• type NullULID
  • func (u *NullULID) Scan(src interface{}) error
  • func (u NullULID) Value() (driver.Value, error)
• type ULID
  • func FromBytes(input []byte) (ULID, error)
  • func FromBytesOrNil(input []byte) ULID
  • func FromString(ulid string) (ULID, error)
  • func FromStringOrNil(ulid string) ULID
  • func Must(u ULID, err error) ULID
  • func New() (ULID, error)
  • func (u ULID) Bytes() []byte
  • func (u ULID) Entropy() []byte
  • func (u ULID) Hash() uint32
  • func (u ULID) IsNil() bool
  • func (u ULID) MarshalBinary() ([]byte, error)
  • func (u ULID) MarshalText() ([]byte, error)
  • func (u *ULID) Scan(src interface{}) error
  • func (u ULID) String() string
  • func (u ULID) Time() time.Time
  • func (u *ULID) UnmarshalBinary(data []byte) error
  • func (u *ULID) UnmarshalText(v []byte) error
  • func (u ULID) Value() (driver.Value, error)

Constants

const (
	// ErrDataSize is returned when parsing or unmarshaling ULIDs with the wrong
	// data size.
	ErrDataSize = Error(iota)
	// ErrInvalidCharacters is returned when parsing or unmarshaling ULIDs with
	// invalid Base32 encodings.
	ErrInvalidCharacters
	// ErrOverflow is returned when unmarshaling a ULID whose first character is
	// larger than 7, thereby exceeding the valid bit depth of 128.
	ErrOverflow
	// ErrMonotonicOverflow is returned by a Monotonic entropy source when
	// incrementing the previous ULID's entropy bytes would result in overflow.
	ErrMonotonicOverflow
	// ErrScanValue is returned when the value passed to scan cannot be
	// unmarshaled into the ULID.
	ErrScanValue
)

The ULID errors.

const EncodedSize = 26

EncodedSize is the length of a text encoded ULID.

const Encoding = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"

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

Variables

var Nil = ULID{}

Nil is special form of ULID that is specified to have all 128 bits set to zero.

Functions

func Compare

func Compare(u ULID, v ULID) int

Compare returns an integer comparing u and v lexicographically. The result will be 0 if u == v, -1 if u < v, and +1 if u > v.

func Equal

func Equal(u ULID, v ULID) bool

Equal returns true iff u equals v equals.

func MaxTime

func MaxTime() time.Time

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

Types

type Error

type Error int

Error represents an error when manipulating ULID data.

func (Error) Error

func (e Error) Error() string

Error returns the error message for the given ULID error.

type NullULID

type NullULID struct {
	ULID  ULID
	Valid bool
}

NullULID can be used with the standard sql package to represent a ULID value that can be NULL in the database

func (*NullULID) Scan

func (u *NullULID) Scan(src interface{}) error

Scan implements the sql.Scanner interface.

func (NullULID) Value

func (u NullULID) Value() (driver.Value, error)

Value implements the driver.Valuer interface.

type ULID

type ULID [16]byte

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                      |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

func FromBytes

func FromBytes(input []byte) (ULID, error)

FromBytes returns a ULID converted from raw byte slice input. It will return error if the slice isn't 16 bytes long.

func FromBytesOrNil

func FromBytesOrNil(input []byte) ULID

FromBytesOrNil returns a ULID converted from raw byte slice input, or the Nil ULID on error.

func FromString

func FromString(ulid string) (ULID, error)

FromString returns a ULID parsed from string input. Input is expected in a form accepted by UnmarshalText.

func FromStringOrNil

func FromStringOrNil(ulid string) ULID

FromStringOrNil returns a ULID parsed from string input, or the Nil ULID on error.

func Must

func Must(u ULID, err error) ULID

Must is a helper that wraps a call to a function returning (ULID, error) and panics if the error is non-nil. It is intended for use in variable initialisations such as

var packageULID = ulid.Must(ulid.FromString("01DQ7W1MG7282JXKCWM0T3FE3R"))

func New

func New() (ULID, error)

New returns a new ULID.

func (ULID) Bytes

func (u ULID) Bytes() []byte

Bytes returns bytes slice representation of u.

func (ULID) Entropy

func (u ULID) Entropy() []byte

Entropy returns the entropy part of u.

func (ULID) Hash

func (u ULID) Hash() uint32

Hash returns a hash of u.

func (ULID) IsNil

func (u ULID) IsNil() bool

IsNil returns true iff this equals the nil-valued ULID with 128 bits set to zero.

func (ULID) MarshalBinary

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

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

func (ULID) MarshalText

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

MarshalText implements the encoding.TextMarshaler interface by returning u encoded as a string.

func (*ULID) Scan

func (u *ULID) Scan(src interface{}) error

Scan implements the sql.Scanner interface. It supports scanning a string or byte slice.

func (ULID) String

func (u ULID) String() string

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

func (ULID) Time

func (u ULID) Time() time.Time

Time returns the time part of u (in millisecond precision).

func (*ULID) UnmarshalBinary

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

UnmarshalBinary implements the encoding.BinaryUnmarshaler interface by copying the passed data and converting it to a ULID.

func (*ULID) UnmarshalText

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

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

func (ULID) Value

func (u ULID) Value() (driver.Value, error)

Value implements the sql/driver.Valuer interface. This returns the value represented as a byte slice.