doc complexity for all algorithms (#13)

compare.go

@@ -3,7 +3,8 @@ package contalgo
 import "golang.org/x/exp/constraints"
 
 // Equal returns whether two slices are equal.
-// Return true if they are the same length and all elements equal.
+// Return true if they are the same length and all elements are equal.
+// Complexity: O(min(len(a), len(b))).
 func Equal[T comparable](a, b []T) bool {
 	if len(a) != len(b) {
 		return false
@@ -16,7 +17,11 @@ func Equal[T comparable](a, b []T) bool {
 	return true
 }
 
-// Compare compares the elements of a and b.
+// Compare compares each elements in a and b.
+// return 0 if they are equals,
+// return 1 if a > b,
+// return -1 if a < b.
+// Complexity: O(min(len(a), len(b))).
 func Compare[E constraints.Ordered](a, b []E) int {
 	bl := len(b)
 	for i, v1 := range a {

compute.go

@@ -1,5 +1,8 @@
 package contalgo
 
+// Sum summarize all elements in a.
+// returns the result as type R, this is useful when T is too small to hold the result.
+// Complexity: O(len(a)).
 func SumAs[R, T Numeric](a []T) R {
 	var total R
 	for v := range a {
@@ -8,6 +11,9 @@ func SumAs[R, T Numeric](a []T) R {
 	return total
 }
 
+// Sum summarize all elements in a.
+// returns the result as type R, you should use SumAs if T can't hold the result.
+// Complexity: O(len(a)).
 func Sum[T Numeric](a []T) T {
 	return SumAs[T](a)
 }
@@ -20,7 +26,8 @@ func Average[T Numeric](a []T) T {
 	return AverageAs[T](a)
 }
 
-// Count returns the number of elements in the slice equals to x
+// Count returns the number of elements in the slice equals to x.
+// Complexity: O(len(a)).
 func Count[T comparable](a []T, x T) int {
 	c := 0
 	for _, v := range a {
@@ -31,7 +38,8 @@ func Count[T comparable](a []T, x T) int {
 	return c
 }
 
-// Count returns the number of elements in the slice which pred returns true
+// Count returns the number of elements in the slice which pred returns true.
+// Complexity: O(len(a)).
 func CountIf[T comparable](a []T, pred func(T) bool) int {
 	c := 0
 	for _, v := range a {

generate.go

@@ -1,6 +1,7 @@
 package contalgo
 
-// Range make a []T filled with values in the `[first, last)` sequence
+// Range make a []T filled with values in the `[first, last)` sequence.
+// Complexity: O(last-first).
 func Range[T Numeric](first, last T) []T {
 	a := make([]T, 0, int(last-first))
 	for v := first; v < last; v++ {
@@ -9,7 +10,8 @@ func Range[T Numeric](first, last T) []T {
 	return a
 }
 
-// Generate fill each element of `a`` with `gen()``
+// Generate fill each element of `a`` with `gen()`.
+// Complexity: O(len(a)).
 func Generate[T Numeric](a []T, gen func() T) {
 	for i := range a {
 		a[i] = gen()

lookup.go

@@ -2,23 +2,26 @@ package contalgo
 
 import "golang.org/x/exp/constraints"
 
-// Max return the larger value between `a` and `b`
+// Max return the larger value between `a` and `b`.
+// Complexity: O(1).
 func Max[T constraints.Ordered](a, b T) T {
 	if a > b {
 		return a
 	}
 	return b
 }
 
-// Max return the smaller value between `a` and `b`
+// Max return the smaller value between `a` and `b`.
+// Complexity: O(1).
 func Min[T constraints.Ordered](a, b T) T {
 	if a < b {
 		return a
 	}
 	return b
 }
 
-// MaxN return the maximum value in the sequence `a`
+// MaxN return the maximum value in the sequence `a`.
+// Complexity: O(len(a)).
 func MaxN[T constraints.Ordered](a ...T) T {
 	if len(a) == 0 {
 		panic("can't call MaxN() with empty arguments list")
@@ -32,7 +35,8 @@ func MaxN[T constraints.Ordered](a ...T) T {
 	return v
 }
 
-// MaxN return the minimum value in the sequence `a`
+// MaxN return the minimum value in the sequence `a`.
+// Complexity: O(len(a)).
 func MinN[T constraints.Ordered](a ...T) T {
 	if len(a) == 0 {
 		panic("can't call MaxN() with empty arguments list")
@@ -46,13 +50,17 @@ func MinN[T constraints.Ordered](a ...T) T {
 	return v
 }
 
+// MinMax returns both min and max between a and b.
+// Complexity: O(1).
 func MinMax[T constraints.Ordered](a, b T) (min, max T) {
 	if a < b {
 		return a, b
 	}
 	return b, a
 }
 
+// MinMax returns both min and max in slice a.
+// Complexity: O(len(a))
 func MinMaxN[T constraints.Ordered](a ...T) (min, max T) {
 	if len(a) == 0 {
 		panic("can't call MaxN() with empty arguments list")
@@ -70,9 +78,10 @@ func MinMaxN[T constraints.Ordered](a ...T) (min, max T) {
 	return
 }
 
-// Find find the value x in the given slice a linearly
-// return (index, true) if found
-// return (_, false) if not found
+// Find find the value x in the given slice a linearly.
+// return (index, true) if found,
+// return (_, false) if not found.
+// Complexity: O(len(a)).
 func Find[T comparable](a []T, x T) (index int, ok bool) {
 	for i, v := range a {
 		if v == x {
@@ -82,9 +91,10 @@ func Find[T comparable](a []T, x T) (index int, ok bool) {
 	return -1, false
 }
 
-// Index find the value x in the given slice a linearly
-// return index if found
-// return -1 if not found
+// Index find the value x in the given slice a linearly.
+// return index if found,
+// return -1 if not found.
+// Complexity: O(len(a)).
 func Index[T comparable](a []T, x T) int {
 	for i, v := range a {
 		if v == x {
@@ -94,7 +104,8 @@ func Index[T comparable](a []T, x T) int {
 	return -1
 }
 
-// AllOf return true if pred(e) returns true for all emements e in a
+// AllOf return true if pred(e) returns true for all emements e in a.
+// Complexity: O(len(a)).
 func AllOf[T any](a []T, pred func(T) bool) bool {
 	for _, v := range a {
 		if !pred(v) {
@@ -104,7 +115,8 @@ func AllOf[T any](a []T, pred func(T) bool) bool {
 	return true
 }
 
-// AllOf return true if pred(e) returns true for any emements e in a
+// AllOf return true if pred(e) returns true for any emements e in a.
+// Complexity: O(len(a)).
 func AnyOf[T any](a []T, pred func(T) bool) bool {
 	for _, v := range a {
 		if pred(v) {
@@ -114,7 +126,8 @@ func AnyOf[T any](a []T, pred func(T) bool) bool {
 	return false
 }
 
-// AllOf return true pred(e) returns true for none emements e in a
+// AllOf return true pred(e) returns true for none emements e in a.
+// Complexity: O(len(a)).
 func NoneOf[T any](a []T, pred func(T) bool) bool {
 	return !AnyOf(a, pred)
 }

sort.go

@@ -2,6 +2,8 @@ package contalgo
 
 import "golang.org/x/exp/constraints"
 
+// IsSorted returns whether the slice a is sorted in ascending order.
+// Complexity: O(len(a)).
 func IsSorted[T constraints.Ordered](a []T) bool {
 	if len(a) == 0 {
 		return true

transform.go

@@ -1,15 +1,38 @@
 package contalgo
 
-func Transform[R any, T any](a []T, op func(T) R) []R {
+// Transform applies the function op to each element in slice a and fill it to slice b.
+// The len(b) must not lesser than len(a).
+// Complexity: O(len(a)).
+func TransformTo[R any, T any](a []T, op func(T) R, b []R) {
+	if len(b) < len(a) {
+		panic("TransformTo: len(b) < len(a)")
+	}
+	for i, v := range a {
+		b[i] = op(v)
+	}
+}
+
+// Transform applies the function op to each element in slice a and set it back to the same place in a.
+// Complexity: O(len(a)).
+func Transform[T any](a []T, op func(T) T) {
+	for i, v := range a {
+		a[i] = op(v)
+	}
+}
+
+// Transform applies the function op to each element in slice a and return all the result as a slice.
+// Complexity: O(len(a)).
+func TransformCopy[R any, T any](a []T, op func(T) R) []R {
 	r := make([]R, 0, len(a))
 	for _, v := range a {
 		r = append(r, op(v))
 	}
 	return r
 }
 
-// Unique remove adjacent repeated elements from the input slice
+// Unique remove adjacent repeated elements from the input slice.
 // return the processed slice, andthe origin slice is also changed.
+// Complexity: O(len(a)).
 func Unique[T comparable](a []T) []T {
 	if len(a) == 0 {
 		return a
@@ -26,8 +49,9 @@ func Unique[T comparable](a []T) []T {
 	return a[:i]
 }
 
-// Unique remove adjacent repeated elements from the input slice
+// Unique remove adjacent repeated elements from the input slice.
 // return the processed slice, andthe origin slice is kept unchanged.
+// Complexity: O(len(a)).
 func UniqueCopy[T comparable](a []T) []T {
 	var r []T
 	if len(a) == 0 {

transform_test.go

@@ -1,6 +1,7 @@
 package contalgo
 
 import (
+	"strconv"
 	"testing"
 )
 
@@ -10,9 +11,30 @@ var (
 
 func TestTransform(t *testing.T) {
 	a := Range(0, 100)
-	b := Transform(a, func(v int) int { return v * v })
+	Transform(a, func(v int) int { return v * v })
 	for i, v := range a {
-		expectEq(t, v*v, b[i])
+		expectEq(t, v, i*i)
+	}
+}
+
+func TestTransformTo(t *testing.T) {
+	a := Range(0, 100)
+	b := make([]string, len(a))
+	TransformTo(a, func(v int) string { return strconv.Itoa(v) }, b)
+	for i, v := range a {
+		expectEq(t, strconv.Itoa(v), b[i])
+	}
+	expactPanic(t, func() {
+		c := make([]string, len(a)-1)
+		TransformTo(a, func(v int) string { return strconv.Itoa(v) }, c)
+	})
+}
+
+func TestTransformCopy(t *testing.T) {
+	a := Range(0, 100)
+	b := TransformCopy(a, func(v int) string { return strconv.Itoa(v) })
+	for i, v := range b {
+		expectEq(t, v, strconv.Itoa(i))
 	}
 }