ksuid: github.com/segmentio/ksuid Index | Files

package ksuid

import "github.com/segmentio/ksuid"


Package Files

base62.go ksuid.go rand.go sequence.go set.go uint128.go


var FastRander = newRBG()

FastRander is an io.Reader that uses math/rand and is optimized for generating 16 bytes KSUID payloads. It is intended to be used as a performance improvements for programs that have no need for cryptographically secure KSUIDs and are generating a lot of them.

func Compare Uses

func Compare(a, b KSUID) int

Implements comparison for KSUID type

func IsSorted Uses

func IsSorted(ids []KSUID) bool

IsSorted checks whether a slice of KSUIDs is sorted

func SetRand Uses

func SetRand(r io.Reader)

Sets the global source of random bytes for KSUID generation. This should probably only be set once globally. While this is technically thread-safe as in it won't cause corruption, there's no guarantee on ordering.

func Sort Uses

func Sort(ids []KSUID)

Sorts the given slice of KSUIDs

type CompressedSet Uses

type CompressedSet []byte

CompressedSet is an immutable data type which stores a set of KSUIDs.

func AppendCompressed Uses

func AppendCompressed(set []byte, ids ...KSUID) CompressedSet

AppendCompressed uses the given byte slice as pre-allocated storage space to build a KSUID set.

Note that the set uses a compression technique to store the KSUIDs, so the resuling length is not 20 x len(ids). The rule of thumb here is for the given byte slice to reserve the amount of memory that the application would be OK to waste.

func Compress Uses

func Compress(ids ...KSUID) CompressedSet

Compress creates and returns a compressed set of KSUIDs from the list given as arguments.

func (CompressedSet) GoString Uses

func (set CompressedSet) GoString() string

String satisfies the fmt.GoStringer interface, returns a Go representation of the set.

func (CompressedSet) Iter Uses

func (set CompressedSet) Iter() CompressedSetIter

Iter returns an iterator that produces all KSUIDs in the set.

func (CompressedSet) String Uses

func (set CompressedSet) String() string

String satisfies the fmt.Stringer interface, returns a human-readable string representation of the set.

type CompressedSetIter Uses

type CompressedSetIter struct {
    // KSUID is modified by calls to the Next method to hold the KSUID loaded
    // by the iterator.
    // contains filtered or unexported fields

CompressedSetIter is an iterator type returned by Set.Iter to produce the list of KSUIDs stored in a set.

Here's is how the iterator type is commonly used:

for it := set.Iter(); it.Next(); {
	id := it.KSUID
	// ...

CompressedSetIter values are not safe to use concurrently from multiple goroutines.

func (*CompressedSetIter) Next Uses

func (it *CompressedSetIter) Next() bool

Next moves the iterator forward, returning true if there a KSUID was found, or false if the iterator as reached the end of the set it was created from.

type KSUID Uses

type KSUID [byteLength]byte

KSUIDs are 20 bytes:

00-03 byte: uint32 BE UTC timestamp with custom epoch
04-19 byte: random "payload"
var (

    // Represents a completely empty (invalid) KSUID
    Nil KSUID
    // Represents the highest value a KSUID can have
    Max = KSUID{255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255}

func FromBytes Uses

func FromBytes(b []byte) (KSUID, error)

Constructs a KSUID from a 20-byte binary representation

func FromParts Uses

func FromParts(t time.Time, payload []byte) (KSUID, error)

Constructs a KSUID from constituent parts

func New Uses

func New() KSUID

Generates a new KSUID. In the strange case that random bytes can't be read, it will panic.

func NewRandom Uses

func NewRandom() (ksuid KSUID, err error)

Generates a new KSUID

func NewRandomWithTime Uses

func NewRandomWithTime(t time.Time) (ksuid KSUID, err error)

func Parse Uses

func Parse(s string) (KSUID, error)

Parse decodes a string-encoded representation of a KSUID object

func (KSUID) Append Uses

func (i KSUID) Append(b []byte) []byte

Append appends the string representation of i to b, returning a slice to a potentially larger memory area.

func (KSUID) Bytes Uses

func (i KSUID) Bytes() []byte

Raw byte representation of KSUID

func (KSUID) Get Uses

func (i KSUID) Get() interface{}

Get satisfies the flag.Getter interface, making it possible to use KSUIDs as part of of the command line options of a program.

func (KSUID) IsNil Uses

func (i KSUID) IsNil() bool

IsNil returns true if this is a "nil" KSUID

func (KSUID) MarshalBinary Uses

func (i KSUID) MarshalBinary() ([]byte, error)

func (KSUID) MarshalText Uses

func (i KSUID) MarshalText() ([]byte, error)

func (KSUID) Next Uses

func (id KSUID) Next() KSUID

Next returns the next KSUID after id.

func (KSUID) Payload Uses

func (i KSUID) Payload() []byte

The 16-byte random payload without the timestamp

func (KSUID) Prev Uses

func (id KSUID) Prev() KSUID

Prev returns the previoud KSUID before id.

func (*KSUID) Scan Uses

func (i *KSUID) Scan(src interface{}) error

Scan implements the sql.Scanner interface. It supports converting from string, []byte, or nil into a KSUID value. Attempting to convert from another type will return an error.

func (*KSUID) Set Uses

func (i *KSUID) Set(s string) error

Set satisfies the flag.Value interface, making it possible to use KSUIDs as part of of the command line options of a program.

func (KSUID) String Uses

func (i KSUID) String() string

String-encoded representation that can be passed through Parse()

func (KSUID) Time Uses

func (i KSUID) Time() time.Time

The timestamp portion of the ID as a Time object

func (KSUID) Timestamp Uses

func (i KSUID) Timestamp() uint32

The timestamp portion of the ID as a bare integer which is uncorrected for KSUID's special epoch.

func (*KSUID) UnmarshalBinary Uses

func (i *KSUID) UnmarshalBinary(b []byte) error

func (*KSUID) UnmarshalText Uses

func (i *KSUID) UnmarshalText(b []byte) error

func (KSUID) Value Uses

func (i KSUID) Value() (driver.Value, error)

Value converts the KSUID into a SQL driver value which can be used to directly use the KSUID as parameter to a SQL query.

type Sequence Uses

type Sequence struct {
    // The seed is used as base for the KSUID generator, all generated KSUIDs
    // share the same leading 18 bytes of the seed.
    Seed KSUID
    // contains filtered or unexported fields

Sequence is a KSUID generator which produces a sequence of ordered KSUIDs from a seed.

Up to 65536 KSUIDs can be generated by for a single seed.

A typical usage of a Sequence looks like this:

seq := ksuid.Sequence{
	Seed: ksuid.New(),
id, err := seq.Next()

Sequence values are not safe to use concurrently from multiple goroutines.

func (*Sequence) Bounds Uses

func (seq *Sequence) Bounds() (min KSUID, max KSUID)

Bounds returns the inclusive min and max bounds of the KSUIDs that may be generated by the sequence. If all ids have been generated already then the returned min value is equal to the max.

func (*Sequence) Next Uses

func (seq *Sequence) Next() (KSUID, error)

Next produces the next KSUID in the sequence, or returns an error if the sequence has been exhausted.

Package ksuid imports 11 packages (graph) and is imported by 162 packages. Updated 2020-07-02. Refresh now. Tools for package owners.