uid

package
v0.0.0-...-9d95335 Latest Latest
Warning

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

 Go to latest Published: Aug 22, 2024 License: MIT Imports: 12 Imported by: 1

Documentation

Index

Constants

This section is empty.

Variables

View Source 
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.

Functions

func Compare 

func Compare(a, b KSUID) int

Compare implements comparison for KSUID type.

func IsSorted 

func IsSorted(ids []KSUID) bool

IsSorted checks whether a slice of KSUIDs is sorted

func SetRand 

func SetRand(r io.Reader)

SetRand 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 

func Sort(ids []KSUID)

Sort sorts the given slice of KSUIDs.

Types

type CompressedSet 

type CompressedSet []byte

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

func AppendCompressed 

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

func Compress(ids ...KSUID) CompressedSet

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

func (CompressedSet) GoString 

func (set CompressedSet) GoString() string

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

func (CompressedSet) Iter 

func (set CompressedSet) Iter() CompressedSetIter

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

func (CompressedSet) String 

func (set CompressedSet) String() string

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

type CompressedSetIter 

type CompressedSetIter struct {
	// KSUID is modified by calls to the Next method to hold the KSUID loaded
	// by the iterator.
	KSUID
	// 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 

func (it *CompressedSetIter) Next() bool

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

type KSUID 

type KSUID [byteLength]byte

KSUID is 20 bytes: 

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

var (

	// Nil represents a completely empty (invalid) KSUID.
	Nil KSUID
	// Max 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 

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

FromBytes constructs a KSUID from a 20-byte binary representation

func FromParts 

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

FromParts constructs a KSUID from constituent parts.

func New 

func New() KSUID

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

func NewRandom 

func NewRandom() (ksuid KSUID, err error)

NewRandom generates a new KSUID

func NewRandomWithTime 

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

func Parse 

func Parse(s string) (KSUID, error)

Parse decodes a string-encoded representation of a KSUID object

func (KSUID) Append 

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 

func (i KSUID) Bytes() []byte

Bytes raw byte representation of KSUID.

func (KSUID) Get 

func (i KSUID) Get() interface{}

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

func (KSUID) IsNil 

func (i KSUID) IsNil() bool

IsNil returns true if this is a "nil" KSUID.

func (KSUID) MarshalBinary 

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

func (KSUID) MarshalText 

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

func (KSUID) Next 

func (i KSUID) Next() KSUID

Next returns the next KSUID after id.

func (KSUID) Payload 

func (i KSUID) Payload() []byte

Payload is the 16-byte random payload without the timestamp.

func (KSUID) Prev 

func (i KSUID) Prev() KSUID

Prev returns the previous KSUID before id.

func (*KSUID) Scan 

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 

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

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

func (KSUID) String 

func (i KSUID) String() string

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

func (KSUID) Time 

func (i KSUID) Time() time.Time

Time is the timestamp portion of the ID as a Time object.

func (KSUID) Timestamp 

func (i KSUID) Timestamp() uint32

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

func (*KSUID) UnmarshalBinary 

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

func (*KSUID) UnmarshalText 

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

func (KSUID) Value 

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 

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 

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 

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

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

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.