ulid: github.com/oklog/ulid Index | Examples | Files

package ulid

import "github.com/oklog/ulid"



Package Files



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.


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

    // ErrInvalidCharacters is returned when parsing or unmarshaling ULIDs with
    // invalid Base32 encodings.
    ErrInvalidCharacters = errors.New("ulid: bad data characters 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")

    // ErrOverflow is returned when unmarshaling a ULID whose first character is
    // larger than 7, thereby exceeding the valid bit depth of 128.
    ErrOverflow = errors.New("ulid: overflow when unmarshaling")

    // ErrMonotonicOverflow is returned by a Monotonic entropy source when
    // incrementing the previous ULID's entropy bytes would result in overflow.
    ErrMonotonicOverflow = errors.New("ulid: monotonic entropy overflow")

    // ErrScanValue is returned when the value passed to scan cannot be unmarshaled
    // into the ULID.
    ErrScanValue = errors.New("ulid: source value must be a string or byte slice")

func MaxTime Uses

func MaxTime() uint64

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

func Now Uses

func Now() uint64

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


func Time Uses

func Time(ms uint64) time.Time

Time converts Unix milliseconds in the format returned by the Timestamp function to a time.Time.

func Timestamp Uses

func Timestamp(t time.Time) uint64

Timestamp converts a time.Time to Unix milliseconds.

Because of the way ULID stores time, times from the year 10889 produces undefined results.

type MonotonicEntropy Uses

type MonotonicEntropy struct {
    // contains filtered or unexported fields

MonotonicEntropy is an opaque type that provides monotonic entropy.

func Monotonic Uses

func Monotonic(entropy io.Reader, inc uint64) *MonotonicEntropy

Monotonic returns an entropy source that is guaranteed to yield strictly increasing entropy bytes for the same ULID timestamp. On conflicts, the previous ULID entropy is incremented with a random number between 1 and `inc` (inclusive).

The provided entropy source must actually yield random bytes or else monotonic reads are not guaranteed to terminate, since there isn't enough randomness to compute an increment number.

When `inc == 0`, it'll be set to a secure default of `math.MaxUint32`. The lower the value of `inc`, the easier the next ULID within the same millisecond is to guess. If your code depends on ULIDs having secure entropy bytes, then don't go under this default unless you know what you're doing.

The returned type isn't safe for concurrent use.

func (*MonotonicEntropy) MonotonicRead Uses

func (m *MonotonicEntropy) MonotonicRead(ms uint64, entropy []byte) (err error)

MonotonicRead implements the MonotonicReader interface.

type MonotonicReader Uses

type MonotonicReader interface {
    MonotonicRead(ms uint64, p []byte) error

MonotonicReader is an interface that should yield monotonically increasing entropy into the provided slice for all calls with the same ms parameter. If a MonotonicReader is provided to the New constructor, its MonotonicRead method will be used instead of Read.

type ULID Uses

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                      |


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



func MustNew Uses

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 Uses

func MustParse(ulid string) ULID

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

func MustParseStrict Uses

func MustParseStrict(ulid string) ULID

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

func New Uses

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.

Safety for concurrent use is only dependent on the safety of the entropy source.

func Parse Uses

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

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

ErrDataSize is returned if the len(ulid) is different from an encoded ULID's length. Invalid encodings produce undefined ULIDs. For a version that returns an error instead, see ParseStrict.

func ParseStrict Uses

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

ParseStrict parses an encoded ULID, returning an error in case of failure.

It is like Parse, but additionally validates that the parsed ULID consists only of valid base32 characters. It is slightly slower than Parse.

ErrDataSize is returned if the len(ulid) is different from an encoded ULID's length. Invalid encodings return ErrInvalidCharacters.

func (ULID) Bytes Uses

func (u ULID) Bytes() []byte

Bytes returns bytes slice representation of ULID.

func (ULID) Compare Uses

func (id ULID) Compare(other ULID) int

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

func (ULID) Entropy Uses

func (id ULID) Entropy() []byte

Entropy returns the entropy from the ULID.

func (ULID) MarshalBinary Uses

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

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

func (ULID) MarshalBinaryTo Uses

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 Uses

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

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

func (ULID) MarshalTextTo Uses

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) Scan Uses

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

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

func (*ULID) SetEntropy Uses

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 Uses

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 Uses

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 Uses

func (id ULID) Time() uint64

Time returns the Unix time in milliseconds encoded in the ULID. Use the top level Time function to convert the returned value to a time.Time.

func (*ULID) UnmarshalBinary Uses

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 Uses

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

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

ErrDataSize is returned if the len(v) is different from an encoded ULID's length. Invalid encodings produce undefined ULIDs.

func (ULID) Value Uses

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

Value implements the sql/driver.Valuer interface. This returns the value represented as a byte slice. If instead a string is desirable, a wrapper type can be created that calls String().

// stringValuer wraps a ULID as a string-based driver.Valuer.
type stringValuer ULID

func (id stringValuer) Value() (driver.Value, error) {
	return ULID(id).String(), nil

// Example usage.
db.Exec("...", stringValuer(id))

Package ulid imports 10 packages (graph) and is imported by 172 packages. Updated 2019-10-30. Refresh now. Tools for package owners.