New algo and update doc (#22)

* implement Sorts, Shuffle and Reverse
* rename Clean to Clear
* update docs automatically

container.go

@@ -4,5 +4,5 @@ package contalgo
 type Container[T any] interface {
 	IsEmpty() bool // IsEmpty checks if the container has no elements.
 	Len() int      // Len returns the number of elements in the container.
-	Clean()        // Clean erases all elements from the container. After this call, Len() returns zero.
+	Clear()        // Clear erases all elements from the container. After this call, Len() returns zero.
 }

dlist.go

@@ -16,22 +16,22 @@ type dListNode[T any] struct {
 // NewDList make a new DList object
 func NewDList[T any]() *DList[T] {
 	l := DList[T]{}
-	l.Clean()
+	l.Clear()
 	return &l
 }
 
 // NewDListOf make a new DList from a serial of values
 func NewDListOf[T any](vs ...T) *DList[T] {
 	l := DList[T]{}
-	l.Clean()
+	l.Clear()
 	for _, v := range vs {
 		l.PushBack(v)
 	}
 	return &l
 }
 
-// Clean cleanup the list
-func (l *DList[T]) Clean() {
+// Clear cleanup the list
+func (l *DList[T]) Clear() {
 	l.head.prev = &l.head
 	l.head.next = &l.head
 	l.length = 0

queue.go

@@ -12,7 +12,7 @@ type Queue[T any] struct {
 // NewQueue create a new Queue object.
 func NewQueue[T any]() *Queue[T] {
 	q := Queue[T]{}
-	q.list.Clean()
+	q.list.Clear()
 	return &q
 }
 
@@ -24,8 +24,8 @@ func (q *Queue[T]) IsEmpty() bool {
 	return q.list.IsEmpty()
 }
 
-func (q *Queue[T]) Clean() {
-	q.list.Clean()
+func (q *Queue[T]) Clear() {
+	q.list.Clear()
 }
 
 func (q *Queue[T]) String() string {

queue_test.go

@@ -14,10 +14,10 @@ func Test_Queue_New(t *testing.T) {
 	expectEq(t, 0, q.Len())
 }
 
-func Test_Queue_Clean(t *testing.T) {
+func Test_Queue_Clear(t *testing.T) {
 	q := NewQueue[int]()
 	q.PushBack(1)
-	q.Clean()
+	q.Clear()
 	expectTrue(t, q.IsEmpty())
 	expectEq(t, 0, q.Len())
 }

set.go

@@ -22,7 +22,7 @@ func (s *Set[K]) Len() int {
 	return len(*s)
 }
 
-func (s *Set[K]) Clean() {
+func (s *Set[K]) Clear() {
 	for k := range *s {
 		delete(*s, k)
 	}

set_test.go

@@ -35,9 +35,9 @@ func Test_Set_IsEmpty(t *testing.T) {
 	expectEq(t, s.IsEmpty(), false)
 }
 
-func Test_Set_Clean(t *testing.T) {
+func Test_Set_Clear(t *testing.T) {
 	s := MakeSetOf("hello", "world")
-	s.Clean()
+	s.Clear()
 	expectTrue(t, s.IsEmpty())
 }
 

sort.go

@@ -1,5 +1,9 @@
 package contalgo
 
+import (
+	"sort"
+)
+
 // IsSorted returns whether the slice a is sorted in ascending order.
 //
 // Complexity: O(len(a)).
@@ -16,3 +20,89 @@ func IsSorted[T Ordered](a []T) bool {
 	}
 	return true
 }
+
+// IsDescSorted returns whether the slice a is sorted in descending order.
+//
+// Complexity: O(len(a)).
+func IsDescSorted[T Ordered](a []T) bool {
+	if len(a) == 0 {
+		return true
+	}
+	prev := a[0]
+	for _, v := range a[1:] {
+		if v > prev {
+			return false
+		}
+		prev = v
+	}
+	return true
+}
+
+type ascSlice[T Ordered] []T
+
+func (x ascSlice[T]) Len() int           { return len(x) }
+func (x ascSlice[T]) Less(i, j int) bool { return x[i] < x[j] }
+func (x ascSlice[T]) Swap(i, j int)      { x[i], x[j] = x[j], x[i] }
+
+// Sort sorts data in ascending order.
+// The order of equal elements is not guaranteed to be preserved.
+//
+// Complexity: O(N*log(N)), N=len(a).
+func Sort[T Ordered](a []T) {
+	sort.Sort(ascSlice[T](a))
+}
+
+// StableSort sorts data in ascending order stably.
+// The order of equivalent elements is guaranteed to be preserved.
+//
+// Complexity: O(N*log(N)), N=len(a).
+func StableSort[T Ordered](a []T) {
+	sort.Stable(ascSlice[T](a))
+}
+
+type descSlice[T Ordered] []T
+
+func (x descSlice[T]) Len() int           { return len(x) }
+func (x descSlice[T]) Less(i, j int) bool { return x[i] > x[j] }
+func (x descSlice[T]) Swap(i, j int)      { x[i], x[j] = x[j], x[i] }
+
+// DescSort sorts data in descending order.
+// The order of equal elements is not guaranteed to be preserved.
+//
+// Complexity: O(N*log(N)), N=len(a).
+func DescSort[T Ordered](a []T) {
+	sort.Sort(descSlice[T](a))
+}
+
+// DescStableSort sorts data in descending order stably.
+// The order of equivalent elements is guaranteed to be preserved.
+//
+// Complexity: O(N*log(N)), N=len(a).
+func DescStableSort[T Ordered](a []T) {
+	sort.Stable(descSlice[T](a))
+}
+
+type funcSortable[T any] struct {
+	e    []T
+	less LessFn[T]
+}
+
+func (x funcSortable[T]) Len() int           { return len(x.e) }
+func (x funcSortable[T]) Less(i, j int) bool { return x.less(x.e[i], x.e[j]) }
+func (x funcSortable[T]) Swap(i, j int)      { x.e[i], x.e[j] = x.e[j], x.e[i] }
+
+// SortFunc sorts data in ascending order with compare func less.
+// The order of equal elements is not guaranteed to be preserved.
+//
+// Complexity: O(N*log(N)), N=len(a).
+func SortFunc[T any](a []T, less func(x, y T) bool) {
+	sort.Sort(funcSortable[T]{a, less})
+}
+
+// StableSortFunc sorts data in ascending order with compare func less stably.
+// The order of equivalent elements is guaranteed to be preserved.
+//
+// Complexity: O(N*log(N)), N=len(a).
+func StableSortFunc[T any](a []T, less func(x, y T) bool) {
+	sort.Stable(funcSortable[T]{a, less})
+}

sort_test.go

@@ -10,3 +10,48 @@ func Test_IsSorted(t *testing.T) {
 	expectTrue(t, IsSorted([]int{1, 2, 2, 3, 4}))
 	expectFalse(t, IsSorted([]int{1, 2, 2, 3, 2}))
 }
+
+func Test_IsDescSorted(t *testing.T) {
+	expectTrue(t, IsDescSorted([]int{}))
+	expectFalse(t, IsDescSorted([]int{1, 2, 3, 4}))
+	expectFalse(t, IsDescSorted([]int{1, 2, 2, 3, 4}))
+	expectTrue(t, IsDescSorted([]int{5, 4, 3, 3, 2}))
+}
+
+func Test_Sort(t *testing.T) {
+	a := []int{5, 4, 3, 2, 1}
+	Sort(a)
+	expectTrue(t, IsSorted(a))
+}
+
+func Test_DescSort(t *testing.T) {
+	a := []int{1, 2, 3, 4}
+	DescSort(a)
+	expectTrue(t, IsDescSorted(a))
+}
+
+func Test_StableSort(t *testing.T) {
+	a := []int{5, 4, 3, 2, 1}
+	StableSort(a)
+	expectTrue(t, IsSorted(a))
+}
+
+func Test_DescStableSort(t *testing.T) {
+	a := []int{1, 2, 3, 4, 5}
+	DescStableSort(a)
+	expectTrue(t, IsDescSorted(a))
+}
+
+func greater(x, y int) bool { return x > y }
+
+func Test_SortFunc(t *testing.T) {
+	a := []int{1, 2, 3, 4, 5}
+	SortFunc(a, greater)
+	expectTrue(t, IsDescSorted(a))
+}
+
+func Test_StableSortFunc(t *testing.T) {
+	a := []int{1, 2, 3, 4, 5}
+	StableSortFunc(a, greater)
+	expectTrue(t, IsDescSorted(a))
+}

stack.go

@@ -28,7 +28,7 @@ func (s *Stack[T]) Cap() int {
 	return cap(s.ele)
 }
 
-func (s *Stack[T]) Clean() {
+func (s *Stack[T]) Clear() {
 	s.ele = s.ele[0:0]
 }
 

stack_test.go

@@ -27,11 +27,11 @@ func Test_StackCap(t *testing.T) {
 	expectEq(t, 10, s.Cap())
 }
 
-func Test_Stack_Clean(t *testing.T) {
+func Test_Stack_Clear(t *testing.T) {
 	s := NewStack[int]()
 	s.Push(1)
 	s.Push(2)
-	s.Clean()
+	s.Clear()
 	expectEq(t, 0, s.Len())
 	expectTrue(t, s.IsEmpty())
 }

transform.go

@@ -1,5 +1,7 @@
 package contalgo
 
+import "math/rand"
+
 // Copy make a copy of slice a.
 //
 // Complexity: O(len(a)).
@@ -140,3 +142,21 @@ func RemoveIfCopy[T any](a []T, cond func(T) bool) []T {
 	}
 	return r
 }
+
+// Shuffle pseudo-randomizes the order of elements.
+//
+// Complexity: O(len(a)).
+func Shuffle[T any](a []T) {
+	rand.Shuffle(len(a), func(i, j int) {
+		a[i], a[j] = a[j], a[i]
+	})
+}
+
+// Reverse reverses the order of the elements in the slice a.
+//
+// Complexity: O(len(a)).
+func Reverse[T any](a []T) {
+	for i, j := 0, len(a)-1; i < j; i, j = i+1, j-1 {
+		a[i], a[j] = a[j], a[i]
+	}
+}

transform_test.go

@@ -90,3 +90,20 @@ func Test_RemoveIfCopy(t *testing.T) {
 	expectTrue(t, Equal([]int{1, 3, 4}, b))
 	expectTrue(t, Equal(a1, a))
 }
+
+func Test_Shuffle(t *testing.T) {
+	a := []int{1, 2, 3, 4, 5, 6}
+	Shuffle(a)
+}
+
+func Test_Reverse(t *testing.T) {
+	a := []int{1, 2, 3, 4}
+	Reverse(a)
+	expectTrue(t, Equal(a, []int{4, 3, 2, 1}))
+}
+
+func Test_Reverse_Odd(t *testing.T) {
+	a := []int{1, 2, 3, 4, 5}
+	Reverse(a)
+	expectTrue(t, Equal(a, []int{5, 4, 3, 2, 1}))
+}

updatedoc.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+gomarkdoc -o README.md -e .

vector.go

@@ -31,9 +31,9 @@ func (v *Vector[T]) Cap() int {
 	return cap(*v)
 }
 
-// Clean erases all elements from the vector. After this call, Len() returns zero.
+// Clear erases all elements from the vector. After this call, Len() returns zero.
 // Leaves the Cap() of the vector unchanged.
-func (v *Vector[T]) Clean() {
+func (v *Vector[T]) Clear() {
 	*v = (*v)[0:0]
 }
 

vector_test.go

@@ -41,9 +41,9 @@ func Test_VectorCap(t *testing.T) {
 	expectEq(t, 10, v.Cap())
 }
 
-func Test_Vector_Clean(t *testing.T) {
+func Test_Vector_Clear(t *testing.T) {
 	v := MakeVectorOf(1, 2, 3)
-	v.Clean()
+	v.Clear()
 	expectEq(t, 0, v.Len())
 	expectTrue(t, v.IsEmpty())
 	expectGt(t, v.Cap(), 0)