range.go

package dasmon

import (
	"iter"

	"golang.org/x/exp/constraints"
)

// Range represents a closed range [start, end] of integer type T.
type Range[T constraints.Unsigned] struct {
	Start T
	End   T
}

func RangeClosed[T constraints.Unsigned](start, end T) Range[T] {
	return Range[T]{Start: start, End: end}
}

func RangeLength[T constraints.Unsigned](start T, length T) Range[T] {
	return Range[T]{Start: start, End: start + length}
}

func (r Range[T]) Values() iter.Seq[T] {
	return func(yield func(T) bool) {
		for i := r.Start; i <= r.End; i++ {
			if !yield(i) {
				return
			}
		}
	}
}

// satAdd returns min(x+y, maxT) for unsigned T.
func satAdd[T constraints.Unsigned](x, y T) T {
	max := ^T(0)
	if x > max-y {
		return max
	}
	return x + y
}

// satSub returns max(x-y, 0) for unsigned T.
func satSub[T constraints.Unsigned](x, y T) T {
	if y > x {
		return 0
	}
	return x - y
}

// splitOffset converts a signed offset into a (neg, pos) unsigned pair.
// Exactly one of the returned values is non-zero (unless offset == 0).
func splitOffset[T constraints.Unsigned](offset int) (neg, pos T) {
	if offset < 0 {
		return T(-offset), 0
	}
	return 0, T(offset)
}

// Intersect returns the intersection of two ranges.
// If the ranges do not intersect, ok is false and ret is undefined.
func (r Range[T]) Intersect(other Range[T]) (ret Range[T], ok bool) {
	ret.Start = max(r.Start, other.Start)
	ret.End = min(r.End, other.End)
	if ret.End < ret.Start {
		return ret, false
	}
	return ret, true
}

// FromEnd anchors at End.
// offset < 0: [max(0, End - |offset|), End]
// offset = 0: [End, End]
// offset > 0: [End, min(maxT, End + offset)]
func (r Range[T]) FromEnd(offset int) Range[T] {
	var (
		neg, pos   = splitOffset[T](offset)
		start, end = satSub(r.End, neg), satAdd(r.End, pos)
	)
	return Range[T]{Start: start, End: end}
}

// FromStart anchors at Start.
// offset < 0: [max(0, Start - |offset|), Start]
// offset = 0: [Start, Start]
// offset > 0: [Start, min(maxT, Start + offset)]
func (r Range[T]) FromStart(offset int) Range[T] {
	var (
		neg, pos   = splitOffset[T](offset)
		start, end = satSub(r.Start, neg), satAdd(r.Start, pos)
	)
	return Range[T]{Start: start, End: end}
}

// Reframe applies signed offsets to both bounds with saturation.
// If Start' > End', clamp Start' to End' to keep a valid closed range.
func (r Range[T]) Reframe(startOff, endOff int) Range[T] {
	var (
		sNeg, sPos = splitOffset[T](startOff)
		eNeg, ePos = splitOffset[T](endOff)
		start, end = satAdd(satSub(r.Start, sNeg), sPos), satAdd(satSub(r.End, eNeg), ePos)
	)
	if start > end {
		start = end
	}
	return Range[T]{Start: start, End: end}
}

// Contains checks if the value is within the range [start, end].
func (r Range[T]) Contains(value T) bool {
	return r.Start <= value && value <= r.End
}

// Valid returns true if start <= end.
func (r Range[T]) Valid() bool {
	return r.End >= r.Start
}

func (r Range[T]) Tuple() (T, T) {
	return r.Start, r.End
}

func (r Range[T]) Length() T {
	if !r.Valid() {
		return 0
	}
	return r.End - r.Start
}