ulid

package
v0.0.0-...-f8415e6 Latest Latest
Warning

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

 Go to latest Published: Dec 21, 2024 License: MIT Imports: 11 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// Encoding is the base 32 encoding alphabet used in ULID strings.
	Encoding = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
	// A ULID consists of 26 characters, which includes:
	// - A 48-bit timestamp (milliseconds since Unix epoch).
	// - A 80-bit random component.
	EncodedSize = 26
)

Variables

View Source 
var (

	// DefaultEntropy returns a thread-safe per process monotonically increasing
	// entropy source.
	DefaultEntropy = func() io.Reader {
		return defaultEntropy
	}
)

Functions

func Now 

func Now() uint64

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

func Time 

func Time(ms uint64) time.Time

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

func Timestamp 

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.

Types

type LockedMonotonicReader 

type LockedMonotonicReader struct {
	MonotonicReader
	// contains filtered or unexported fields
}

LockedMonotonicReader wraps a MonotonicReader with a sync.Mutex for safe concurrent use.

func (*LockedMonotonicReader) MonotonicRead 

func (r *LockedMonotonicReader) MonotonicRead(ms uint64, p []byte) error

MonotonicRead synchronizes calls to the wrapped MonotonicReader.

type MonotonicEntropy 

type MonotonicEntropy struct {
	io.Reader
	// contains filtered or unexported fields
}

MonotonicEntropy is an opaque type that provides monotonic entropy.

func Monotonic 

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

Monotonic returns a source of entropy that yields strictly increasing entropy bytes, to a limit governeed by the `inc` parameter.

Specifically, calls to MonotonicRead within the same ULID timestamp return entropy incremented by a random number between 1 and `inc` inclusive. If an increment results in entropy that would overflow available space, MonotonicRead returns ErrMonotonicOverflow.

Passing `inc == 0` results in the reasonable default `math.MaxUint32`. Lower values of `inc` provide more monotonic entropy in a single millisecond, at the cost of easier "guessability" of generated ULIDs. If your code depends on ULIDs having secure entropy bytes, then it's recommended to use the secure default value of `inc == 0`, unless you know what you're doing.

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

The returned type isn't safe for concurrent use.

func (*MonotonicEntropy) MonotonicRead 

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

MonotonicRead implements the MonotonicReader interface.

type MonotonicReader 

type MonotonicReader interface {
	io.Reader
	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 

type ULID [16]byte

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

var (
	// Zero is a zero-value ULID.
	Zero ULID

	// MaxTime returns the maximum Unix time in milliseconds that can be encoded in a ULID.
	MaxTime = func() uint64 {
		return maxTime
	}
)

func Make 

func Make() *ULID

Make returns a ULID with the current time in Unix milliseconds and monotonically increasing entropy for the same millisecond. It is safe for concurrent use, leveraging a sync.Pool underneath for minimal contention.

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 MustNewDefault 

func MustNewDefault(t time.Time) *ULID

MustNewDefault is a convenience function equivalent to MustNew with DefaultEntropy as the entropy. It may panic if the given time.Time is too large or too small.

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 MustParseStrict 

func MustParseStrict(ulid string) *ULID

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

func New 

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

New returns a 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 

func Parse(ulid string) (*ULID, 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 

func ParseStrict(ulid string) (*ULID, 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 

func (id *ULID) Bytes() []byte

Bytes returns bytes slice representation of ULID.

func (*ULID) Compare 

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 

func (id *ULID) Entropy() []byte

Entropy returns the entropy from the ULID.

func (*ULID) IsZero 

func (id *ULID) IsZero() bool

IsZero returns true if the ULID is a zero-value ULID, i.e. ulid.Zero.

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

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

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

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. Use the top level Time function to convert the returned value to a time.Time.

func (*ULID) Timestamp 

func (id *ULID) Timestamp() time.Time

Timestamp returns the time encoded in the ULID as a time.Time.

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

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

func (*ULID) Value 

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

Value implements the sql/driver.Valuer interface, returning the ULID as a slice of bytes, by invoking MarshalBinary. If your use case requires a string representation instead, you can create a wrapper type that calls String() instead.

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.