summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLuke Shumaker <lukeshu@lukeshu.com>2023-02-05 10:14:16 -0700
committerLuke Shumaker <lukeshu@lukeshu.com>2023-02-05 21:01:58 -0700
commita20926015f050f34b8a4dff17f80af6c6224e22c (patch)
tree984621e1935ce28077bb32b0f4b292cd031b95b6
parent0ff1d420f21101a92d8da888d491860cf0cf16cc (diff)
containers: Ordered: Add doc comments.
-rw-r--r--lib/containers/ordered.go23
1 files changed, 23 insertions, 0 deletions
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)
}