From a20926015f050f34b8a4dff17f80af6c6224e22c Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Sun, 5 Feb 2023 10:14:16 -0700 Subject: containers: Ordered: Add doc comments. --- lib/containers/ordered.go | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/lib/containers/ordered.go b/lib/containers/ordered.go index aa2c94d..1ebc17e 100644 --- a/lib/containers/ordered.go +++ b/lib/containers/ordered.go @@ -12,12 +12,34 @@ type _Ordered[T any] interface { Compare(T) int } +// An Ordered[T] is a type that has a +// +// func (a T) Compare(b T) int +// +// method that returns a value <1 if a is "less than" b, >1 if a is +// "greater than" b, or 0 if a is "equal to" b. +// +// You can conceptualize as subtraction: +// +// func (a T) Compare(b T) int { +// return a - b +// } +// +// Be careful to avoid integer overflow if actually implementing it as +// subtraction. type Ordered[T _Ordered[T]] _Ordered[T] +// NativeOrdered takes a type that is natively-ordered (integer types, +// float types, and string types), and wraps them such that they +// implement the Ordered interface. type NativeOrdered[T constraints.Ordered] struct { Val T } +// NativeCompare[T] implements the Ordered[T] Compare operation for +// natively-ordered (integer types, float types, and string types). +// While this operation be conceptualized as subtration, +// NativeCompare[T] is careful to avoid integer overflow. func NativeCompare[T constraints.Ordered](a, b T) int { switch { case a < b: @@ -29,6 +51,7 @@ func NativeCompare[T constraints.Ordered](a, b T) int { } } +// Compare implements Ordered[T]. func (a NativeOrdered[T]) Compare(b NativeOrdered[T]) int { return NativeCompare(a.Val, b.Val) } -- cgit v1.2.3-2-g168b