link

README

Self-Describing Identification Implementation

Install

go get -u github.com/go-camp/link

Doc

https://pkg.go.dev/github.com/go-camp/link

Documentation

Index

• type ID
  • func Must(id ID, err error) ID
  • func NewRandom() (root ID, err error)
  • func NewRandomFromReader(reader io.Reader) (root ID, err error)
  • func NextChild(id ID, seq *Seq) ID
  • func ParseRandom(sid string) (ID, error)
• type Seq
  • func NewSeq(opts ...SeqOption) *Seq
  • func (seq *Seq) Next() uint64
• type SeqOption
  • func SeqIncrementBy(incrementBy uint64) SeqOption
  • func SeqStartWith(startWith uint64) SeqOption

Examples

• ParseRandom
• Seq

Types

type ID

type ID interface {
	// IsZero returns true if id is zero value.
	IsZero() bool

	// Parent returns the direct parent of id.
	// If id is zero or root, then parent is zero.
	Parent() ID

	// Index returns the index of id in the parant.
	// The index of root id is 0.
	Index() (index uint64)

	// Child returns the derived child id according to the given index.
	Child(index uint64) (child ID)

	// IsRoot returns true if id is a root id.
	IsRoot() bool

	// Root returns the root of id.
	Root() (root ID)

	// Chain returns the id derivation chain.
	// The order of chain from root to id.
	//   chain := []ID{root, ..., parent, id}
	Chain() (chain []ID)

	// Deep returns the number of parents in the id derivation chain.
	// The deep of root id is 0.
	Deep() (deep int)

	// Equal reports whether id and xid represent the same id.
	Equal(xid ID) bool

	// String returns string expression of id.
	String() string
}

ID is a self-describing identification interface.

func Must

func Must(id ID, err error) ID

Must returns an id if err is nil and panics otherwise.

func NewRandom

func NewRandom() (root ID, err error)

NewRandom creates an new random root id based on crypto/rand.Reader. If err is not nil, root is nil.

func NewRandomFromReader

func NewRandomFromReader(reader io.Reader) (root ID, err error)

NewRandom creates an new random root id based on given reader. If err is not nil, root is nil.

func NextChild

func NextChild(id ID, seq *Seq) ID

NextChild returns the next derived child id.

func ParseRandom

func ParseRandom(sid string) (ID, error)

ParseRandom decodes hex encoded sid into an id.

Example

id := Must(ParseRandom("a9e272b77827c32a785e27342acfd1680a1f8001"))
p := fmt.Println
p("ID:", id)
p("Chain:", id.Chain())
p("IsZero:", id.IsZero())
p("Parent:", id.Parent())
p("Index:", id.Index())
p("Child(10):", id.Child(10))
p("IsRoot:", id.IsRoot())
p("Root:", id.Root())
p("Deep:", id.Deep())
p("Equal(NewRandom()):", id.Equal(Must(NewRandom())))

Output:

ID: a9e272b77827c32a785e27342acfd1680a1f8001
Chain: [a9e272b77827c32a785e27342acfd168 a9e272b77827c32a785e27342acfd1680a a9e272b77827c32a785e27342acfd1680a1f a9e272b77827c32a785e27342acfd1680a1f8001]
IsZero: false
Parent: a9e272b77827c32a785e27342acfd1680a1f
Index: 128
Child(10): a9e272b77827c32a785e27342acfd1680a1f80010a
IsRoot: false
Root: a9e272b77827c32a785e27342acfd168
Deep: 3
Equal(NewRandom()): false

type Seq

type Seq struct {
	// contains filtered or unexported fields
}

Seq is a sequence number generator.

All public methods can be safely called concurrently.

Example

seq := NewSeq()
p := fmt.Println
p(seq.Next())

root := Must(NewRandom())
id := NextChild(root, seq)
p(id.Index())

Output:

0
1

func NewSeq

func NewSeq(opts ...SeqOption) *Seq

NewSeq creates a sequence with a set of options.

func (*Seq) Next

func (seq *Seq) Next() uint64

Next advances the sequence to its next value and returns that value.

type SeqOption

type SeqOption func(seq *Seq)

func SeqIncrementBy

func SeqIncrementBy(incrementBy uint64) SeqOption

SeqIncrementBy specifies which value is added to the current sequence value to create an new value. A positive value will make an ascending sequence, a negative one a descending sequence. The default value is 1.

func SeqStartWith

func SeqStartWith(startWith uint64) SeqOption

SeqStartWith allows the sequence to begin anywhere. The default starting value is 0.