rlid

Documentation

Index

• Constants
• Variables
• func Now() uint64
• func Time(ms uint64) time.Time
• func Timestamp(t time.Time) uint64
• type RLID
  • func Make(seq uint32) (id RLID)
  • func MustParse(rlid string) RLID
  • func MustParseStrict(rlid string) RLID
  • func Parse(rlid string) (id RLID, err error)
  • func ParseStrict(rlid string) (id RLID, err error)
  • func (id RLID) Bytes() []byte
  • func (id RLID) Compare(other RLID) int
  • func (id *RLID) Decode(src []byte, strict bool) error
  • func (id RLID) Encode(dst []byte) error
  • func (id RLID) MarshalBinary() ([]byte, error)
  • func (id RLID) MarshalText() ([]byte, error)
  • func (id *RLID) Scan(src interface{}) error
  • func (id RLID) Sequence() uint32
  • func (id *RLID) SetSequence(seq uint32) error
  • func (id *RLID) SetTime(ms uint64) error
  • func (id RLID) String() string
  • func (id RLID) Time() uint64
  • func (id *RLID) UnmarshalBinary(data []byte) error
  • func (id *RLID) UnmarshalText(data []byte) error
  • func (id RLID) Value() (driver.Value, error)

Constants

const (
	// EncodedSize is the length of a text encoded RLID.
	EncodedSize = 16

	// Encoding is the base 32 encoding alphabet used in ULID strings.
	Encoding = "0123456789abcdefghjkmnpqrstvwxyz"
)

const MaxTime uint64 = 281474976710655

The maximum time in milliseconds that can be represented in an RLID.

Variables

var (
	// Returned when constructing an RLID with a timestamp that is larger than maxTime
	ErrOverTime = errors.New("timestamp is too far in the future to encode")

	// Returned when marshaling RLIDs to a buffer that is the incorrect size.
	ErrBufferSize = errors.New("bad buffer size: cannot encode the id")

	// Returned when unmarshaling RLIDs from a string that is the incorrect length.
	ErrDataSize = errors.New("bad data size: cannot decode the id from string")

	// Returned when unmarshaling RLIDs in strict mode if the string contains bad chars
	ErrInvalidCharacters = errors.New("invalid characters: cannot decode the id from string")

	// Returned when using the sql.Scanner interface if the type is incorrect.
	ErrScanValue = errors.New("source value must be either string or byte slice")
)

Functions

func Now

func Now() uint64

Now is a convenience function to return the current time in Unix epoch time in milliseconds. Unix epoch time is the number of milliseconds since January 1, 1970 at midnight UTC. Note that Unix epoch time will always be in the UTC timezone.

func Time

func Time(ms uint64) time.Time

Time converts a Unix epoch time in milliseconds back to a time.Time.

func Timestamp

func Timestamp(t time.Time) uint64

Timestamp converts a time.Time to Unix epoch time in milliseconds. NOTE: RLIDs cannot store a full Unix millisecond epoch time so timestamps after 10889-08-02 05:31:50.656 UTC are undefined.

Types

type RLID

type RLID [10]byte

An RLID is a 10 byte totally ordered unique lexicographically sortable identifier. The components are encoded in 10 octets where each component is encoded with the MSB first (network byte order). The first 48 bits encode a timestamp at millisecond granularity and the next 32 bits encode a montonically increasing sequence number that allows for ~4.294e12 unique ids to be generated per second with timestamps that will last until around 10,000 years after 1970.

RLIDs are string encoded using Crockford's base32 (5 bits per character) meaning that each RLID is 16 characters long in string format.

func Make

func Make(seq uint32) (id RLID)

Make returns an RLID with the current timestamp and the given sequence number. Make will panic if the current timestamp is too far in the future for an RLID.

func MustParse

func MustParse(rlid string) RLID

MustParse parses an RLID from an encoded string but panics if there is an error.

func MustParseStrict

func MustParseStrict(rlid string) RLID

MustParseStrict parses anRLID from an encoded string in strict mode and panics on error

func Parse

func Parse(rlid string) (id RLID, err error)

Parse an RLID from an encoded string. ErrDataSize is returned if the length of the string is different from the expected encoded length of RLIDs. Invalid encodings produce undefined RLIDs. For a version that validates the RLID, use ParseStrict.

func ParseStrict

func ParseStrict(rlid string) (id RLID, err error)

Parse an RLID from an encoded string in strict mode. ErrDataSize is returned if the length of the string is different from the expected encoded length of the RLID. ErrInvalidCharacters is returned if the encoding is not valid or would produce an undefined RLID.

func (RLID) Bytes

func (id RLID) Bytes() []byte

Bytes returns a bytes slice representation of the RLID.

func (RLID) Compare

func (id RLID) Compare(other RLID) 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 (*RLID) Decode

func (id *RLID) Decode(src []byte, strict bool) error

Decode the RLID from a string represented as a UTF encoded byte array. If strict is true then the decoder will validate that the string contains only valid base32 characters, but this is slightly slower if the input is known to be valid.

func (RLID) Encode

func (id RLID) Encode(dst []byte) error

Encode the RLID as a string to the given buffer. ErrBufferSize is returned if the dst is not equal to the encoded size.

func (RLID) MarshalBinary

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

MarshalBinary implements the encoding.BinaryMarshaler interface.

func (RLID) MarshalText

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

MarshalText implements the encoding.TextMarshaler interface.

func (*RLID) Scan

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

Scan implements the sql.Scanner interface. Supports scanning either a string or a byte slice.

func (RLID) Sequence

func (id RLID) Sequence() uint32

Sequence returns the montonically increasing sequence number component.

func (*RLID) SetSequence

func (id *RLID) SetSequence(seq uint32) error

SetSequence sets the sequence component of the RLID to the given integer.

func (*RLID) SetTime

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

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

func (RLID) String

func (id RLID) String() string

String returns a lexicographically sortable string encoded RLID. 16 characters, non-standard base32 encoded

func (RLID) Time

func (id RLID) Time() uint64

Time returns the Unix epoch time in milliseconds that is encoded in the ID. Use the top level Time function to convert into a time.Time.

func (*RLID) UnmarshalBinary

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

UnmarshalBinary implements the encoding.BinaryUnmarshaler interface.

func (*RLID) UnmarshalText

func (id *RLID) UnmarshalText(data []byte) error

UnmarshalText implements the encoding.TextUnmarshaler interface.

func (RLID) Value

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

Value implements the sql/driver.Value interface, returning the RLID as a slice of bytes. This is the more compact database representation, but to use string values in the database you will have to create your own wrapper type.