Improvements to Optional type

InvalidateTo is no longer needed

README.md

@@ -1,3 +1,7 @@
 # goutil
 
-Extension of the standard library.
+[![Go Reference](https://pkg.go.dev/badge/git.tebibyte.media/sashakoshka/goutil.svg)](https://pkg.go.dev/git.tebibyte.media/sashakoshka/goutil)
+
+Goutil provides extensions to the Go standard library. This repository mimics
+its package/directory structure, prefixing all package names with 'u' to
+differentiate them from their standard library counterparts.

container/doc.go

@@ -0,0 +1,2 @@
+// Package ucontainer extends container and implements generic container types.
+package ucontainer

container/memo.go

@@ -20,6 +20,7 @@ func NewMemo[T any] (update func () T) Memo[T] {
 func (this *Memo[T]) Value () T {
 	if !this.valid {
 		this.cache = this.update()
+		this.valid = true
 	}
 	return this.cache
 }
@@ -27,13 +28,8 @@ func (this *Memo[T]) Value () T {
 // Invalidate marks the Memo's value as invalid, which will cause it to be
 // updated the next time Value is called.
 func (this *Memo[T]) Invalidate () {
+	var zero T
+	this.cache = zero
 	this.valid = false
 }
 
-// InvalidateTo invalidates the Memo and sets its value. The new value will be
-// entirely inaccessible. This is only intended to be used for setting a
-// reference to nil
-func (this *Memo[T]) InvalidateTo (value T) {
-	this.Invalidate()
-	this.cache = value
-}

container/optional.go

@@ -0,0 +1,31 @@
+package ucontainer
+
+// Optional can either hold a value, or nothing.
+type Optional[T any] struct {
+	value T
+	exists bool
+}
+
+// O creates a new optional with the specified value.
+func O[T any] (value T) Optional[T] {
+	return Optional[T] {
+		value: value,
+		exists: true,
+	}
+}
+
+// Void returns an optional with no value.
+func Void[T any] () Optional[T] {
+	return Optional[T] { }
+}
+
+// Exists returns if the value is currently set.
+func (optional Optional[T]) Exists () bool {
+	return optional.exists
+}
+
+// Value returns the value and true if the value exists. If not, it returns the
+// zero value and false.
+func (optional Optional[T]) Value () (T, bool) {
+	return optional.value, optional.exists
+}

container/set.go

@@ -3,6 +3,15 @@ package ucontainer
 // Set is a set of unique items, built on top of map.
 type Set[T comparable] map[T] struct { }
 
+// NewSet creates a new set that contains all specified items.
+func NewSet[T comparable] (items ...T) Set[T] {
+	set := make(Set[T])
+	for _, item := range items {
+		set.Add(item)
+	}
+	return set
+}
+
 // Empty returns true if there are no items in the set.
 func (set Set[T]) Empty () bool {
 	return set == nil || len(set) == 0

go.mod

@@ -1,3 +1,3 @@
 module git.tebibyte.media/sashakoshka/goutil
 
-go 1.22.4
+go 1.22.0

image/color/color.go

@@ -18,3 +18,21 @@ func ToRGBA (c color.Color) color.RGBA {
 		uint8(a >> 8),
 	}
 }
+
+// Premultiply applies alpha-premultiplication that colors must apply as per
+// color.Color.RGBA. This is an intrinsically lossy proccess.
+func Premultiply (ur, ug, ub, ua uint32) (r, g, b, a uint32) {
+	return (ur * ua) / 0xFFFF,
+		(ug * ua) / 0xFFFF,
+		(ub * ua) / 0xFFFF,
+		ua
+}
+
+// Unpremultiply reverses alpha-premultiplication that colors must apply as per
+// color.Color.RGBA. This may or may not return the precise original color.
+func Unpremultiply (r, g, b, a uint32) (ur, ug, ub, ua uint32) {
+	return (r / a) * 0xFFFF,
+		(g / a) * 0xFFFF,
+		(b / a) * 0xFFFF,
+		a
+}

image/color/color_test.go

@@ -0,0 +1,34 @@
+package ucolor
+
+import "testing"
+import "image/color"
+
+func TestTransparent (test *testing.T) {
+	if Transparent(color.NRGBA { A: 255 }) {
+		test.Fatal("false positive")
+	}
+	if !Transparent(color.NRGBA { A: 0 }) {
+		test.Fatal("false negative")
+	}
+}
+
+func TestToRGBA (test *testing.T) {
+	rgba := ToRGBA(color.NRGBA { R: 123, G: 100, B: 23, A: 230 })
+	if rgba != (color.RGBA { R: 111, G: 90, B: 20, A: 230 }) {
+		test.Fatalf("wrong value: %v", rgba)
+	}
+}
+
+func TestPremultiply (test *testing.T) {
+	r, g, b, a := Premultiply(0xFFFF, 0xFFFF, 0xFFFF, 0x8888)
+	if r != 0x8888 || g != 0x8888 || b != 0x8888 || a != 0x8888 {
+		test.Fatalf("wrong value: %08x %08x %08x %08x", r, g, b, a)
+	}
+}
+
+func TestUnpremultiply (test *testing.T) {
+	r, g, b, a := Unpremultiply(0x8888, 0x8888, 0x8888, 0x8888)
+	if r != 0xFFFF || g != 0xFFFF || b != 0xFFFF || a != 0x8888 {
+		test.Fatalf("wrong value: %08x %08x %08x %08x", r, g, b, a)
+	}
+}

image/color/doc.go

@@ -0,0 +1,2 @@
+// Package ucolor extends image/color.
+package ucolor

image/color/hsv.go

@@ -0,0 +1,167 @@
+package ucolor
+
+import "image/color"
+
+// HSV represents a color with hue, saturation, and value components. Each
+// component C is in range 0 <= C <= 1.
+type HSV struct {
+	H float64
+	S float64
+	V float64
+}
+
+// HSVA is an HSV color with an added 8-bit alpha component. The alpha component
+// ranges from 0x0000 (fully transparent) to 0xFFFF (opaque), and has no bearing
+// on the other components.
+type HSVA struct {
+	H float64
+	S float64
+	V float64
+	A uint16
+}
+
+var (
+	HSVModel  color.Model = color.ModelFunc(hsvModel)
+	HSVAModel color.Model = color.ModelFunc(hsvaModel)
+)
+
+func (hsv HSV) RGBA () (r, g, b, a uint32) {
+	// Adapted from:
+	// https://www.cs.rit.edu/~ncs/color/t_convert.html
+	
+	component := func (x float64) uint32 {
+		return uint32(float64(0xFFFF) * x)
+	}
+
+	s := clamp01(hsv.S)
+	v := clamp01(hsv.V)
+	if s == 0 {
+		light := component(v)
+		return light, light, light, 0xFFFF
+	}
+	
+	h := clamp01(hsv.H) * 360
+	sector := int(h / 60)
+	// otherwise when given 1.0 for H, sector would overflow to 6
+	if sector > 5 { sector = 5 }
+	offset := (h / 60) - float64(sector)
+	
+	p  := component(v * (1 - s))
+	q  := component(v * (1 - s * offset))
+	t  := component(v * (1 - s * (1 - offset)))
+	va := component(v)
+	
+	switch sector {
+	case 0:  return va, t,  p,  0xFFFF
+	case 1:  return q,  va, p,  0xFFFF
+	case 2:  return p,  va, t,  0xFFFF
+	case 3:  return p,  q,  va, 0xFFFF
+	case 4:  return t,  p,  va, 0xFFFF
+	default: return va, p,  q,  0xFFFF
+	}
+}
+
+func (hsva HSVA) RGBA () (r, g, b, a uint32) {
+	r, g, b, a = HSV {
+		H: hsva.H,
+		S: hsva.S,
+		V: hsva.V,
+	}.RGBA()
+	return Premultiply(r, g, b, uint32(hsva.A))
+}
+
+// Canon returns the color but with the H, S, and V fields are constrained to
+// the range 0.0-1.0
+func (hsv HSV) Canon () HSV {
+	hsv.H = clamp01(hsv.H)
+	hsv.S = clamp01(hsv.S)
+	hsv.V = clamp01(hsv.V)
+	return hsv
+}
+
+// Canon returns the color but with the H, S, and V fields are constrained to
+// the range 0.0-1.0
+func (hsva HSVA) Canon () HSVA {
+	hsva.H = clamp01(hsva.H)
+	hsva.S = clamp01(hsva.S)
+	hsva.V = clamp01(hsva.V)
+	return hsva
+}
+
+func clamp01 (x float64) float64 {
+	if x > 1.0 { return 1.0 }
+	if x < 0.0 { return 0.0 }
+	return x
+}
+
+func hsvModel (c color.Color) color.Color {
+	switch c := c.(type) {
+	case HSV:  return c
+	case HSVA: return HSV { H: c.H, S: c.S, V: c.V }
+	default:
+		r, g, b, _ := Unpremultiply(c.RGBA())
+		return rgbToHSV(r, g, b)
+	}
+}
+
+func hsvaModel (c color.Color) color.Color {
+	switch c := c.(type) {
+	case HSV:  return HSVA { H: c.H, S: c.S, V: c.V, A: 0xFFFF }
+	case HSVA: return c
+	default:
+		r, g, b, a := c.RGBA()
+		hsv := rgbToHSV(r, g, b)
+
+		return HSVA {
+			H: hsv.H,
+			S: hsv.S,
+			V: hsv.V,
+			A: uint16(a),
+		}
+	}
+}
+
+func rgbToHSV (r, g, b uint32) HSV {
+	// Adapted from:
+	// https://www.cs.rit.edu/~ncs/color/t_convert.html
+	
+	component := func (x uint32) float64 {
+		return clamp01(float64(x) / 0xFFFF)
+	}
+	cr := component(r)
+	cg := component(g)
+	cb := component(b)
+	
+	var maxComponent float64
+	if cr > maxComponent { maxComponent = cr }
+	if cg > maxComponent { maxComponent = cg }
+	if cb > maxComponent { maxComponent = cb }
+	var minComponent = 1.0
+	if cr < minComponent { minComponent = cr }
+	if cg < minComponent { minComponent = cg }
+	if cb < minComponent { minComponent = cb }
+	
+	hsv := HSV {
+		V: maxComponent,
+	}
+	
+	delta := maxComponent - minComponent
+	if delta == 0 {
+		// hsva.S is undefined, so hue doesn't matter
+		return hsv
+	}
+	hsv.S = delta / maxComponent
+	
+	switch {
+	case cr == maxComponent: hsv.H =     (cg - cb) / delta
+	case cg == maxComponent: hsv.H = 2 + (cb - cr) / delta
+	case cb == maxComponent: hsv.H = 4 + (cr - cg) / delta
+	}
+	
+	hsv.H *= 60
+	if hsv.H < 0 { hsv.H += 360 }
+	hsv.H /= 360
+	
+	return hsv
+}
+

image/path/doc.go

@@ -0,0 +1,2 @@
+// Package upath implements operations on slices of image.Points.
+package upath

io/cycler.go

@@ -0,0 +1,28 @@
+package uio
+
+import "io"
+
+// Cycler stores any io.Closer. When the value is replaced, the old value is
+// closed.
+type Cycler struct {
+	value io.Closer
+}
+
+// Value returns the value of the Cycler. If there is no value, nil is returned.
+func (this *Cycler) Value () io.Closer {
+	return this.value
+}
+
+// Set replaces the value of the Cycler, closing the previous one if it exists.
+func (this *Cycler) Set (value io.Closer) error {
+	err := this.value.Close()
+	this.value = value
+	return err
+}
+
+// Close closes the Cycler's value early. It will be set to nil.
+func (this *Cycler) Close () error {
+	return this.Set(nil)
+}
+
+

io/doc.go

@@ -0,0 +1,2 @@
+// Package uio extends io.
+package uio