Collections and Utility Packages

package main

import (
	"cmp"
	"fmt"
	"math"
	"slices"
)

type Config struct {
	Addr    string
	Timeout int
}

func main() {
	fmt.Println(cmp.Compare(1, 2), cmp.Compare("b", "a"), cmp.Compare(3.5, 3.5))
	fmt.Println(cmp.Less("apple", "banana"))

	// NaN sorts before every other float; NaN equals NaN for Compare.
	nan := math.NaN()
	fmt.Println(cmp.Compare(nan, 1), cmp.Compare(nan, nan), cmp.Compare(1, nan))
	fmt.Println(cmp.Less(nan, math.Inf(-1)), nan < math.Inf(-1))
	// -0.0 and +0.0 compare equal.
	fmt.Println(cmp.Compare(math.Copysign(0, -1), 0))

	floats := []float64{3, nan, 1, math.Inf(1), -2, math.Inf(-1)}
	slices.Sort(floats)
	fmt.Println(floats)

	// cmp.Or returns the first argument that is not the zero value.
	def := Config{Addr: ":8080", Timeout: 30}
	user := Config{Timeout: 5}
	merged := Config{
		Addr:    cmp.Or(user.Addr, def.Addr),
		Timeout: cmp.Or(user.Timeout, def.Timeout),
	}
	fmt.Printf("%+v\n", merged)
	fmt.Println(cmp.Or(0, 0, 0) == 0, cmp.Or[string]() == "")

	// It works for any comparable type, e.g. pointers and structs.
	fmt.Println(cmp.Or(Config{}, def) == def)
}

-1 1 0
true
-1 0 1
true false
0
[NaN -Inf -2 1 3 +Inf]
{Addr::8080 Timeout:5}
true true
true

package main

import (
	"cmp"
	"fmt"
	"math"
)

func main() {
	a, b := math.MaxInt-1, -5
	fmt.Println(a-b > 0)           // wraps: wrongly reports a < b
	fmt.Println(cmp.Compare(a, b)) // correct: 1
}

false
1

type Book struct {
	Title string
	Year  int
}

books := []Book{{"Emma", 1815}, {"Dune", 1965}}
slices.Sort(books)                       // Book is not an ordered type
fmt.Println(cmp.Compare(books[0], books[1]))
fmt.Println(cmp.Or([]int{}, []int{1}))   // slices are not comparable

./main.go:16:13: Book does not satisfy cmp.Ordered (Book missing in ~int | ~int8 | ~int16 | ~int32 | ~int64 | ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr | ~float32 | ~float64 | ~string)
./main.go:17:25: Book does not satisfy cmp.Ordered (Book missing in ~int | ~int8 | ~int16 | ~int32 | ~int64 | ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr | ~float32 | ~float64 | ~string)
./main.go:18:20: []int does not satisfy comparable

slices.SortFunc(s, func(a, b int) bool { return a < b })

./main.go:11:21: in call to slices.SortFunc, type func(a int, b int) bool of func(a, b int) bool {…} does not match inferred type func(a int, b int) int for func(a E, b E) int

package main

import (
	"fmt"
	"slices"
	"sort"
	"strings"
)

type Book struct {
	Title string
	Year  int
}

// byYear implements sort.Interface, the pre-generics way.
type byYear []Book

func (s byYear) Len() int           { return len(s) }
func (s byYear) Less(i, j int) bool { return s[i].Year < s[j].Year }
func (s byYear) Swap(i, j int)      { s[i], s[j] = s[j], s[i] }

func main() {
	books := []Book{{"Ulysses", 1922}, {"Emma", 1815}, {"Dune", 1965}, {"Dubliners", 1914}}

	// 1. sort.Slice: reflection-based swapper, `less` gets indices.
	sort.Slice(books, func(i, j int) bool { return books[i].Year < books[j].Year })
	fmt.Println(books)

	// 2. sort.Sort with a named type implementing sort.Interface.
	sort.Sort(sort.Reverse(byYear(books)))
	fmt.Println(books)

	// 3. The modern replacement: generic, no reflection, three-way compare.
	slices.SortFunc(books, func(a, b Book) int { return a.Year - b.Year })
	fmt.Println(books)

	// Typed helpers for the basic types.
	ints := []int{5, 2, 8}
	sort.Ints(ints)
	words := strings.Fields("pear apple fig")
	sort.Strings(words)
	fmt.Println(ints, words, sort.IntsAreSorted(ints))

	// sort.Search: smallest index in [0,n) where f is true (f must be monotone).
	years := []int{1815, 1914, 1922, 1965}
	i := sort.Search(len(years), func(i int) bool { return years[i] >= 1920 })
	fmt.Println(i, years[i])
	// Not found: Search returns n, so check the bounds yourself.
	j := sort.Search(len(years), func(i int) bool { return years[i] >= 2000 })
	fmt.Println(j, j == len(years))

	// sort.SearchInts and slices.BinarySearch also report whether it was found.
	k := sort.SearchInts(years, 1914)
	fmt.Println(k, k < len(years) && years[k] == 1914)
	pos, ok := slices.BinarySearch(years, 1914)
	fmt.Println(pos, ok)

	// sort.Find (Go 1.19) is the three-way variant and reports found.
	pos, ok = sort.Find(len(years), func(i int) int { return 1922 - years[i] })
	fmt.Println(pos, ok)

	// Stability: sort.SliceStable keeps equal elements in input order.
	people := []struct {
		Name string
		Age  int
	}{{"Ann", 30}, {"Bob", 25}, {"Cat", 30}, {"Dan", 25}}
	sort.SliceStable(people, func(i, j int) bool { return people[i].Age < people[j].Age })
	fmt.Println(people)

	defer func() { fmt.Println("recovered:", recover()) }()
	sort.Slice("not a slice", func(i, j int) bool { return false })
}

[{Emma 1815} {Dubliners 1914} {Ulysses 1922} {Dune 1965}]
[{Dune 1965} {Ulysses 1922} {Dubliners 1914} {Emma 1815}]
[{Emma 1815} {Dubliners 1914} {Ulysses 1922} {Dune 1965}]
[2 5 8] [apple fig pear] true
2 1922
4 true
1 true
1 true
2 true
[{Bob 25} {Dan 25} {Ann 30} {Cat 30}]
recovered: reflect: call of Swapper on string Value

type Interface interface {
	sort.Interface   // Len, Less, Swap
	Push(x any)      // add x as element Len()
	Pop() any        // remove and return element Len()-1
}

package main

import (
	"container/heap"
	"fmt"
	"time"
)

// Loan is a due-date entry; index is maintained by the heap for Fix/Remove.
type Loan struct {
	Member string
	Book   string
	Due    time.Time
	index  int
}

// dueQueue is a min-heap of loans ordered by due date.
type dueQueue []*Loan

func (q dueQueue) Len() int           { return len(q) }
func (q dueQueue) Less(i, j int) bool { return q[i].Due.Before(q[j].Due) }
func (q dueQueue) Swap(i, j int) {
	q[i], q[j] = q[j], q[i]
	q[i].index = i
	q[j].index = j
}

// Push and Pop are called by package heap; do not call them directly.
func (q *dueQueue) Push(x any) {
	l := x.(*Loan)
	l.index = len(*q)
	*q = append(*q, l)
}

func (q *dueQueue) Pop() any {
	old := *q
	n := len(old)
	l := old[n-1]
	old[n-1] = nil // let the GC reclaim the loan
	l.index = -1
	*q = old[:n-1]
	return l
}

func main() {
	day := func(d int) time.Time { return time.Date(2026, time.November, d, 0, 0, 0, 0, time.UTC) }
	q := &dueQueue{}
	heap.Init(q)

	loans := map[string]*Loan{
		"dune":      {Member: "ann", Book: "Dune", Due: day(20)},
		"emma":      {Member: "bob", Book: "Emma", Due: day(5)},
		"ulysses":   {Member: "cat", Book: "Ulysses", Due: day(12)},
		"dubliners": {Member: "dan", Book: "Dubliners", Due: day(30)},
	}
	for _, k := range []string{"dune", "emma", "ulysses", "dubliners"} {
		heap.Push(q, loans[k])
	}

	fmt.Println("next due:", (*q)[0].Book, (*q)[0].Due.Format("Jan 2"))

	// Renewal: change the key, then restore the heap invariant with Fix.
	loans["emma"].Due = day(25)
	heap.Fix(q, loans["emma"].index)

	// Remove an arbitrary element by its index.
	heap.Remove(q, loans["ulysses"].index)

	for q.Len() > 0 {
		l := heap.Pop(q).(*Loan)
		fmt.Println(l.Due.Format("Jan 2"), l.Book, l.Member)
	}
}

next due: Emma Nov 5
Nov 20 Dune ann
Nov 25 Emma bob
Nov 30 Dubliners dan

type q []int

func (q q) Len() int           { return len(q) }
func (q q) Less(i, j int) bool { return q[i] < q[j] }
func (q q) Swap(i, j int)      { q[i], q[j] = q[j], q[i] }
func (q *q) Push(x any)        { *q = append(*q, x.(int)) }

func main() {
	h := &q{}
	heap.Push(h, 1)
}

./main.go:14:12: cannot use h (variable of type *q) as heap.Interface value in argument to heap.Push: *q does not implement heap.Interface (missing method Pop)

package main

import (
	"container/heap"
	"fmt"
)

// PQ is a small generic wrapper that hides the any-typed heap API.
type PQ[T any] struct{ h inner[T] }

type inner[T any] struct {
	items []T
	less  func(a, b T) bool
}

func (h inner[T]) Len() int           { return len(h.items) }
func (h inner[T]) Less(i, j int) bool { return h.less(h.items[i], h.items[j]) }
func (h inner[T]) Swap(i, j int)      { h.items[i], h.items[j] = h.items[j], h.items[i] }
func (h *inner[T]) Push(x any)        { h.items = append(h.items, x.(T)) }
func (h *inner[T]) Pop() any {
	n := len(h.items)
	x := h.items[n-1]
	var zero T
	h.items[n-1] = zero
	h.items = h.items[:n-1]
	return x
}

func NewPQ[T any](less func(a, b T) bool) *PQ[T] {
	return &PQ[T]{h: inner[T]{less: less}}
}

func (p *PQ[T]) Push(x T) { heap.Push(&p.h, x) }
func (p *PQ[T]) Pop() T   { return heap.Pop(&p.h).(T) }
func (p *PQ[T]) Len() int { return p.h.Len() }

func main() {
	pq := NewPQ(func(a, b string) bool { return len(a) < len(b) })
	for _, s := range []string{"Persuasion", "Emma", "Dubliners", "Ulysses"} {
		pq.Push(s)
	}
	for pq.Len() > 0 {
		fmt.Print(pq.Pop(), " ")
	}
	fmt.Println()
}

Emma Ulysses Dubliners Persuasion

package main

import (
	"container/list"
	"container/ring"
	"fmt"
)

// lru is a least-recently-used cache of book titles by ISBN.
type lru struct {
	cap   int
	order *list.List // front = most recently used
	items map[string]*list.Element
}

type entry struct{ isbn, title string }

func newLRU(n int) *lru {
	return &lru{cap: n, order: list.New(), items: map[string]*list.Element{}}
}

func (c *lru) Get(isbn string) (string, bool) {
	el, ok := c.items[isbn]
	if !ok {
		return "", false
	}
	c.order.MoveToFront(el)
	return el.Value.(entry).title, true
}

func (c *lru) Put(isbn, title string) {
	if el, ok := c.items[isbn]; ok {
		el.Value = entry{isbn, title}
		c.order.MoveToFront(el)
		return
	}
	c.items[isbn] = c.order.PushFront(entry{isbn, title})
	if c.order.Len() > c.cap {
		last := c.order.Back()
		delete(c.items, last.Value.(entry).isbn)
		c.order.Remove(last)
	}
}

func (c *lru) Keys() []string {
	var keys []string
	for el := c.order.Front(); el != nil; el = el.Next() {
		keys = append(keys, el.Value.(entry).isbn)
	}
	return keys
}

func main() {
	c := newLRU(2)
	c.Put("a", "Dune")
	c.Put("b", "Emma")
	c.Get("a")            // a becomes most recent
	c.Put("c", "Ulysses") // evicts b
	_, okB := c.Get("b")
	fmt.Println(c.Keys(), okB)

	// container/ring: a fixed-size circular buffer of recent searches.
	r := ring.New(3)
	for _, q := range []string{"dune", "emma", "ulysses", "dubliners"} {
		r.Value = q
		r = r.Next()
	}
	r.Do(func(v any) { fmt.Print(v, " ") }) // oldest to newest
	fmt.Println(r.Len())

	// Rotate moves the starting point; Link and Unlink splice rings.
	r = r.Move(1)
	r.Do(func(v any) { fmt.Print(v, " ") })
	fmt.Println()
}

[c a] false
emma ulysses dubliners 3
ulysses dubliners emma

package main

import (
	"fmt"
	"math"
)

func main() {
	// Constants are exact (untyped) until they are used.
	fmt.Println(math.MaxInt8, math.MinInt64, uint64(math.MaxUint64))
	fmt.Println(math.MaxInt, math.Pi)
	fmt.Println(math.MaxFloat64, math.SmallestNonzeroFloat64)

	// Rounding family.
	for _, x := range []float64{2.5, -2.5, 2.4, 3.5} {
		fmt.Println(x, math.Floor(x), math.Ceil(x), math.Trunc(x), math.Round(x), math.RoundToEven(x))
	}

	// Special values.
	inf, nan := math.Inf(1), math.NaN()
	fmt.Println(inf, -inf, nan, 1/inf, math.IsInf(inf, 0), math.IsNaN(nan))
	fmt.Println(nan == nan, nan != nan)
	var zero float64
	fmt.Println(1/zero, -1/zero, zero/zero) // no panic for floats
	fmt.Println(math.Sqrt(-1), math.Log(0), math.Log(-1))

	// Mod keeps the sign of the dividend; Remainder is IEEE 754 round-to-nearest.
	fmt.Println(math.Mod(-7, 3), math.Remainder(7, 3), -7%3)
	fmt.Println(math.Hypot(3, 4), math.Cbrt(27), math.Pow(2, 10), math.Pow(-8, 1.0/3))
	fmt.Println(math.Abs(-0.5), math.Max(1, nan), math.Min(math.Copysign(0, -1), 0), math.Copysign(3, -1))

	// Floating-point equality: compare with a tolerance.
	x, y := 0.1, 0.2 // variables: the constant expression 0.1+0.2 would be exact
	a, b := x+y, 0.3
	fmt.Println(a == b, math.Abs(a-b) < 1e-9, a)

	// Integer overflow wraps silently; detect it before it happens.
	var i int8 = math.MaxInt8
	i++
	fmt.Println(i)
	maxv := int64(math.MaxInt64)
	fmt.Println(maxv+1 < 0, addOverflows(maxv, 1))

	// Frexp/Modf/Float64bits expose the representation.
	frac, exp := math.Frexp(48)
	ip, fp := math.Modf(3.75)
	fmt.Println(frac, exp, ip, fp)
	fmt.Printf("%#016x %v\n", math.Float64bits(1.0), math.Float64frombits(0x4000000000000000))
	fmt.Println(math.Nextafter(1, 2) - 1)
}

// addOverflows reports whether a+b would overflow int64.
func addOverflows(a, b int64) bool {
	return (b > 0 && a > math.MaxInt64-b) || (b < 0 && a < math.MinInt64-b)
}

127 -9223372036854775808 18446744073709551615
9223372036854775807 3.141592653589793
1.7976931348623157e+308 5e-324
2.5 2 3 2 3 2
-2.5 -3 -2 -2 -3 -2
2.4 2 3 2 2 2
3.5 3 4 3 4 4
+Inf -Inf NaN 0 true true
false true
+Inf -Inf NaN
NaN -Inf NaN
-1 1 -1
5 3 1024 NaN
0.5 NaN -0 -3
false true 0.30000000000000004
-128
true true
0.75 6 3 0.75
0x3ff0000000000000 2
2.220446049250313e-16

package main

import (
	"fmt"
	"math/big"
)

func main() {
	// Int: arbitrary precision, methods write into the receiver.
	f := big.NewInt(1)
	for i := int64(2); i <= 30; i++ {
		f.Mul(f, big.NewInt(i)) // f = f * i
	}
	fmt.Println("30! =", f, f.BitLen(), "bits")

	n, ok := new(big.Int).SetString("123456789012345678901234567890", 10)
	fmt.Println(n, ok)
	_, ok = new(big.Int).SetString("12x", 10)
	fmt.Println(ok)

	a, b := big.NewInt(-7), big.NewInt(2)
	q, r := new(big.Int).QuoRem(a, b, new(big.Int)) // truncated, like Go's / and %
	d, m := new(big.Int).DivMod(a, b, new(big.Int)) // Euclidean: remainder >= 0
	fmt.Println(q, r, d, m)

	// Go 1.27: Divide with an explicit rounding mode.
	for _, mode := range []big.RoundingMode{big.Trunc, big.Floor, big.Round, big.Ceil} {
		q, r := new(big.Int).Divide(a, b, new(big.Int), mode)
		fmt.Println(mode, q, r)
	}

	fmt.Println(new(big.Int).Exp(big.NewInt(2), big.NewInt(100), nil))
	fmt.Println(new(big.Int).Exp(big.NewInt(3), big.NewInt(1000), big.NewInt(1_000_007))) // modular
	fmt.Println(new(big.Int).GCD(nil, nil, big.NewInt(84), big.NewInt(36)))
	fmt.Println(new(big.Int).ModInverse(big.NewInt(3), big.NewInt(11)))
	fmt.Println(big.NewInt(1_000_003).ProbablyPrime(20), a.Sign(), a.Cmp(b), a.CmpAbs(b))
	fmt.Printf("%x %s %v\n", f, f.Text(36), f.IsInt64())

	// Rat: exact fractions.
	x := big.NewRat(1, 3)
	y := big.NewRat(1, 6)
	s := new(big.Rat).Add(x, y)
	fmt.Println(s, s.FloatString(5), s.Num(), s.Denom())

	// Float: arbitrary precision (in bits), explicit rounding mode.
	p := new(big.Float).SetPrec(200).SetInt64(2)
	root := new(big.Float).SetPrec(200).Sqrt(p)
	fmt.Println(root.Text('f', 50))
	fmt.Println(new(big.Float).SetPrec(53).Quo(big.NewFloat(1), big.NewFloat(3)))

	// The zero value is a valid 0, and a result may alias an operand.
	var z big.Int
	fmt.Println(z.String())
	z.Add(&z, big.NewInt(5))
	z.Mul(&z, &z)
	fmt.Println(&z)
}

30! = 265252859812191058636308480000000 108 bits
123456789012345678901234567890 true
false
-3 -1 -4 1
ToZero -3 -1
ToNegativeInf -4 1
ToNearestEven -4 1
ToPositiveInf -3 -1
1267650600228229401496703205376
297623
12
4
true -1 -1 1
d13f6370f96865df5dd54000000 jucotkuo7qe0hs0000000 false
1/2 0.50000 1 2
1.41421356237309504880168872420969807856967187537695
0.3333333333333333
0
25

package main

import (
	"fmt"
	"math"
	"math/bits"
)

// mulChecked multiplies two uint64 values and reports overflow using bits.Mul64.
func mulChecked(a, b uint64) (uint64, bool) {
	hi, lo := bits.Mul64(a, b)
	return lo, hi != 0
}

// addChecked adds with carry detection.
func addChecked(a, b uint64) (uint64, bool) {
	sum, carry := bits.Add64(a, b, 0)
	return sum, carry != 0
}

// Set is a bitset for loan states 0..63.
type Set uint64

func (s Set) Has(i uint) bool { return s&(1<<i) != 0 }
func (s *Set) Add(i uint)     { *s |= 1 << i }
func (s Set) Len() int        { return bits.OnesCount64(uint64(s)) }

func main() {
	x := uint32(0b0010_1100)
	fmt.Println(bits.OnesCount32(x), bits.Len32(x), bits.LeadingZeros32(x), bits.TrailingZeros32(x))
	fmt.Printf("%08b %08b %08b\n", bits.Reverse8(0b0000_0110), bits.RotateLeft8(0b1000_0001, 1), bits.RotateLeft8(0b1000_0001, -1))
	fmt.Printf("%#x\n", bits.ReverseBytes32(0x01020304))

	fmt.Println(mulChecked(1<<32, 1<<31))
	fmt.Println(mulChecked(1<<32, 1<<32))
	fmt.Println(addChecked(math.MaxUint64, 1))

	// 128-bit division: (hi, lo) / y; panics if y <= hi.
	q, r := bits.Div64(1, 0, 3) // 2^64 / 3
	fmt.Println(q, r)

	// Next power of two and power-of-two test.
	n := uint(37)
	next := uint(1) << bits.Len(n-1)
	fmt.Println(next, bits.OnesCount(next) == 1, bits.UintSize)

	var s Set
	s.Add(3)
	s.Add(40)
	fmt.Println(s.Has(3), s.Has(4), s.Len(), bits.TrailingZeros64(uint64(s)))

	defer func() { fmt.Println("recovered:", recover()) }()
	bits.Div64(5, 0, 3) // y <= hi: quotient overflows
}

3 6 26 2
01100000 00000011 11000000
0x4030201
9223372036854775808 false
0 true
0 true
6148914691236517205 1
64 true 64
true false 2 3
recovered: runtime error: integer overflow

package main

import (
	"fmt"
	"math/rand/v2"
	"slices"
	"time"
)

func main() {
	// A reproducible generator: PCG with an explicit two-word seed.
	r := rand.New(rand.NewPCG(1, 2))
	fmt.Println(r.IntN(100), r.IntN(100), r.IntN(100))
	fmt.Println(r.Float64())
	fmt.Println(r.Perm(5))

	// Same seed, same sequence.
	r2 := rand.New(rand.NewPCG(1, 2))
	fmt.Println(r2.IntN(100), r2.IntN(100), r2.IntN(100))

	// ChaCha8 takes a 32-byte seed.
	seed := [32]byte([]byte("shelf-test-seed-0123456789abcdef"))
	c := rand.New(rand.NewChaCha8(seed))
	fmt.Println(c.Uint64(), c.IntN(10))

	// Shuffle in place.
	titles := []string{"Dune", "Emma", "Ulysses", "Dubliners", "Persuasion"}
	rand.New(rand.NewPCG(7, 7)).Shuffle(len(titles), func(i, j int) {
		titles[i], titles[j] = titles[j], titles[i]
	})
	fmt.Println(titles)

	// Go 1.27: N is also a method on *Rand, generic over any integer type,
	// so a Duration needs no conversion.
	d := r.N(10 * time.Second)
	fmt.Println(d >= 0 && d < 10*time.Second)

	rr := rand.New(rand.NewPCG(1, 2))
	fmt.Println(rr.N(int64(1000)), rr.N(uint8(200)), rr.N(time.Hour))

	// The top-level functions use a randomly seeded generator: values differ per run.
	a, b := rand.IntN(1<<30), rand.IntN(1<<30)
	fmt.Println(a >= 0, b >= 0, rand.N(time.Minute) < time.Minute)

	// Weighted/other distributions: NormFloat64, ExpFloat64, Zipf.
	z := rand.NewZipf(rand.New(rand.NewPCG(3, 4)), 1.5, 2, 100)
	counts := make([]int, 4)
	for range 1000 {
		counts[min(z.Uint64(), 3)]++
	}
	fmt.Println(counts, slices.Max(counts) > 0)

	defer func() { fmt.Println("recovered:", recover()) }()
	rand.IntN(0)
}

76 61 78
0.4297927436037299
[2 3 4 0 1]
76 61 78
15734305148095224245 3
[Dune Emma Dubliners Ulysses Persuasion]
true
769 123 47m3.940805972s
true true true
[229 121 101 549] true
recovered: invalid argument to IntN

package main

import (
	crand "crypto/rand"
	"encoding/hex"
	"fmt"
	"math/big"
	"math/rand/v2"
	"regexp"
)

func main() {
	// A session or API token: use crypto/rand, never math/rand.
	token := crand.Text()
	fmt.Println(len(token), regexp.MustCompile(`^[A-Z2-7]+$`).MatchString(token))

	// Raw random bytes; Read never returns an error (it crashes the program instead).
	key := make([]byte, 16)
	crand.Read(key)
	fmt.Println(len(hex.EncodeToString(key)))

	// A uniform integer in [0, max) of any size.
	n, err := crand.Int(crand.Reader, big.NewInt(1000))
	fmt.Println(n.Cmp(big.NewInt(1000)) < 0, err)

	// Seed a fast, non-cryptographic generator from the OS source when you want
	// per-run variation but your own generator instance (e.g. one per worker).
	var seed [32]byte
	crand.Read(seed[:])
	local := rand.New(rand.NewChaCha8(seed))
	fmt.Println(local.IntN(6)+1 >= 1)

	// The ChaCha8 generator is also what the top-level math/rand/v2 functions use,
	// seeded by the runtime. It is fast, but its output is predictable from its state.
}

26 true
32
true <nil>
true

module example.com/shelf

go 1.27

package main

import (
	"encoding/json"
	"fmt"
	"slices"
	"uuid"
)

// Member is a library member identified by a UUID.
type Member struct {
	ID   uuid.UUID `json:"id"`
	Name string    `json:"name"`
}

func main() {
	id := uuid.New()                                  // currently the same algorithm as NewV4
	fmt.Println(len(id.String()), id[6]>>4, id[8]>>6) // version nibble and variant bits

	v7a, v7b, v7c := uuid.NewV7(), uuid.NewV7(), uuid.NewV7()
	fmt.Println(v7a[6]>>4, v7a.Compare(v7b), v7b.Compare(v7c))
	ids := []uuid.UUID{v7c, v7a, v7b}
	slices.SortFunc(ids, uuid.UUID.Compare)
	fmt.Println(slices.Equal(ids, []uuid.UUID{v7a, v7b, v7c}))

	// Parse accepts four forms, any letter case.
	for _, s := range []string{
		"f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
		"{F81D4FAE-7DEC-11D0-A765-00A0C91E6BF6}",
		"urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
		"f81d4fae7dec11d0a76500a0c91e6bf6",
	} {
		u, err := uuid.Parse(s)
		fmt.Println(u, err)
	}
	_, err := uuid.Parse("not-a-uuid")
	fmt.Println(err)

	fmt.Println(uuid.Nil(), uuid.Max(), uuid.Nil() == uuid.UUID{})

	// UUID implements encoding.TextMarshaler/TextUnmarshaler, so JSON uses strings.
	m := Member{ID: uuid.MustParse("f81d4fae-7dec-11d0-a765-00a0c91e6bf6"), Name: "Ann"}
	data, _ := json.Marshal(m)
	fmt.Println(string(data))
	var back Member
	fmt.Println(json.Unmarshal(data, &back), back == m)

	// Being an array, a UUID is comparable and can be a map key.
	byID := map[uuid.UUID]Member{m.ID: m}
	fmt.Println(byID[m.ID].Name)

	defer func() { fmt.Println("recovered:", recover()) }()
	uuid.MustParse("nope")
}

36 4 2
7 -1 -1
true
f81d4fae-7dec-11d0-a765-00a0c91e6bf6 <nil>
f81d4fae-7dec-11d0-a765-00a0c91e6bf6 <nil>
f81d4fae-7dec-11d0-a765-00a0c91e6bf6 <nil>
f81d4fae-7dec-11d0-a765-00a0c91e6bf6 <nil>
invalid uuid
00000000-0000-0000-0000-000000000000 ffffffff-ffff-ffff-ffff-ffffffffffff true
{"id":"f81d4fae-7dec-11d0-a765-00a0c91e6bf6","name":"Ann"}
<nil> true
Ann
recovered: invalid uuid

package main

import (
	"fmt"
	"hash/maphash"
	"strings"
)

// CaseInsensitive is a maphash.Hasher[string] that ignores letter case.
type CaseInsensitive struct{}

func (CaseInsensitive) Hash(h *maphash.Hash, s string) { h.WriteString(strings.ToLower(s)) }
func (CaseInsensitive) Equal(x, y string) bool         { return strings.ToLower(x) == strings.ToLower(y) }

// HashSet is a minimal open-hashing set built on any maphash.Hasher.
type HashSet[T any] struct {
	hasher  maphash.Hasher[T]
	seed    maphash.Seed
	buckets map[uint64][]T
}

func NewHashSet[T any](h maphash.Hasher[T]) *HashSet[T] {
	return &HashSet[T]{hasher: h, seed: maphash.MakeSeed(), buckets: map[uint64][]T{}}
}

func (s *HashSet[T]) sum(v T) uint64 {
	var h maphash.Hash
	h.SetSeed(s.seed)
	s.hasher.Hash(&h, v)
	return h.Sum64()
}

func (s *HashSet[T]) Add(v T) bool {
	k := s.sum(v)
	for _, e := range s.buckets[k] {
		if s.hasher.Equal(e, v) {
			return false
		}
	}
	s.buckets[k] = append(s.buckets[k], v)
	return true
}

func (s *HashSet[T]) Has(v T) bool {
	for _, e := range s.buckets[s.sum(v)] {
		if s.hasher.Equal(e, v) {
			return true
		}
	}
	return false
}

type ISBNKey struct {
	Prefix string
	Number int
}

func main() {
	seed := maphash.MakeSeed()
	h1 := maphash.String(seed, "Dune")
	h2 := maphash.Bytes(seed, []byte("Dune"))
	fmt.Println(h1 == h2, h1 == maphash.String(seed, "dune"))

	// Comparable hashes any comparable value consistently with ==.
	k := ISBNKey{"978", 441013593}
	fmt.Println(maphash.Comparable(seed, k) == maphash.Comparable(seed, ISBNKey{"978", 441013593}))

	// A different seed is a different hash function (hash-flooding resistance),
	// and a seed cannot be saved: the numbers differ from run to run.
	fmt.Println(maphash.String(seed, "Dune") == maphash.String(maphash.MakeSeed(), "Dune"))

	// Incremental hashing: chunks do not matter.
	var a, b maphash.Hash
	a.SetSeed(seed)
	b.SetSeed(seed)
	a.WriteString("Dune")
	b.WriteString("Du")
	b.WriteString("ne")
	fmt.Println(a.Sum64() == b.Sum64())

	// Hasher (Go 1.27) lets containers plug in their own equivalence.
	set := NewHashSet[string](CaseInsensitive{})
	fmt.Println(set.Add("Dune"), set.Add("DUNE"), set.Add("Emma"), set.Has("emma"), set.Has("Ulysses"))

	keys := NewHashSet[ISBNKey](maphash.ComparableHasher[ISBNKey]{})
	fmt.Println(keys.Add(k), keys.Add(k), keys.Has(ISBNKey{"978", 1}))
}

true false
true
false
true
true false true true false
true false false

package main

import (
	"fmt"
	"strings"
	"unique"
	"unsafe"
)

// Genre is interned: copies are one pointer-sized handle, and comparing two
// genres is a pointer comparison instead of a string comparison.
type Genre = unique.Handle[string]

type Book struct {
	Title string
	Genre Genre
}

func main() {
	genres := []string{"Science Fiction", "science fiction", "Novel"}
	var books []Book
	for i, g := range genres {
		books = append(books, Book{Title: fmt.Sprint("book", i), Genre: unique.Make(g)})
	}
	books = append(books, Book{Title: "book3", Genre: unique.Make(strings.Clone("Science Fiction"))})

	fmt.Println(books[0].Genre == books[1].Genre) // different strings, different handles
	fmt.Println(books[0].Genre == books[3].Genre) // same value, same handle
	fmt.Println(books[0].Genre.Value(), unsafe.Sizeof(books[0].Genre))
}

false
true
Science Fiction 8