From 41cf3ca21b631e68e8c0532d541582f9de1ddcd1 Mon Sep 17 00:00:00 2001 From: CHEN Feng Date: Sun, 14 Aug 2022 21:06:18 +0800 Subject: [PATCH] update docs (#61) --- README.md | 1497 +++++--------------------------------------------- README_zh.md | 1493 ++++--------------------------------------------- updatedoc.sh | 3 +- 3 files changed, 242 insertions(+), 2751 deletions(-) diff --git a/README.md b/README.md index 8de9125..deb7f2f 100644 --- a/README.md +++ b/README.md @@ -16,1448 +16,197 @@ This library depends on go generics, which is introduced in 1.18+. -# stl4go - -```go -import "github.com/chen3feng/stl4go" -``` - -Package stl4go is a generic container and algorithm library for go. - -## Index - -- [func AllOf[T any](a []T, pred func(T) bool) bool](<#func-allof>) -- [func AnyOf[T any](a []T, pred func(T) bool) bool](<#func-anyof>) -- [func Average[T Numeric](a []T) T](<#func-average>) -- [func AverageAs[R, T Numeric](a []T) R](<#func-averageas>) -- [func BinarySearch[T Ordered](a []T, value T) (index int, ok bool)](<#func-binarysearch>) -- [func BinarySearchFunc[T any](a []T, value T, less LessFn[T]) (index int, ok bool)](<#func-binarysearchfunc>) -- [func Compare[E Ordered](a, b []E) int](<#func-compare>) -- [func Copy[T any](a []T) []T](<#func-copy>) -- [func Count[T comparable](a []T, x T) int](<#func-count>) -- [func CountIf[T comparable](a []T, pred func(T) bool) int](<#func-countif>) -- [func DescSort[T Ordered](a []T)](<#func-descsort>) -- [func DescStableSort[T Ordered](a []T)](<#func-descstablesort>) -- [func Equal[T comparable](a, b []T) bool](<#func-equal>) -- [func Equals[T comparable](a, b T) bool](<#func-equals>) -- [func Find[T comparable](a []T, x T) (index int, ok bool)](<#func-find>) -- [func FindIf[T any](a []T, cond func(T) bool) (index int, ok bool)](<#func-findif>) -- [func Generate[T any](a []T, gen func() T)](<#func-generate>) -- [func Index[T comparable](a []T, x T) int](<#func-index>) -- [func IsDescSorted[T Ordered](a []T) bool](<#func-isdescsorted>) -- [func IsSorted[T Ordered](a []T) bool](<#func-issorted>) -- [func Less[T Ordered](a, b T) bool](<#func-less>) -- [func LowerBound[T Ordered](a []T, value T) int](<#func-lowerbound>) -- [func LowerBoundFunc[T any](a []T, value T, less LessFn[T]) int](<#func-lowerboundfunc>) -- [func Max[T Ordered](a, b T) T](<#func-max>) -- [func MaxN[T Ordered](a ...T) T](<#func-maxn>) -- [func Min[T Ordered](a, b T) T](<#func-min>) -- [func MinMax[T Ordered](a, b T) (min, max T)](<#func-minmax>) -- [func MinMaxN[T Ordered](a ...T) (min, max T)](<#func-minmaxn>) -- [func MinN[T Ordered](a ...T) T](<#func-minn>) -- [func NoneOf[T any](a []T, pred func(T) bool) bool](<#func-noneof>) -- [func OrderedCompare[T Ordered](a, b T) int](<#func-orderedcompare>) -- [func Range[T Numeric](first, last T) []T](<#func-range>) -- [func Remove[T comparable](a []T, x T) []T](<#func-remove>) -- [func RemoveCopy[T comparable](a []T, x T) []T](<#func-removecopy>) -- [func RemoveIf[T any](a []T, cond func(T) bool) []T](<#func-removeif>) -- [func RemoveIfCopy[T any](a []T, cond func(T) bool) []T](<#func-removeifcopy>) -- [func Reverse[T any](a []T)](<#func-reverse>) -- [func ReverseCopy[T any](a []T) []T](<#func-reversecopy>) -- [func Shuffle[T any](a []T)](<#func-shuffle>) -- [func Sort[T Ordered](a []T)](<#func-sort>) -- [func SortFunc[T any](a []T, less func(x, y T) bool)](<#func-sortfunc>) -- [func StableSort[T Ordered](a []T)](<#func-stablesort>) -- [func StableSortFunc[T any](a []T, less func(x, y T) bool)](<#func-stablesortfunc>) -- [func Sum[T Numeric](a []T) T](<#func-sum>) -- [func SumAs[R, T Numeric](a []T) R](<#func-sumas>) -- [func Transform[T any](a []T, op func(T) T)](<#func-transform>) -- [func TransformCopy[R any, T any](a []T, op func(T) R) []R](<#func-transformcopy>) -- [func TransformTo[R any, T any](a []T, op func(T) R, b []R)](<#func-transformto>) -- [func Unique[T comparable](a []T) []T](<#func-unique>) -- [func UniqueCopy[T comparable](a []T) []T](<#func-uniquecopy>) -- [func UpperBound[T Ordered](a []T, value T) int](<#func-upperbound>) -- [func UpperBoundFunc[T any](a []T, value T, less LessFn[T]) int](<#func-upperboundfunc>) -- [type BuiltinSet](<#type-builtinset>) - - [func MakeBuiltinSetOf[K comparable](ks ...K) BuiltinSet[K]](<#func-makebuiltinsetof>) - - [func (s *BuiltinSet[K]) Clear()](<#func-builtinsetk-clear>) - - [func (s *BuiltinSet[K]) ForEach(cb func(k K))](<#func-builtinsetk-foreach>) - - [func (s *BuiltinSet[K]) ForEachIf(cb func(k K) bool)](<#func-builtinsetk-foreachif>) - - [func (s *BuiltinSet[K]) Has(k K) bool](<#func-builtinsetk-has>) - - [func (s *BuiltinSet[K]) Insert(k K)](<#func-builtinsetk-insert>) - - [func (s *BuiltinSet[K]) InsertN(ks ...K)](<#func-builtinsetk-insertn>) - - [func (s *BuiltinSet[K]) IsEmpty() bool](<#func-builtinsetk-isempty>) - - [func (s *BuiltinSet[K]) Keys() []K](<#func-builtinsetk-keys>) - - [func (s *BuiltinSet[K]) Len() int](<#func-builtinsetk-len>) - - [func (s *BuiltinSet[K]) Remove(k K) bool](<#func-builtinsetk-remove>) - - [func (s *BuiltinSet[K]) RemoveN(ks ...K)](<#func-builtinsetk-removen>) - - [func (s BuiltinSet[K]) String() string](<#func-builtinsetk-string>) -- [type CompareFn](<#type-comparefn>) -- [type Container](<#type-container>) -- [type DList](<#type-dlist>) - - [func NewDList[T any]() *DList[T]](<#func-newdlist>) - - [func NewDListOf[T any](vs ...T) *DList[T]](<#func-newdlistof>) - - [func (l *DList[T]) Clear()](<#func-dlistt-clear>) - - [func (l *DList[T]) ForEach(cb func(val T))](<#func-dlistt-foreach>) - - [func (l *DList[T]) ForEachIf(cb func(val T) bool)](<#func-dlistt-foreachif>) - - [func (l *DList[T]) IsEmpty() bool](<#func-dlistt-isempty>) - - [func (l *DList[T]) Iterate() Iterator[T]](<#func-dlistt-iterate>) - - [func (l *DList[T]) Len() int](<#func-dlistt-len>) - - [func (l *DList[T]) PopBack() (T, bool)](<#func-dlistt-popback>) - - [func (l *DList[T]) PopFront() (T, bool)](<#func-dlistt-popfront>) - - [func (l *DList[T]) PushBack(val T)](<#func-dlistt-pushback>) - - [func (l *DList[T]) PushFront(val T)](<#func-dlistt-pushfront>) - - [func (l *DList[T]) String() string](<#func-dlistt-string>) -- [type Float](<#type-float>) -- [type HashFn](<#type-hashfn>) -- [type Integer](<#type-integer>) -- [type Iterator](<#type-iterator>) -- [type LessFn](<#type-lessfn>) -- [type Map](<#type-map>) -- [type MapIterator](<#type-mapiterator>) -- [type Numeric](<#type-numeric>) -- [type Ordered](<#type-ordered>) -- [type Queue](<#type-queue>) - - [func NewQueue[T any]() *Queue[T]](<#func-newqueue>) - - [func (q *Queue[T]) Clear()](<#func-queuet-clear>) - - [func (q *Queue[T]) IsEmpty() bool](<#func-queuet-isempty>) - - [func (q *Queue[T]) Len() int](<#func-queuet-len>) - - [func (q *Queue[T]) PopBack() (T, bool)](<#func-queuet-popback>) - - [func (q *Queue[T]) PopFront() (T, bool)](<#func-queuet-popfront>) - - [func (q *Queue[T]) PushBack(val T)](<#func-queuet-pushback>) - - [func (q *Queue[T]) PushFront(val T)](<#func-queuet-pushfront>) - - [func (q *Queue[T]) String() string](<#func-queuet-string>) -- [type Set](<#type-set>) -- [type Signed](<#type-signed>) -- [type SkipList](<#type-skiplist>) - - [func NewSkipList[K Ordered, V any]() *SkipList[K, V]](<#func-newskiplist>) - - [func NewSkipListFromMap[K Ordered, V any](m map[K]V) *SkipList[K, V]](<#func-newskiplistfrommap>) - - [func NewSkipListFunc[K any, V any](keyCmp CompareFn[K]) *SkipList[K, V]](<#func-newskiplistfunc>) - - [func (sl *SkipList[K, V]) Clear()](<#func-skiplistk-v-clear>) - - [func (sl *SkipList[K, V]) Find(key K) *V](<#func-skiplistk-v-find>) - - [func (sl *SkipList[K, V]) FindRange(first, last K) MapIterator[K, V]](<#func-skiplistk-v-findrange>) - - [func (sl *SkipList[K, V]) ForEach(op func(K, V))](<#func-skiplistk-v-foreach>) - - [func (sl *SkipList[K, V]) ForEachIf(op func(K, V) bool)](<#func-skiplistk-v-foreachif>) - - [func (sl *SkipList[K, V]) ForEachMutable(op func(K, *V))](<#func-skiplistk-v-foreachmutable>) - - [func (sl *SkipList[K, V]) ForEachMutableIf(op func(K, *V) bool)](<#func-skiplistk-v-foreachmutableif>) - - [func (sl *SkipList[K, V]) Has(key K) bool](<#func-skiplistk-v-has>) - - [func (sl *SkipList[K, V]) Insert(key K, value V)](<#func-skiplistk-v-insert>) - - [func (sl *SkipList[K, V]) IsEmpty() bool](<#func-skiplistk-v-isempty>) - - [func (sl *SkipList[K, V]) Iterate() MapIterator[K, V]](<#func-skiplistk-v-iterate>) - - [func (sl *SkipList[K, V]) Len() int](<#func-skiplistk-v-len>) - - [func (sl *SkipList[K, V]) LowerBound(key K) MapIterator[K, V]](<#func-skiplistk-v-lowerbound>) - - [func (sl *SkipList[K, V]) Remove(key K) bool](<#func-skiplistk-v-remove>) - - [func (sl *SkipList[K, V]) UpperBound(key K) MapIterator[K, V]](<#func-skiplistk-v-upperbound>) -- [type Stack](<#type-stack>) - - [func NewStack[T any]() *Stack[T]](<#func-newstack>) - - [func NewStackCap[T any](capicity int) *Stack[T]](<#func-newstackcap>) - - [func (s *Stack[T]) Cap() int](<#func-stackt-cap>) - - [func (s *Stack[T]) Clear()](<#func-stackt-clear>) - - [func (s *Stack[T]) IsEmpty() bool](<#func-stackt-isempty>) - - [func (s *Stack[T]) Len() int](<#func-stackt-len>) - - [func (s *Stack[T]) MustPop() T](<#func-stackt-mustpop>) - - [func (s *Stack[T]) Pop() (val T, ok bool)](<#func-stackt-pop>) - - [func (s *Stack[T]) Push(t T)](<#func-stackt-push>) -- [type Unsigned](<#type-unsigned>) -- [type Vector](<#type-vector>) - - [func MakeVector[T any]() Vector[T]](<#func-makevector>) - - [func MakeVectorCap[T any](c int) Vector[T]](<#func-makevectorcap>) - - [func MakeVectorOf[T any](v ...T) Vector[T]](<#func-makevectorof>) - - [func (v *Vector[T]) Append(x ...T)](<#func-vectort-append>) - - [func (v *Vector[T]) At(i int) T](<#func-vectort-at>) - - [func (v *Vector[T]) Cap() int](<#func-vectort-cap>) - - [func (v *Vector[T]) Clear()](<#func-vectort-clear>) - - [func (v *Vector[T]) Insert(i int, x ...T)](<#func-vectort-insert>) - - [func (v *Vector[T]) IsEmpty() bool](<#func-vectort-isempty>) - - [func (v *Vector[T]) Len() int](<#func-vectort-len>) - - [func (v *Vector[T]) PushBack(x T)](<#func-vectort-pushback>) - - [func (v *Vector[T]) Remove(i int)](<#func-vectort-remove>) - - [func (v *Vector[T]) RemoveLength(i int, len int)](<#func-vectort-removelength>) - - [func (v *Vector[T]) RemoveRange(i, j int)](<#func-vectort-removerange>) - - [func (v *Vector[T]) Reserve(l int)](<#func-vectort-reserve>) - - [func (v *Vector[T]) Set(i int, x T)](<#func-vectort-set>) - - [func (v *Vector[T]) Shrink()](<#func-vectort-shrink>) - - -## func [AllOf]() - -```go -func AllOf[T any](a []T, pred func(T) bool) bool -``` - -AllOf return true if pred\(e\) returns true for all emements e in a. - -Complexity: O\(len\(a\)\). - -## func [AnyOf]() - -```go -func AnyOf[T any](a []T, pred func(T) bool) bool -``` - -AnyOf return true if pred\(e\) returns true for any emements e in a. - -Complexity: O\(len\(a\)\). - -## func [Average]() - -```go -func Average[T Numeric](a []T) T -``` - -Average returns the average value of a. - -## func [AverageAs]() - -```go -func AverageAs[R, T Numeric](a []T) R -``` - -AverageAs returns the average value of a as type R. - -## func [BinarySearch]() - -```go -func BinarySearch[T Ordered](a []T, value T) (index int, ok bool) -``` - -BinarySearch returns the \(index, true\) to the first element in the ascending ordered slice a such that element == value, or \(\-1, false\) if no such element is found. - -Complexity: O\(log\(len\(a\)\)\). - -## func [BinarySearchFunc]() - -```go -func BinarySearchFunc[T any](a []T, value T, less LessFn[T]) (index int, ok bool) -``` - -BinarySearchFunc returns the \(index, true\) to the first element in the ordered slice a such that less\(element, value\) and less\(value, element\) are both false, or \(\-1, false\) if no such element is found. - -The elements in the slice a should sorted according with compare func less. - -Complexity: O\(log\(len\(a\)\)\). - -## func [Compare]() - -```go -func Compare[E Ordered](a, b []E) int -``` - -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 [Copy]() - -```go -func Copy[T any](a []T) []T -``` - -Copy make a copy of slice a. - -Complexity: O\(len\(a\)\). - -## func [Count]() - -```go -func Count[T comparable](a []T, x T) int -``` - -Count returns the number of elements in the slice equals to x. - -Complexity: O\(len\(a\)\). - -## func [CountIf]() - -```go -func CountIf[T comparable](a []T, pred func(T) bool) int -``` - -CountIf returns the number of elements in the slice which pred returns true. - -Complexity: O\(len\(a\)\). - -## func [DescSort]() - -```go -func DescSort[T Ordered](a []T) -``` - -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 [DescStableSort]() - -```go -func DescStableSort[T Ordered](a []T) -``` - -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 [Equal]() - -```go -func Equal[T comparable](a, b []T) bool -``` - -Equal returns whether two slices are equal. Return true if they are the same length and all elements are equal. - -Complexity: O\(min\(len\(a\), len\(b\)\)\). - -## func [Equals]() - -```go -func Equals[T comparable](a, b T) bool -``` - -Equals wraps the '==' operator for comparable types. - -## func [Find]() - -```go -func Find[T comparable](a []T, x T) (index int, ok bool) -``` - -Find find the first value x in the given slice a linearly. return \(index, true\) if found, return \(\_, false\) if not found. - -Complexity: O\(len\(a\)\). - -## func [FindIf]() - -```go -func FindIf[T any](a []T, cond func(T) bool) (index int, ok bool) -``` - -FindIf find the first value x satisfying function cond in the given slice a linearly. return \(index, true\) if found, return \(\_, false\) if not found. - -Complexity: O\(len\(a\)\). - -## func [Generate]() - -```go -func Generate[T any](a []T, gen func() T) -``` - -Generate fill each element of \`a\`\` with \`gen\(\)\`. - -Complexity: O\(len\(a\)\). - -## func [Index]() - -```go -func Index[T comparable](a []T, x T) int -``` - -Index find the value x in the given slice a linearly. - -Return index if found, \-1 if not found. - -Complexity: O\(len\(a\)\). - -## func [IsDescSorted]() - -```go -func IsDescSorted[T Ordered](a []T) bool -``` - -IsDescSorted returns whether the slice a is sorted in descending order. - -Complexity: O\(len\(a\)\). - -## func [IsSorted]() - -```go -func IsSorted[T Ordered](a []T) bool -``` - -IsSorted returns whether the slice a is sorted in ascending order. - -Complexity: O\(len\(a\)\). - -## func [Less]() - -```go -func Less[T Ordered](a, b T) bool -``` - -Less wraps the '\<' operator for ordered types. - -## func [LowerBound]() - -```go -func LowerBound[T Ordered](a []T, value T) int -``` - -LowerBound returns an index to the first element in the ascending ordered slice a that does not satisfy element \< value \(i.e. greater or equal to\), or len\(a\) if no such element is found. - -Complexity: O\(log\(len\(a\)\)\). - -## func [LowerBoundFunc]() - -```go -func LowerBoundFunc[T any](a []T, value T, less LessFn[T]) int -``` - -LowerBoundFunc returns an index to the first element in the ordered slice a that does not satisfy less\(element, value\)\), or len\(a\) if no such element is found. - -The elements in the slice a should sorted according with compare func less. - -Complexity: O\(log\(len\(a\)\)\). - -## func [Max]() - -```go -func Max[T Ordered](a, b T) T -``` - -Max return the larger value between \`a\` and \`b\`. - -Complexity: O\(1\). - -## func [MaxN]() - -```go -func MaxN[T Ordered](a ...T) T -``` - -MaxN return the maximum value in the sequence \`a\`. - -Complexity: O\(len\(a\)\). - -## func [Min]() - -```go -func Min[T Ordered](a, b T) T -``` - -Min return the smaller value between \`a\` and \`b\`. - -Complexity: O\(1\). - -## func [MinMax]() - -```go -func MinMax[T Ordered](a, b T) (min, max T) -``` - -MinMax returns both min and max between a and b. - -Complexity: O\(1\). - -## func [MinMaxN]() - -```go -func MinMaxN[T Ordered](a ...T) (min, max T) -``` - -MinMaxN returns both min and max in slice a. - -Complexity: O\(len\(a\)\) - -## func [MinN]() - -```go -func MinN[T Ordered](a ...T) T -``` - -MinN return the minimum value in the sequence \`a\`. - -Complexity: O\(len\(a\)\). - -## func [NoneOf]() - -```go -func NoneOf[T any](a []T, pred func(T) bool) bool -``` - -NoneOf return true pred\(e\) returns true for none emements e in a. - -Complexity: O\(len\(a\)\). - -## func [OrderedCompare]() - -```go -func OrderedCompare[T Ordered](a, b T) int -``` - -OrderedCompare provide default CompareFn for ordered types. - -## func [Range]() - -```go -func Range[T Numeric](first, last T) []T -``` - -Range make a \[\]T filled with values in the \`\[first, last\)\` sequence. NOTE: the last is not included in the result. - -Complexity: O\(last\-first\). - -## func [Remove]() - -```go -func Remove[T comparable](a []T, x T) []T -``` - -Remove remove the elements which equals to x from the input slice. return the processed slice, and the content of the input slice is also changed. - -Complexity: O\(len\(a\)\). - -## func [RemoveCopy]() - -```go -func RemoveCopy[T comparable](a []T, x T) []T -``` - -RemoveCopy remove all elements which equals to x from the input slice. return the processed slice, and the content of the input slice is also changed. - -Complexity: O\(len\(a\)\). - -## func [RemoveIf]() - -```go -func RemoveIf[T any](a []T, cond func(T) bool) []T -``` - -RemoveIf remove each element which make cond\(x\) returns true from the input slice, copy other elements to a new slice and return it. The input slice is kept unchanged. - -Complexity: O\(len\(a\)\). - -## func [RemoveIfCopy]() - -```go -func RemoveIfCopy[T any](a []T, cond func(T) bool) []T -``` - -RemoveIfCopy drops each element which make cond\(x\) returns true from the input slice, copy other elements to a new slice and return it. The input slice is kept unchanged. - -Complexity: O\(len\(a\)\). - -## func [Reverse]() - -```go -func Reverse[T any](a []T) -``` - -Reverse reverses the order of the elements in the slice a. - -Complexity: O\(len\(a\)\). - -## func [ReverseCopy]() - -```go -func ReverseCopy[T any](a []T) []T -``` - -ReverseCopy returns a reversed copy of slice a. - -Complexity: O\(len\(a\)\). - -## func [Shuffle]() - -```go -func Shuffle[T any](a []T) -``` - -Shuffle pseudo\-randomizes the order of elements. - -Complexity: O\(len\(a\)\). - -## func [Sort]() - -```go -func Sort[T Ordered](a []T) -``` - -Sort sorts data in ascending order. The order of equal elements is not guaranteed to be preserved. - -Complexity: O\(N\*log\(N\)\), where N=len\(a\). - -## func [SortFunc]() - -```go -func SortFunc[T any](a []T, less func(x, y T) bool) -``` - -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 [StableSort]() - -```go -func StableSort[T Ordered](a []T) -``` - -StableSort sorts data in ascending order stably. The order of equivalent elements is guaranteed to be preserved. - -Complexity: O\(N\*log\(N\)^2\), where N=len\(a\). - -## func [StableSortFunc]() - -```go -func StableSortFunc[T any](a []T, less func(x, y T) bool) -``` - -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 [Sum]() - -```go -func Sum[T Numeric](a []T) T -``` - -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 [SumAs]() - -```go -func SumAs[R, T Numeric](a []T) R -``` - -SumAs 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 [Transform]() - -```go -func Transform[T any](a []T, op func(T) T) -``` - -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 [TransformCopy]() - -```go -func TransformCopy[R any, T any](a []T, op func(T) R) []R -``` - -TransformCopy applies the function op to each element in slice a and return all the result as a slice. - -Complexity: O\(len\(a\)\). - -## func [TransformTo]() - -```go -func TransformTo[R any, T any](a []T, op func(T) R, b []R) -``` - -TransformTo 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 [Unique]() - -```go -func Unique[T comparable](a []T) []T -``` - -Unique remove adjacent repeated elements from the input slice. return the processed slice, and the content of the input slice is also changed. - -Complexity: O\(len\(a\)\). - -## func [UniqueCopy]() - -```go -func UniqueCopy[T comparable](a []T) []T -``` - -UniqueCopy remove adjacent repeated elements from the input slice. return the result slice, and the input slice is kept unchanged. - -Complexity: O\(len\(a\)\). - -## func [UpperBound]() - -```go -func UpperBound[T Ordered](a []T, value T) int -``` - -UpperBound returns an index to the first element in the ascending ordered slice a such that value \< element \(i.e. strictly greater\), or len\(a\) if no such element is found. - -Complexity: O\(log\(len\(a\)\)\). - -## func [UpperBoundFunc]() - -```go -func UpperBoundFunc[T any](a []T, value T, less LessFn[T]) int -``` - -UpperBoundFunc returns an index to the first element in the ordered slice a such that less\(value, element\)\) is true \(i.e. strictly greater\), or len\(a\) if no such element is found. - -The elements in the slice a should sorted according with compare func less. - -Complexity: O\(log\(len\(a\)\)\). - -## type [BuiltinSet]() - -BuiltinSet is an associative container that contains a unordered set of unique objects of type K. - -```go -type BuiltinSet[K comparable] map[K]bool -``` - -### func [MakeBuiltinSetOf]() - -```go -func MakeBuiltinSetOf[K comparable](ks ...K) BuiltinSet[K] -``` - -MakeBuiltinSetOf creates a new BuiltinSet object with the initial content from ks. - -### func \(\*BuiltinSet\[K\]\) [Clear]() - -```go -func (s *BuiltinSet[K]) Clear() -``` - -### func \(\*BuiltinSet\[K\]\) [ForEach]() - -```go -func (s *BuiltinSet[K]) ForEach(cb func(k K)) -``` - -### func \(\*BuiltinSet\[K\]\) [ForEachIf]() - -```go -func (s *BuiltinSet[K]) ForEachIf(cb func(k K) bool) -``` - -### func \(\*BuiltinSet\[K\]\) [Has]() - -```go -func (s *BuiltinSet[K]) Has(k K) bool -``` - -### func \(\*BuiltinSet\[K\]\) [Insert]() - -```go -func (s *BuiltinSet[K]) Insert(k K) -``` - -### func \(\*BuiltinSet\[K\]\) [InsertN]() - -```go -func (s *BuiltinSet[K]) InsertN(ks ...K) -``` - -### func \(\*BuiltinSet\[K\]\) [IsEmpty]() - -```go -func (s *BuiltinSet[K]) IsEmpty() bool -``` - -### func \(\*BuiltinSet\[K\]\) [Keys]() - -```go -func (s *BuiltinSet[K]) Keys() []K -``` - -### func \(\*BuiltinSet\[K\]\) [Len]() - -```go -func (s *BuiltinSet[K]) Len() int -``` - -### func \(\*BuiltinSet\[K\]\) [Remove]() - -```go -func (s *BuiltinSet[K]) Remove(k K) bool -``` - -### func \(\*BuiltinSet\[K\]\) [RemoveN]() - -```go -func (s *BuiltinSet[K]) RemoveN(ks ...K) -``` - -### func \(BuiltinSet\[K\]\) [String]() - -```go -func (s BuiltinSet[K]) String() string -``` - -## type [CompareFn]() - -CompareFn is a 3 way compare function that returns 1 if a \> b, returns 0 if a == b, returns \-1 if a \< b. - -```go -type CompareFn[T any] func(a, b T) int -``` - -## type [Container]() - -Container is a holder object that stores a collection of other objects. - -```go -type Container interface { - IsEmpty() bool // IsEmpty checks if the container has no elements. - Len() int // Len returns the number of elements in the container. - Clear() // Clear erases all elements from the container. After this call, Len() returns zero. -} -``` - -## type [DList]() - -DList is a doubly linked list. - -```go -type DList[T any] struct { - // contains filtered or unexported fields -} -``` - -### func [NewDList]() - -```go -func NewDList[T any]() *DList[T] -``` - -NewDList make a new DList object - -### func [NewDListOf]() - -```go -func NewDListOf[T any](vs ...T) *DList[T] -``` - -NewDListOf make a new DList from a serial of values - -### func \(\*DList\[T\]\) [Clear]() - -```go -func (l *DList[T]) Clear() -``` - -Clear cleanup the list - -### func \(\*DList\[T\]\) [ForEach]() - -```go -func (l *DList[T]) ForEach(cb func(val T)) -``` - -ForEach iterate the list, apply each element to the cb callback function - -### func \(\*DList\[T\]\) [ForEachIf]() - -```go -func (l *DList[T]) ForEachIf(cb func(val T) bool) -``` - -ForEach iterate the list, apply each element to the cb callback function, stop if cb returns false. - -### func \(\*DList\[T\]\) [IsEmpty]() - -```go -func (l *DList[T]) IsEmpty() bool -``` - -IsEmpty return whether the list is empty - -### func \(\*DList\[T\]\) [Iterate]() - -```go -func (l *DList[T]) Iterate() Iterator[T] -``` - -Iterate returns an iterator to the first element in the list. - -### func \(\*DList\[T\]\) [Len]() - -```go -func (l *DList[T]) Len() int -``` - -Len return the length of the list - -### func \(\*DList\[T\]\) [PopBack]() - -```go -func (l *DList[T]) PopBack() (T, bool) -``` - -### func \(\*DList\[T\]\) [PopFront]() - -```go -func (l *DList[T]) PopFront() (T, bool) -``` - -### func \(\*DList\[T\]\) [PushBack]() - -```go -func (l *DList[T]) PushBack(val T) -``` - -### func \(\*DList\[T\]\) [PushFront]() - -```go -func (l *DList[T]) PushFront(val T) -``` - -### func \(\*DList\[T\]\) [String]() - -```go -func (l *DList[T]) String() string -``` - -String convert the list to string - -## type [Float]() - -Float is a constraint that permits any floating\-point type. If future releases of Go add new predeclared floating\-point types, this constraint will be modified to include them. - -```go -type Float interface { - // contains filtered or unexported methods -} -``` - -## type [HashFn]() - -HashFn is a function that returns the hash of 't'. - -```go -type HashFn[T any] func(t T) uint64 -``` - -## type [Integer]() - -Integer is a constraint that permits any integer type. If future releases of Go add new predeclared integer types, this constraint will be modified to include them. - -```go -type Integer interface { - // contains filtered or unexported methods -} -``` - -## type [Iterator]() - -Iterator is the interface for container's iterator. - -```go -type Iterator[T any] interface { - IsNotEnd() bool // Whether it is point to the end of the range. - MoveToNext() // Let it point to the next element. - Value() T // Return the value of current element. -} -``` - -## type [LessFn]() - -LessFn is a function that returns whether 'a' is less than 'b'. - -```go -type LessFn[T any] func(a, b T) bool -``` - -## type [Map]() - -Map is a associative container that contains key\-value pairs with unique keys. - -```go -type Map[K any, V any] interface { - Container - Has(K) bool // Checks whether the container contains element with specific key. - Find(K) *V // Finds element with specific key. - Insert(K, V) // Inserts a key-value pair in to the container or replace existing value. - Remove(K) bool // Remove element with specific key. - ForEach(func(K, V)) // Iterate the container. - ForEachIf(func(K, V) bool) // Iterate the container, stops when the callback returns false. - ForEachMutable(func(K, *V)) // Iterate the container, *V is mutable. - ForEachMutableIf(func(K, *V) bool) // Iterate the container, *V is mutable, stops when the callback returns false. -} -``` - -## type [MapIterator]() - -MapIterator is the interface for map's iterator. - -```go -type MapIterator[K any, V any] interface { - Key() K // The key of the element - // contains filtered or unexported methods -} -``` - -## type [Numeric]() - -Numeric is a constraint that permits any numeric type. - -```go -type Numeric interface { - // contains filtered or unexported methods -} -``` - -## type [Ordered]() - -Ordered is a constraint that permits any ordered type: any type that supports the operators \< \<= \>= \>. If future releases of Go add new ordered types, this constraint will be modified to include them. - -```go -type Ordered interface { - // contains filtered or unexported methods -} -``` - -## type [Queue]() - -Queue is a FIFO container - -```go -type Queue[T any] struct { - // contains filtered or unexported fields -} -``` - -### func [NewQueue]() - ```go -func NewQueue[T any]() *Queue[T] +import "github.com/chen3feng/stl4go" ``` -NewQueue create a new Queue object. +Package stl4go is a generic container and algo +rithm library for go. -### func \(\*Queue\[T\]\) [Clear]() +## Introduce -```go -func (q *Queue[T]) Clear() -``` - -### func \(\*Queue\[T\]\) [IsEmpty]() - -```go -func (q *Queue[T]) IsEmpty() bool -``` +This library is a general container and algorithm library that attempts to learn from the C++ STL implementation after Go 1.18 began to support generics. +(Personally I's totally unacceptable for me use to languages without generics, so I didn't try it until go 1.18). -### func \(\*Queue\[T\]\) [Len]() +The code quality of this library is quite high and follows the latest best practices in the industry. +Test coverage is close💯%, ✅，CI, and [gosec](https://securego.io/) check are both set up, got +[![GoReport](https://goreportcard.com/badge/github.com/securego/gosec)](https://goreportcard.com/report/github.com/chen3feng/stl4go) score。 -```go -func (q *Queue[T]) Len() int -``` +## Features -### func \(\*Queue\[T\]\) [PopBack]() +As we all know, C++'s STL includes containers, algorithms, and iterators relate the two. -```go -func (q *Queue[T]) PopBack() (T, bool) -``` +Due to language limitations, it is impossible and unnecessary to completely imitate the interface of C++ STL in Go, +so C++ users may feel familiar, and sometimes (maybe) feel more convenient. -### func \(\*Queue\[T\]\) [PopFront]() +### Containers -```go -func (q *Queue[T]) PopFront() (T, bool) -``` +Currently implemented containers are: -### func \(\*Queue\[T\]\) [PushBack]() +- [x] `BuiltinSet` provided a set funtionality based on Go's own `map` +- [x] `Vector` is a thin encapsulation based on `slice`. It provides functions such as insertion and deletion in the middle, range deletion, etc., + and is still compatible with slices. +- [x] `DList` is a doubly linked list. +- [x] [SkipList](skiplist.md) is an ordered associative container that fills the gap where Go `map` only supports unordered. + This is currently the fastest skip list I tested in GitHub, see [skiplist-survey](https://github.com/chen3feng/skiplist-survey) for performance comparison +- [x] `Stack`, is a FILO container based on Slice implementation +- [x] `Queue` is a bidirectional FIFO queue, implemented based on linked list. -```go -func (q *Queue[T]) PushBack(val T) -``` +Different containers support different methods. The following are the methods supported by all containers: -### func \(\*Queue\[T\]\) [PushFront]() +- `IsEmpty() bool` Returns whether the container is empty +- `Len() int` returns the number of elements in the container +- `Clear()` to clear the container -```go -func (q *Queue[T]) PushFront(val T) -``` +### Iterators -### func \(\*Queue\[T\]\) [String]() +DList and SkipList support simple iterators. ```go -func (q *Queue[T]) String() string + l := stl4go.NewDListOf(Range(1, 10000)...) + sum := 0 + for i := 0; i < b.N; i++ { + for it := l.Iterate(); it.IsNotEnd(); it.MoveToNext() { + sum += it.Value() + } + } ``` -## type [Set]() - -Set is a containers that store unique elements. +SkipList also supports interval iteration: ```go -type Set[K any] interface { - Container - Has(K) bool // Checks whether the container contains element with specific key. - Insert(K) // Inserts a key-value pair in to the container or replace existing value. - InsertN(...K) // Inserts multiple key-value pairs in to the container or replace existing value. - Remove(K) bool // Remove element with specific key. - RemoveN(...K) // Remove multiple elements with specific keys. - ForEach(func(K)) // Iterate the container. - ForEachIf(func(K) bool) // Iterate the container, stops when the callback returns false. -} + l := stl4go.NewDListOf(Range(1, 1000)...) + it := sl.FindRange(120, 350) ``` -## type [Signed]() +Iterating over `it` yields numbers between 120 and 349. -Signed is a constraint that permits any signed integer type. If future releases of Go add new predeclared signed integer types, this constraint will be modified to include them. +In many cases, it is more convenient to use the `ForEach` and `ForEachIf` methods provided by the container, +and the performance is often better: ```go -type Signed interface { - // contains filtered or unexported methods +func TestSkipList_ForEach(t *testing.T) { + sl := newSkipListN(100) + a := []int{} + sl.ForEach(func(k int, v int) { + a = append(a, k) + }) + expectEq(t, len(a), 100) + expectTrue(t, IsSorted(a)) } ``` -## type [SkipList]() - -SkipList is a probabilistic data structure that seem likely to supplant balanced trees as the implementation method of choice for many applications. Skip list algorithms have the same asymptotic expected time bounds as balanced trees and are simpler, faster and use less space. - -See https://en.wikipedia.org/wiki/Skip_list for more details. +`ForEachIf` is used for scenarios that you want to end early during the iteration: -```go -type SkipList[K any, V any] struct { - // contains filtered or unexported fields + ```go +func Test_DList_ForEachIf(t *testing.T) { + l := NewDListOf(1, 2, 3) + c := 0 + l.ForEachIf(func(n int) bool { + c = n + return n != 2 + }) + expectEq(t, c, 2) } -``` - -### func [NewSkipList]() - -```go -func NewSkipList[K Ordered, V any]() *SkipList[K, V] -``` - -NewSkipList creates a new SkipList for Ordered key type. - -### func [NewSkipListFromMap]() - -```go -func NewSkipListFromMap[K Ordered, V any](m map[K]V) *SkipList[K, V] -``` - -NewSkipListFromMap creates a new SkipList from a map. - -### func [NewSkipListFunc]() - -```go -func NewSkipListFunc[K any, V any](keyCmp CompareFn[K]) *SkipList[K, V] -``` - -NewSkipListFunc creates a new SkipList with specified compare function keyCmp. - -### func \(\*SkipList\[K, V\]\) [Clear]() - -```go -func (sl *SkipList[K, V]) Clear() -``` - -### func \(\*SkipList\[K, V\]\) [Find]() - -```go -func (sl *SkipList[K, V]) Find(key K) *V -``` - -Find returns the value associated with the passed key if the key is in the skiplist, otherwise returns nil. - -### func \(\*SkipList\[K, V\]\) [FindRange]() - -```go -func (sl *SkipList[K, V]) FindRange(first, last K) MapIterator[K, V] -``` - -FindRange returns an iterator in range \[first, last\) \(last is not includeed\). - -### func \(\*SkipList\[K, V\]\) [ForEach]() - -```go -func (sl *SkipList[K, V]) ForEach(op func(K, V)) -``` - -### func \(\*SkipList\[K, V\]\) [ForEachIf]() - -```go -func (sl *SkipList[K, V]) ForEachIf(op func(K, V) bool) -``` - -### func \(\*SkipList\[K, V\]\) [ForEachMutable]() - -```go -func (sl *SkipList[K, V]) ForEachMutable(op func(K, *V)) -``` - -### func \(\*SkipList\[K, V\]\) [ForEachMutableIf]() - -```go -func (sl *SkipList[K, V]) ForEachMutableIf(op func(K, *V) bool) -``` - -### func \(\*SkipList\[K, V\]\) [Has]() - -```go -func (sl *SkipList[K, V]) Has(key K) bool -``` - -### func \(\*SkipList\[K, V\]\) [Insert]() - -```go -func (sl *SkipList[K, V]) Insert(key K, value V) -``` - -Insert inserts a key\-value pair into the skiplist. If the key is already in the skip list, it's value will be updated. - -### func \(\*SkipList\[K, V\]\) [IsEmpty]() - -```go -func (sl *SkipList[K, V]) IsEmpty() bool -``` + ``` -### func \(\*SkipList\[K, V\]\) [Iterate]() +You can use `ForEachMutable` or `ForEachMutable` to modify the value of an element during the iteration: ```go -func (sl *SkipList[K, V]) Iterate() MapIterator[K, V] -``` - -### func \(\*SkipList\[K, V\]\) [Len]() - -```go -func (sl *SkipList[K, V]) Len() int -``` - -### func \(\*SkipList\[K, V\]\) [LowerBound]() - -```go -func (sl *SkipList[K, V]) LowerBound(key K) MapIterator[K, V] -``` - -### func \(\*SkipList\[K, V\]\) [Remove]() - -```go -func (sl *SkipList[K, V]) Remove(key K) bool -``` - -Remove removes the key\-value pair associated with the passed key and returns true if the key is in the skiplist, otherwise returns false. - -### func \(\*SkipList\[K, V\]\) [UpperBound]() - -```go -func (sl *SkipList[K, V]) UpperBound(key K) MapIterator[K, V] -``` - -## type [Stack]() - -Stack s is a container adaptor that provides the functionality of a stack, a LIFO \(last\-in, first\-out\) data structure. - -```go -type Stack[T any] struct { - // contains filtered or unexported fields +func TestSkipList_ForEachMutable(t *testing.T) { + sl := newSkipListN(100) + sl.ForEachMutable(func(k int, v *int) { + *v = -*v + }) + for i := 0; i < sl.Len(); i++ { + expectEq(t, *sl.Find(i), -i) + } } ``` -### func [NewStack]() - -```go -func NewStack[T any]() *Stack[T] -``` +### Algorithms -NewStack creates a new Stack object. +Due to the limitations of language, most algorithms only support Slice. The functions name of the algorithms ends with `If`, `Func`, +indicating that a custom comparison function can be passed. -### func [NewStackCap]() +#### Generate -```go -func NewStackCap[T any](capicity int) *Stack[T] -``` +- `Range` returns a Slice of contains integers in the range of `[begin, end)` +- `Generate` generates a sequence with the given function to fill the Slice -NewStackCap creates a new Stack object with the specified capicity. +#### Compute -### func \(\*Stack\[T\]\) [Cap]() +- `Sum` Sum +- `SumAs` sums and returns a result as another type (eg. use `int64` to return the sum of `[]int32`). +- `Average` finds the average value. +- `AverageAs` averages and returns the result as another type (eg. use `float64` to return the sum of `[]int`). +- `Count` returns the number equivalent to the specified value +- `CountIf` returns the number of elements for which the specified function returns `true` -```go -func (s *Stack[T]) Cap() int -``` +#### Compare -### func \(\*Stack\[T\]\) [Clear]() +- `Equal` checks whether two sequences are equal +- `Compare` compares two sequences and returns `-1`, `0`, and `1` in lexicographical order, respectively indicating the relationship of 2 slices. -```go -func (s *Stack[T]) Clear() -``` +#### Lookup -### func \(\*Stack\[T\]\) [IsEmpty]() +- `Min`, `Max` find the maximum and minimum +- `MinN`, `MaxN`, `MinMax` return the maximum and minimum values in the slice +- `Find` linearly finds the first specified value and returns its index +- `FindIf` linearly finds the first value that make specified function returns `true` and returns its index +- `AllOf`, `AnyOf`, `NoneOf` return whether all, any, or none of the elements in the range can make the passed function return `true` accordingly. -```go -func (s *Stack[T]) IsEmpty() bool -``` +#### Binary Search -### func \(\*Stack\[T\]\) [Len]() +See C++ STL. -```go -func (s *Stack[T]) Len() int -``` +- BinarySearch +- LowerBound +- UpperBound -### func \(\*Stack\[T\]\) [MustPop]() +#### Sort -```go -func (s *Stack[T]) MustPop() T -``` +- `Sort` sorting +- `DescSort` descending sorting +- `StableSort` stable sorting +- `DescStableSort` descending stable sorting +- `IsSorted` check whether the slice is sorted +- `IsDescSorted` check whether the slice is sorted in descending order -### func \(\*Stack\[T\]\) [Pop]() +### Interface Design and Naming -```go -func (s *Stack[T]) Pop() (val T, ok bool) -``` +The design leart much from the C++ STL. The `T` here represents `template`. Yes, Go's generic is not template. but who made C++ so influential and STL so famous? -### func \(\*Stack\[T\]\) [Push]() +Many libraries are designed for small code repositories or split into multiple subpackages in one repository. +For example: ```go -func (s *Stack[T]) Push(t T) -``` +import ( + "github.com/someone/awesomelib/skiplist" + "github.com/someone/awesomelib/binarysearch" +) -## type [Unsigned]() - -Unsigned is a constraint that permits any unsigned integer type. If future releases of Go add new predeclared unsigned integer types, this constraint will be modified to include them. - -```go -type Unsigned interface { - // contains filtered or unexported methods +func main() { + sl := skiplist.New() } ``` -## type [Vector]() - -Vector is a sequence container representing array that can change in size. - -```go -type Vector[T any] []T -``` - -### func [MakeVector]() - -```go -func MakeVector[T any]() Vector[T] -``` - -MakeVector creates an empty Vector object. - -### func [MakeVectorCap]() - -```go -func MakeVectorCap[T any](c int) Vector[T] -``` - -MakeVectorCap creates an empty Vector object with specified capacity. - -### func [MakeVectorOf]() - -```go -func MakeVectorOf[T any](v ...T) Vector[T] -``` - -MakeVectorOf creates an Vector object with initial values. - -### func \(\*Vector\[T\]\) [Append]() - -```go -func (v *Vector[T]) Append(x ...T) -``` - -Append appends the values x... to the tail of the vector. - -### func \(\*Vector\[T\]\) [At]() - -```go -func (v *Vector[T]) At(i int) T -``` - -### func \(\*Vector\[T\]\) [Cap]() - -```go -func (v *Vector[T]) Cap() int -``` - -### func \(\*Vector\[T\]\) [Clear]() - -```go -func (v *Vector[T]) Clear() -``` - -Clear erases all elements from the vector. After this call, Len\(\) returns zero. Leaves the Cap\(\) of the vector unchanged. - -### func \(\*Vector\[T\]\) [Insert]() - -```go -func (v *Vector[T]) Insert(i int, x ...T) -``` - -Insert inserts the values x... into the vector at index i. After the insertion, \(\*v\)\[i\] == x\[0\]. Insert panics if i is out of range. - -Complexity: O\(len\(s\) \+ len\(v\)\). - -### func \(\*Vector\[T\]\) [IsEmpty]() - -```go -func (v *Vector[T]) IsEmpty() bool -``` - -### func \(\*Vector\[T\]\) [Len]() - -```go -func (v *Vector[T]) Len() int -``` - -### func \(\*Vector\[T\]\) [PushBack]() - -```go -func (v *Vector[T]) PushBack(x T) -``` - -### func \(\*Vector\[T\]\) [Remove]() - -```go -func (v *Vector[T]) Remove(i int) -``` - -Remove removes 1 element in the vector. - -Complexity: O\(len\(s\) \- i\). - -### func \(\*Vector\[T\]\) [RemoveLength]() - -```go -func (v *Vector[T]) RemoveLength(i int, len int) -``` - -Remove removes the elements in the range\[i, i\+len\) from the vector. - -### func \(\*Vector\[T\]\) [RemoveRange]() - -```go -func (v *Vector[T]) RemoveRange(i, j int) -``` - -Remove removes the elements in the range\[i, j\) from the vector. - -### func \(\*Vector\[T\]\) [Reserve]() - -```go -func (v *Vector[T]) Reserve(l int) -``` - -Reserve increases the capacity of the vector \(the total number of elements that the vector can hold without requiring reallocation\)to a value that's greater or equal to l. If l is greater than the current Cap\(\), new storage is allocated, otherwise the function does nothing. - -Reserve\(\) does not change the size of the vector. - -### func \(\*Vector\[T\]\) [Set]() - -```go -func (v *Vector[T]) Set(i int, x T) -``` - -### func \(\*Vector\[T\]\) [Shrink]() - -```go -func (v *Vector[T]) Shrink() -``` +This way of writing seems elegant, but because everyone likes good names, import renaming has to be introduced in use in case of package name conflict, +and different users have different renaming style, which increases the mental burden of code reading and writing. -Shrink removes unused capacity from the vector. +I don't like this style, especially in a larger repository. +Therefore, this library is all under the `stl4go` package, and it is expected that it will not namesake in other people's libraries. +### TODO -Generated by [gomarkdoc]() +See [Issue](https://github.com/chen3feng/stl4go/issues)。 +And add more detailed documents. - +## Go Doc +Clock to view the [generated doc](generated_doc.md). ## Reference - [C++ STL](https://en.wikipedia.org/wiki/Standard_Template_Library) diff --git a/README_zh.md b/README_zh.md index fdc95ec..c17dc91 100644 --- a/README_zh.md +++ b/README_zh.md @@ -10,1448 +10,191 @@ [![Coverage Status](https://coveralls.io/repos/github/chen3feng/stl4go/badge.svg?branch=master)](https://coveralls.io/github/chen3feng/stl4go?branch=master) [![GoReport](https://goreportcard.com/badge/github.com/securego/gosec)](https://goreportcard.com/report/github.com/chen3feng/stl4go) - - - - -# stl4go - -```go -import "github.com/chen3feng/stl4go" -``` - -Package stl4go is a generic container and algorithm library for go. - -## Index - -- [func AllOf[T any](a []T, pred func(T) bool) bool](<#func-allof>) -- [func AnyOf[T any](a []T, pred func(T) bool) bool](<#func-anyof>) -- [func Average[T Numeric](a []T) T](<#func-average>) -- [func AverageAs[R, T Numeric](a []T) R](<#func-averageas>) -- [func BinarySearch[T Ordered](a []T, value T) (index int, ok bool)](<#func-binarysearch>) -- [func BinarySearchFunc[T any](a []T, value T, less LessFn[T]) (index int, ok bool)](<#func-binarysearchfunc>) -- [func Compare[E Ordered](a, b []E) int](<#func-compare>) -- [func Copy[T any](a []T) []T](<#func-copy>) -- [func Count[T comparable](a []T, x T) int](<#func-count>) -- [func CountIf[T comparable](a []T, pred func(T) bool) int](<#func-countif>) -- [func DescSort[T Ordered](a []T)](<#func-descsort>) -- [func DescStableSort[T Ordered](a []T)](<#func-descstablesort>) -- [func Equal[T comparable](a, b []T) bool](<#func-equal>) -- [func Equals[T comparable](a, b T) bool](<#func-equals>) -- [func Find[T comparable](a []T, x T) (index int, ok bool)](<#func-find>) -- [func FindIf[T any](a []T, cond func(T) bool) (index int, ok bool)](<#func-findif>) -- [func Generate[T any](a []T, gen func() T)](<#func-generate>) -- [func Index[T comparable](a []T, x T) int](<#func-index>) -- [func IsDescSorted[T Ordered](a []T) bool](<#func-isdescsorted>) -- [func IsSorted[T Ordered](a []T) bool](<#func-issorted>) -- [func Less[T Ordered](a, b T) bool](<#func-less>) -- [func LowerBound[T Ordered](a []T, value T) int](<#func-lowerbound>) -- [func LowerBoundFunc[T any](a []T, value T, less LessFn[T]) int](<#func-lowerboundfunc>) -- [func Max[T Ordered](a, b T) T](<#func-max>) -- [func MaxN[T Ordered](a ...T) T](<#func-maxn>) -- [func Min[T Ordered](a, b T) T](<#func-min>) -- [func MinMax[T Ordered](a, b T) (min, max T)](<#func-minmax>) -- [func MinMaxN[T Ordered](a ...T) (min, max T)](<#func-minmaxn>) -- [func MinN[T Ordered](a ...T) T](<#func-minn>) -- [func NoneOf[T any](a []T, pred func(T) bool) bool](<#func-noneof>) -- [func OrderedCompare[T Ordered](a, b T) int](<#func-orderedcompare>) -- [func Range[T Numeric](first, last T) []T](<#func-range>) -- [func Remove[T comparable](a []T, x T) []T](<#func-remove>) -- [func RemoveCopy[T comparable](a []T, x T) []T](<#func-removecopy>) -- [func RemoveIf[T any](a []T, cond func(T) bool) []T](<#func-removeif>) -- [func RemoveIfCopy[T any](a []T, cond func(T) bool) []T](<#func-removeifcopy>) -- [func Reverse[T any](a []T)](<#func-reverse>) -- [func ReverseCopy[T any](a []T) []T](<#func-reversecopy>) -- [func Shuffle[T any](a []T)](<#func-shuffle>) -- [func Sort[T Ordered](a []T)](<#func-sort>) -- [func SortFunc[T any](a []T, less func(x, y T) bool)](<#func-sortfunc>) -- [func StableSort[T Ordered](a []T)](<#func-stablesort>) -- [func StableSortFunc[T any](a []T, less func(x, y T) bool)](<#func-stablesortfunc>) -- [func Sum[T Numeric](a []T) T](<#func-sum>) -- [func SumAs[R, T Numeric](a []T) R](<#func-sumas>) -- [func Transform[T any](a []T, op func(T) T)](<#func-transform>) -- [func TransformCopy[R any, T any](a []T, op func(T) R) []R](<#func-transformcopy>) -- [func TransformTo[R any, T any](a []T, op func(T) R, b []R)](<#func-transformto>) -- [func Unique[T comparable](a []T) []T](<#func-unique>) -- [func UniqueCopy[T comparable](a []T) []T](<#func-uniquecopy>) -- [func UpperBound[T Ordered](a []T, value T) int](<#func-upperbound>) -- [func UpperBoundFunc[T any](a []T, value T, less LessFn[T]) int](<#func-upperboundfunc>) -- [type BuiltinSet](<#type-builtinset>) - - [func MakeBuiltinSetOf[K comparable](ks ...K) BuiltinSet[K]](<#func-makebuiltinsetof>) - - [func (s *BuiltinSet[K]) Clear()](<#func-builtinsetk-clear>) - - [func (s *BuiltinSet[K]) ForEach(cb func(k K))](<#func-builtinsetk-foreach>) - - [func (s *BuiltinSet[K]) ForEachIf(cb func(k K) bool)](<#func-builtinsetk-foreachif>) - - [func (s *BuiltinSet[K]) Has(k K) bool](<#func-builtinsetk-has>) - - [func (s *BuiltinSet[K]) Insert(k K)](<#func-builtinsetk-insert>) - - [func (s *BuiltinSet[K]) InsertN(ks ...K)](<#func-builtinsetk-insertn>) - - [func (s *BuiltinSet[K]) IsEmpty() bool](<#func-builtinsetk-isempty>) - - [func (s *BuiltinSet[K]) Keys() []K](<#func-builtinsetk-keys>) - - [func (s *BuiltinSet[K]) Len() int](<#func-builtinsetk-len>) - - [func (s *BuiltinSet[K]) Remove(k K) bool](<#func-builtinsetk-remove>) - - [func (s *BuiltinSet[K]) RemoveN(ks ...K)](<#func-builtinsetk-removen>) - - [func (s BuiltinSet[K]) String() string](<#func-builtinsetk-string>) -- [type CompareFn](<#type-comparefn>) -- [type Container](<#type-container>) -- [type DList](<#type-dlist>) - - [func NewDList[T any]() *DList[T]](<#func-newdlist>) - - [func NewDListOf[T any](vs ...T) *DList[T]](<#func-newdlistof>) - - [func (l *DList[T]) Clear()](<#func-dlistt-clear>) - - [func (l *DList[T]) ForEach(cb func(val T))](<#func-dlistt-foreach>) - - [func (l *DList[T]) ForEachIf(cb func(val T) bool)](<#func-dlistt-foreachif>) - - [func (l *DList[T]) IsEmpty() bool](<#func-dlistt-isempty>) - - [func (l *DList[T]) Iterate() Iterator[T]](<#func-dlistt-iterate>) - - [func (l *DList[T]) Len() int](<#func-dlistt-len>) - - [func (l *DList[T]) PopBack() (T, bool)](<#func-dlistt-popback>) - - [func (l *DList[T]) PopFront() (T, bool)](<#func-dlistt-popfront>) - - [func (l *DList[T]) PushBack(val T)](<#func-dlistt-pushback>) - - [func (l *DList[T]) PushFront(val T)](<#func-dlistt-pushfront>) - - [func (l *DList[T]) String() string](<#func-dlistt-string>) -- [type Float](<#type-float>) -- [type HashFn](<#type-hashfn>) -- [type Integer](<#type-integer>) -- [type Iterator](<#type-iterator>) -- [type LessFn](<#type-lessfn>) -- [type Map](<#type-map>) -- [type MapIterator](<#type-mapiterator>) -- [type Numeric](<#type-numeric>) -- [type Ordered](<#type-ordered>) -- [type Queue](<#type-queue>) - - [func NewQueue[T any]() *Queue[T]](<#func-newqueue>) - - [func (q *Queue[T]) Clear()](<#func-queuet-clear>) - - [func (q *Queue[T]) IsEmpty() bool](<#func-queuet-isempty>) - - [func (q *Queue[T]) Len() int](<#func-queuet-len>) - - [func (q *Queue[T]) PopBack() (T, bool)](<#func-queuet-popback>) - - [func (q *Queue[T]) PopFront() (T, bool)](<#func-queuet-popfront>) - - [func (q *Queue[T]) PushBack(val T)](<#func-queuet-pushback>) - - [func (q *Queue[T]) PushFront(val T)](<#func-queuet-pushfront>) - - [func (q *Queue[T]) String() string](<#func-queuet-string>) -- [type Set](<#type-set>) -- [type Signed](<#type-signed>) -- [type SkipList](<#type-skiplist>) - - [func NewSkipList[K Ordered, V any]() *SkipList[K, V]](<#func-newskiplist>) - - [func NewSkipListFromMap[K Ordered, V any](m map[K]V) *SkipList[K, V]](<#func-newskiplistfrommap>) - - [func NewSkipListFunc[K any, V any](keyCmp CompareFn[K]) *SkipList[K, V]](<#func-newskiplistfunc>) - - [func (sl *SkipList[K, V]) Clear()](<#func-skiplistk-v-clear>) - - [func (sl *SkipList[K, V]) Find(key K) *V](<#func-skiplistk-v-find>) - - [func (sl *SkipList[K, V]) FindRange(first, last K) MapIterator[K, V]](<#func-skiplistk-v-findrange>) - - [func (sl *SkipList[K, V]) ForEach(op func(K, V))](<#func-skiplistk-v-foreach>) - - [func (sl *SkipList[K, V]) ForEachIf(op func(K, V) bool)](<#func-skiplistk-v-foreachif>) - - [func (sl *SkipList[K, V]) ForEachMutable(op func(K, *V))](<#func-skiplistk-v-foreachmutable>) - - [func (sl *SkipList[K, V]) ForEachMutableIf(op func(K, *V) bool)](<#func-skiplistk-v-foreachmutableif>) - - [func (sl *SkipList[K, V]) Has(key K) bool](<#func-skiplistk-v-has>) - - [func (sl *SkipList[K, V]) Insert(key K, value V)](<#func-skiplistk-v-insert>) - - [func (sl *SkipList[K, V]) IsEmpty() bool](<#func-skiplistk-v-isempty>) - - [func (sl *SkipList[K, V]) Iterate() MapIterator[K, V]](<#func-skiplistk-v-iterate>) - - [func (sl *SkipList[K, V]) Len() int](<#func-skiplistk-v-len>) - - [func (sl *SkipList[K, V]) LowerBound(key K) MapIterator[K, V]](<#func-skiplistk-v-lowerbound>) - - [func (sl *SkipList[K, V]) Remove(key K) bool](<#func-skiplistk-v-remove>) - - [func (sl *SkipList[K, V]) UpperBound(key K) MapIterator[K, V]](<#func-skiplistk-v-upperbound>) -- [type Stack](<#type-stack>) - - [func NewStack[T any]() *Stack[T]](<#func-newstack>) - - [func NewStackCap[T any](capicity int) *Stack[T]](<#func-newstackcap>) - - [func (s *Stack[T]) Cap() int](<#func-stackt-cap>) - - [func (s *Stack[T]) Clear()](<#func-stackt-clear>) - - [func (s *Stack[T]) IsEmpty() bool](<#func-stackt-isempty>) - - [func (s *Stack[T]) Len() int](<#func-stackt-len>) - - [func (s *Stack[T]) MustPop() T](<#func-stackt-mustpop>) - - [func (s *Stack[T]) Pop() (val T, ok bool)](<#func-stackt-pop>) - - [func (s *Stack[T]) Push(t T)](<#func-stackt-push>) -- [type Unsigned](<#type-unsigned>) -- [type Vector](<#type-vector>) - - [func MakeVector[T any]() Vector[T]](<#func-makevector>) - - [func MakeVectorCap[T any](c int) Vector[T]](<#func-makevectorcap>) - - [func MakeVectorOf[T any](v ...T) Vector[T]](<#func-makevectorof>) - - [func (v *Vector[T]) Append(x ...T)](<#func-vectort-append>) - - [func (v *Vector[T]) At(i int) T](<#func-vectort-at>) - - [func (v *Vector[T]) Cap() int](<#func-vectort-cap>) - - [func (v *Vector[T]) Clear()](<#func-vectort-clear>) - - [func (v *Vector[T]) Insert(i int, x ...T)](<#func-vectort-insert>) - - [func (v *Vector[T]) IsEmpty() bool](<#func-vectort-isempty>) - - [func (v *Vector[T]) Len() int](<#func-vectort-len>) - - [func (v *Vector[T]) PushBack(x T)](<#func-vectort-pushback>) - - [func (v *Vector[T]) Remove(i int)](<#func-vectort-remove>) - - [func (v *Vector[T]) RemoveLength(i int, len int)](<#func-vectort-removelength>) - - [func (v *Vector[T]) RemoveRange(i, j int)](<#func-vectort-removerange>) - - [func (v *Vector[T]) Reserve(l int)](<#func-vectort-reserve>) - - [func (v *Vector[T]) Set(i int, x T)](<#func-vectort-set>) - - [func (v *Vector[T]) Shrink()](<#func-vectort-shrink>) - - -## func [AllOf]() - -```go -func AllOf[T any](a []T, pred func(T) bool) bool -``` - -AllOf return true if pred\(e\) returns true for all emements e in a. - -Complexity: O\(len\(a\)\). - -## func [AnyOf]() - -```go -func AnyOf[T any](a []T, pred func(T) bool) bool -``` - -AnyOf return true if pred\(e\) returns true for any emements e in a. - -Complexity: O\(len\(a\)\). - -## func [Average]() - -```go -func Average[T Numeric](a []T) T -``` - -Average returns the average value of a. - -## func [AverageAs]() - -```go -func AverageAs[R, T Numeric](a []T) R -``` - -AverageAs returns the average value of a as type R. - -## func [BinarySearch]() - -```go -func BinarySearch[T Ordered](a []T, value T) (index int, ok bool) -``` - -BinarySearch returns the \(index, true\) to the first element in the ascending ordered slice a such that element == value, or \(\-1, false\) if no such element is found. - -Complexity: O\(log\(len\(a\)\)\). - -## func [BinarySearchFunc]() - -```go -func BinarySearchFunc[T any](a []T, value T, less LessFn[T]) (index int, ok bool) -``` - -BinarySearchFunc returns the \(index, true\) to the first element in the ordered slice a such that less\(element, value\) and less\(value, element\) are both false, or \(\-1, false\) if no such element is found. - -The elements in the slice a should sorted according with compare func less. - -Complexity: O\(log\(len\(a\)\)\). - -## func [Compare]() - -```go -func Compare[E Ordered](a, b []E) int -``` - -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 [Copy]() - -```go -func Copy[T any](a []T) []T -``` - -Copy make a copy of slice a. - -Complexity: O\(len\(a\)\). - -## func [Count]() - -```go -func Count[T comparable](a []T, x T) int -``` - -Count returns the number of elements in the slice equals to x. - -Complexity: O\(len\(a\)\). - -## func [CountIf]() - -```go -func CountIf[T comparable](a []T, pred func(T) bool) int -``` - -CountIf returns the number of elements in the slice which pred returns true. - -Complexity: O\(len\(a\)\). - -## func [DescSort]() - -```go -func DescSort[T Ordered](a []T) -``` - -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 [DescStableSort]() - -```go -func DescStableSort[T Ordered](a []T) -``` - -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 [Equal]() - -```go -func Equal[T comparable](a, b []T) bool -``` - -Equal returns whether two slices are equal. Return true if they are the same length and all elements are equal. - -Complexity: O\(min\(len\(a\), len\(b\)\)\). - -## func [Equals]() - -```go -func Equals[T comparable](a, b T) bool -``` - -Equals wraps the '==' operator for comparable types. - -## func [Find]() - -```go -func Find[T comparable](a []T, x T) (index int, ok bool) -``` - -Find find the first value x in the given slice a linearly. return \(index, true\) if found, return \(\_, false\) if not found. - -Complexity: O\(len\(a\)\). - -## func [FindIf]() - -```go -func FindIf[T any](a []T, cond func(T) bool) (index int, ok bool) -``` - -FindIf find the first value x satisfying function cond in the given slice a linearly. return \(index, true\) if found, return \(\_, false\) if not found. - -Complexity: O\(len\(a\)\). - -## func [Generate]() - -```go -func Generate[T any](a []T, gen func() T) -``` - -Generate fill each element of \`a\`\` with \`gen\(\)\`. - -Complexity: O\(len\(a\)\). - -## func [Index]() - -```go -func Index[T comparable](a []T, x T) int -``` - -Index find the value x in the given slice a linearly. - -Return index if found, \-1 if not found. - -Complexity: O\(len\(a\)\). - -## func [IsDescSorted]() - -```go -func IsDescSorted[T Ordered](a []T) bool -``` - -IsDescSorted returns whether the slice a is sorted in descending order. - -Complexity: O\(len\(a\)\). - -## func [IsSorted]() - -```go -func IsSorted[T Ordered](a []T) bool -``` - -IsSorted returns whether the slice a is sorted in ascending order. - -Complexity: O\(len\(a\)\). - -## func [Less]() - -```go -func Less[T Ordered](a, b T) bool -``` - -Less wraps the '\<' operator for ordered types. - -## func [LowerBound]() - -```go -func LowerBound[T Ordered](a []T, value T) int -``` - -LowerBound returns an index to the first element in the ascending ordered slice a that does not satisfy element \< value \(i.e. greater or equal to\), or len\(a\) if no such element is found. - -Complexity: O\(log\(len\(a\)\)\). - -## func [LowerBoundFunc]() - -```go -func LowerBoundFunc[T any](a []T, value T, less LessFn[T]) int -``` - -LowerBoundFunc returns an index to the first element in the ordered slice a that does not satisfy less\(element, value\)\), or len\(a\) if no such element is found. - -The elements in the slice a should sorted according with compare func less. - -Complexity: O\(log\(len\(a\)\)\). - -## func [Max]() - -```go -func Max[T Ordered](a, b T) T -``` - -Max return the larger value between \`a\` and \`b\`. - -Complexity: O\(1\). - -## func [MaxN]() - -```go -func MaxN[T Ordered](a ...T) T -``` - -MaxN return the maximum value in the sequence \`a\`. - -Complexity: O\(len\(a\)\). - -## func [Min]() - -```go -func Min[T Ordered](a, b T) T -``` - -Min return the smaller value between \`a\` and \`b\`. - -Complexity: O\(1\). - -## func [MinMax]() - -```go -func MinMax[T Ordered](a, b T) (min, max T) -``` - -MinMax returns both min and max between a and b. - -Complexity: O\(1\). - -## func [MinMaxN]() - -```go -func MinMaxN[T Ordered](a ...T) (min, max T) -``` - -MinMaxN returns both min and max in slice a. - -Complexity: O\(len\(a\)\) - -## func [MinN]() - -```go -func MinN[T Ordered](a ...T) T -``` - -MinN return the minimum value in the sequence \`a\`. - -Complexity: O\(len\(a\)\). - -## func [NoneOf]() - -```go -func NoneOf[T any](a []T, pred func(T) bool) bool -``` - -NoneOf return true pred\(e\) returns true for none emements e in a. - -Complexity: O\(len\(a\)\). - -## func [OrderedCompare]() - -```go -func OrderedCompare[T Ordered](a, b T) int -``` - -OrderedCompare provide default CompareFn for ordered types. - -## func [Range]() - -```go -func Range[T Numeric](first, last T) []T -``` - -Range make a \[\]T filled with values in the \`\[first, last\)\` sequence. NOTE: the last is not included in the result. - -Complexity: O\(last\-first\). - -## func [Remove]() - -```go -func Remove[T comparable](a []T, x T) []T -``` - -Remove remove the elements which equals to x from the input slice. return the processed slice, and the content of the input slice is also changed. - -Complexity: O\(len\(a\)\). - -## func [RemoveCopy]() - -```go -func RemoveCopy[T comparable](a []T, x T) []T -``` - -RemoveCopy remove all elements which equals to x from the input slice. return the processed slice, and the content of the input slice is also changed. - -Complexity: O\(len\(a\)\). - -## func [RemoveIf]() - -```go -func RemoveIf[T any](a []T, cond func(T) bool) []T -``` - -RemoveIf remove each element which make cond\(x\) returns true from the input slice, copy other elements to a new slice and return it. The input slice is kept unchanged. - -Complexity: O\(len\(a\)\). - -## func [RemoveIfCopy]() - -```go -func RemoveIfCopy[T any](a []T, cond func(T) bool) []T -``` - -RemoveIfCopy drops each element which make cond\(x\) returns true from the input slice, copy other elements to a new slice and return it. The input slice is kept unchanged. - -Complexity: O\(len\(a\)\). - -## func [Reverse]() - -```go -func Reverse[T any](a []T) -``` - -Reverse reverses the order of the elements in the slice a. - -Complexity: O\(len\(a\)\). - -## func [ReverseCopy]() - -```go -func ReverseCopy[T any](a []T) []T -``` - -ReverseCopy returns a reversed copy of slice a. - -Complexity: O\(len\(a\)\). - -## func [Shuffle]() - -```go -func Shuffle[T any](a []T) -``` - -Shuffle pseudo\-randomizes the order of elements. - -Complexity: O\(len\(a\)\). - -## func [Sort]() - -```go -func Sort[T Ordered](a []T) -``` - -Sort sorts data in ascending order. The order of equal elements is not guaranteed to be preserved. - -Complexity: O\(N\*log\(N\)\), where N=len\(a\). - -## func [SortFunc]() - -```go -func SortFunc[T any](a []T, less func(x, y T) bool) -``` - -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 [StableSort]() - -```go -func StableSort[T Ordered](a []T) -``` - -StableSort sorts data in ascending order stably. The order of equivalent elements is guaranteed to be preserved. - -Complexity: O\(N\*log\(N\)^2\), where N=len\(a\). - -## func [StableSortFunc]() - -```go -func StableSortFunc[T any](a []T, less func(x, y T) bool) -``` - -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 [Sum]() - -```go -func Sum[T Numeric](a []T) T -``` - -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 [SumAs]() - -```go -func SumAs[R, T Numeric](a []T) R -``` - -SumAs 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 [Transform]() - -```go -func Transform[T any](a []T, op func(T) T) -``` - -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 [TransformCopy]() - -```go -func TransformCopy[R any, T any](a []T, op func(T) R) []R -``` - -TransformCopy applies the function op to each element in slice a and return all the result as a slice. - -Complexity: O\(len\(a\)\). - -## func [TransformTo]() - -```go -func TransformTo[R any, T any](a []T, op func(T) R, b []R) -``` - -TransformTo 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 [Unique]() - -```go -func Unique[T comparable](a []T) []T -``` - -Unique remove adjacent repeated elements from the input slice. return the processed slice, and the content of the input slice is also changed. - -Complexity: O\(len\(a\)\). - -## func [UniqueCopy]() - -```go -func UniqueCopy[T comparable](a []T) []T -``` - -UniqueCopy remove adjacent repeated elements from the input slice. return the result slice, and the input slice is kept unchanged. - -Complexity: O\(len\(a\)\). - -## func [UpperBound]() - -```go -func UpperBound[T Ordered](a []T, value T) int -``` - -UpperBound returns an index to the first element in the ascending ordered slice a such that value \< element \(i.e. strictly greater\), or len\(a\) if no such element is found. - -Complexity: O\(log\(len\(a\)\)\). - -## func [UpperBoundFunc]() - -```go -func UpperBoundFunc[T any](a []T, value T, less LessFn[T]) int -``` - -UpperBoundFunc returns an index to the first element in the ordered slice a such that less\(value, element\)\) is true \(i.e. strictly greater\), or len\(a\) if no such element is found. - -The elements in the slice a should sorted according with compare func less. - -Complexity: O\(log\(len\(a\)\)\). - -## type [BuiltinSet]() - -BuiltinSet is an associative container that contains a unordered set of unique objects of type K. - -```go -type BuiltinSet[K comparable] map[K]bool -``` - -### func [MakeBuiltinSetOf]() - -```go -func MakeBuiltinSetOf[K comparable](ks ...K) BuiltinSet[K] -``` - -MakeBuiltinSetOf creates a new BuiltinSet object with the initial content from ks. - -### func \(\*BuiltinSet\[K\]\) [Clear]() - -```go -func (s *BuiltinSet[K]) Clear() -``` - -### func \(\*BuiltinSet\[K\]\) [ForEach]() - -```go -func (s *BuiltinSet[K]) ForEach(cb func(k K)) -``` - -### func \(\*BuiltinSet\[K\]\) [ForEachIf]() - -```go -func (s *BuiltinSet[K]) ForEachIf(cb func(k K) bool) -``` - -### func \(\*BuiltinSet\[K\]\) [Has]() - -```go -func (s *BuiltinSet[K]) Has(k K) bool -``` - -### func \(\*BuiltinSet\[K\]\) [Insert]() - -```go -func (s *BuiltinSet[K]) Insert(k K) -``` - -### func \(\*BuiltinSet\[K\]\) [InsertN]() - -```go -func (s *BuiltinSet[K]) InsertN(ks ...K) -``` - -### func \(\*BuiltinSet\[K\]\) [IsEmpty]() - -```go -func (s *BuiltinSet[K]) IsEmpty() bool -``` - -### func \(\*BuiltinSet\[K\]\) [Keys]() - -```go -func (s *BuiltinSet[K]) Keys() []K -``` - -### func \(\*BuiltinSet\[K\]\) [Len]() - -```go -func (s *BuiltinSet[K]) Len() int -``` - -### func \(\*BuiltinSet\[K\]\) [Remove]() - -```go -func (s *BuiltinSet[K]) Remove(k K) bool -``` - -### func \(\*BuiltinSet\[K\]\) [RemoveN]() - -```go -func (s *BuiltinSet[K]) RemoveN(ks ...K) -``` - -### func \(BuiltinSet\[K\]\) [String]() - -```go -func (s BuiltinSet[K]) String() string -``` - -## type [CompareFn]() - -CompareFn is a 3 way compare function that returns 1 if a \> b, returns 0 if a == b, returns \-1 if a \< b. - -```go -type CompareFn[T any] func(a, b T) int -``` - -## type [Container]() - -Container is a holder object that stores a collection of other objects. - -```go -type Container interface { - IsEmpty() bool // IsEmpty checks if the container has no elements. - Len() int // Len returns the number of elements in the container. - Clear() // Clear erases all elements from the container. After this call, Len() returns zero. -} -``` - -## type [DList]() - -DList is a doubly linked list. - -```go -type DList[T any] struct { - // contains filtered or unexported fields -} -``` - -### func [NewDList]() - -```go -func NewDList[T any]() *DList[T] -``` - -NewDList make a new DList object - -### func [NewDListOf]() - -```go -func NewDListOf[T any](vs ...T) *DList[T] -``` - -NewDListOf make a new DList from a serial of values - -### func \(\*DList\[T\]\) [Clear]() - -```go -func (l *DList[T]) Clear() -``` - -Clear cleanup the list - -### func \(\*DList\[T\]\) [ForEach]() - -```go -func (l *DList[T]) ForEach(cb func(val T)) -``` - -ForEach iterate the list, apply each element to the cb callback function - -### func \(\*DList\[T\]\) [ForEachIf]() - -```go -func (l *DList[T]) ForEachIf(cb func(val T) bool) -``` - -ForEach iterate the list, apply each element to the cb callback function, stop if cb returns false. - -### func \(\*DList\[T\]\) [IsEmpty]() - -```go -func (l *DList[T]) IsEmpty() bool -``` - -IsEmpty return whether the list is empty - -### func \(\*DList\[T\]\) [Iterate]() - -```go -func (l *DList[T]) Iterate() Iterator[T] -``` - -Iterate returns an iterator to the first element in the list. - -### func \(\*DList\[T\]\) [Len]() - -```go -func (l *DList[T]) Len() int -``` - -Len return the length of the list - -### func \(\*DList\[T\]\) [PopBack]() - -```go -func (l *DList[T]) PopBack() (T, bool) -``` - -### func \(\*DList\[T\]\) [PopFront]() - -```go -func (l *DList[T]) PopFront() (T, bool) -``` - -### func \(\*DList\[T\]\) [PushBack]() - -```go -func (l *DList[T]) PushBack(val T) -``` - -### func \(\*DList\[T\]\) [PushFront]() - -```go -func (l *DList[T]) PushFront(val T) -``` - -### func \(\*DList\[T\]\) [String]() - -```go -func (l *DList[T]) String() string -``` - -String convert the list to string - -## type [Float]() - -Float is a constraint that permits any floating\-point type. If future releases of Go add new predeclared floating\-point types, this constraint will be modified to include them. - -```go -type Float interface { - // contains filtered or unexported methods -} -``` - -## type [HashFn]() - -HashFn is a function that returns the hash of 't'. - -```go -type HashFn[T any] func(t T) uint64 -``` - -## type [Integer]() - -Integer is a constraint that permits any integer type. If future releases of Go add new predeclared integer types, this constraint will be modified to include them. - -```go -type Integer interface { - // contains filtered or unexported methods -} -``` - -## type [Iterator]() - -Iterator is the interface for container's iterator. - -```go -type Iterator[T any] interface { - IsNotEnd() bool // Whether it is point to the end of the range. - MoveToNext() // Let it point to the next element. - Value() T // Return the value of current element. -} -``` - -## type [LessFn]() - -LessFn is a function that returns whether 'a' is less than 'b'. - -```go -type LessFn[T any] func(a, b T) bool -``` - -## type [Map]() - -Map is a associative container that contains key\-value pairs with unique keys. - -```go -type Map[K any, V any] interface { - Container - Has(K) bool // Checks whether the container contains element with specific key. - Find(K) *V // Finds element with specific key. - Insert(K, V) // Inserts a key-value pair in to the container or replace existing value. - Remove(K) bool // Remove element with specific key. - ForEach(func(K, V)) // Iterate the container. - ForEachIf(func(K, V) bool) // Iterate the container, stops when the callback returns false. - ForEachMutable(func(K, *V)) // Iterate the container, *V is mutable. - ForEachMutableIf(func(K, *V) bool) // Iterate the container, *V is mutable, stops when the callback returns false. -} -``` - -## type [MapIterator]() - -MapIterator is the interface for map's iterator. - -```go -type MapIterator[K any, V any] interface { - Key() K // The key of the element - // contains filtered or unexported methods -} -``` - -## type [Numeric]() - -Numeric is a constraint that permits any numeric type. - -```go -type Numeric interface { - // contains filtered or unexported methods -} -``` - -## type [Ordered]() - -Ordered is a constraint that permits any ordered type: any type that supports the operators \< \<= \>= \>. If future releases of Go add new ordered types, this constraint will be modified to include them. - -```go -type Ordered interface { - // contains filtered or unexported methods -} -``` - -## type [Queue]() - -Queue is a FIFO container - -```go -type Queue[T any] struct { - // contains filtered or unexported fields -} -``` - -### func [NewQueue]() - -```go -func NewQueue[T any]() *Queue[T] -``` - -NewQueue create a new Queue object. - -### func \(\*Queue\[T\]\) [Clear]() - ```go -func (q *Queue[T]) Clear() +import "github.com/chen3feng/stl4go" ``` -### func \(\*Queue\[T\]\) [IsEmpty]() +## 简介 -```go -func (q *Queue[T]) IsEmpty() bool -``` +本库是在 Go 1.18 开始支持范型后，尝试借鉴 C++ STL 实现的一个通用容器和算法库。（我个人完全无法接受没有范型的语言，因此直到 go 1.18 才开始尝试用它） -### func \(\*Queue\[T\]\) [Len]() +本库代码质量高，遵循了业界最新的最佳实践。测试覆盖率接近 💯%，✅，设置了 CI、 [gosec](https://securego.io/) 检查， +[![GoReport](https://goreportcard.com/badge/github.com/securego/gosec)](https://goreportcard.com/report/github.com/chen3feng/stl4go) 评分。 -```go -func (q *Queue[T]) Len() int -``` +## 主要功能 -### func \(\*Queue\[T\]\) [PopBack]() +众所周知，C++ 的 STL 包括容器、算法，并以迭代器关联两者。 -```go -func (q *Queue[T]) PopBack() (T, bool) -``` +受语言限制，在 Go 中无法也没有必要完全模仿 C++的接口，因此 C++ 用户可能会感觉似曾相识相识，有时候也会感觉更方便。 -### func \(\*Queue\[T\]\) [PopFront]() +### 容器 -```go -func (q *Queue[T]) PopFront() (T, bool) -``` +目前实现的容器有： -### func \(\*Queue\[T\]\) [PushBack]() +- [x] 集合 用 Go 自己的 map 封装了一个 `BuiltinSet` +- [x] 基于 slice 封装的向量 `Vector`。提供了中间插入删除、区间删除等功能，依然与 slice 兼容。 +- [x] 双链表 DList +- [x] [跳表（SkipList）](skiplist.md) 是一种有序的关联容器，可以填补 Go `map` 只支持无序的的空白。这是目前全 GitHub 最快的跳表，参见 [skiplist-survey](https://github.com/chen3feng/skiplist-survey)的性能比较 +- [x] 栈 Stack，基于 Slice 实现 +- [x] 队列 Queue 双向进出的队列，基于链表实现 -```go -func (q *Queue[T]) PushBack(val T) -``` +不同的容器支持的方法不同，下面是所有容器都支持的方法： -### func \(\*Queue\[T\]\) [PushFront]() +- IsEmpty() bool 返回容器是否为空 +- Len() int 返回容器中的元素个数 +- Clear() 清空容器 -```go -func (q *Queue[T]) PushFront(val T) -``` +### 迭代器 -### func \(\*Queue\[T\]\) [String]() +DList 和 SkipList 支持简单的迭代器。 ```go -func (q *Queue[T]) String() string + l := stl4go.NewDListOf(Range(1, 10000)...) + sum := 0 + for i := 0; i < b.N; i++ { + for it := l.Iterate(); it.IsNotEnd(); it.MoveToNext() { + sum += it.Value() + } + } ``` -## type [Set]() - -Set is a containers that store unique elements. +SkipList 还支持区间迭代： ```go -type Set[K any] interface { - Container - Has(K) bool // Checks whether the container contains element with specific key. - Insert(K) // Inserts a key-value pair in to the container or replace existing value. - InsertN(...K) // Inserts multiple key-value pairs in to the container or replace existing value. - Remove(K) bool // Remove element with specific key. - RemoveN(...K) // Remove multiple elements with specific keys. - ForEach(func(K)) // Iterate the container. - ForEachIf(func(K) bool) // Iterate the container, stops when the callback returns false. -} + l := stl4go.NewDListOf(Range(1, 1000)...) + it := sl.FindRange(120, 350) ``` -## type [Signed]() +对 `it` 迭代可以得到 120~349 之间的数。 -Signed is a constraint that permits any signed integer type. If future releases of Go add new predeclared signed integer types, this constraint will be modified to include them. +更多时候，使用容器提供的 `ForEach` 和 `ForEachIf` 更方便，往往性能也更好一些： ```go -type Signed interface { - // contains filtered or unexported methods +func TestSkipList_ForEach(t *testing.T) { + sl := newSkipListN(100) + a := []int{} + sl.ForEach(func(k int, v int) { + a = append(a, k) + }) + expectEq(t, len(a), 100) + expectTrue(t, IsSorted(a)) } ``` -## type [SkipList]() - -SkipList is a probabilistic data structure that seem likely to supplant balanced trees as the implementation method of choice for many applications. Skip list algorithms have the same asymptotic expected time bounds as balanced trees and are simpler, faster and use less space. - -See https://en.wikipedia.org/wiki/Skip_list for more details. + `ForEachIf` 用于遍历时候提前结束的场景： -```go -type SkipList[K any, V any] struct { - // contains filtered or unexported fields + ```go +func Test_DList_ForEachIf(t *testing.T) { + l := NewDListOf(1, 2, 3) + c := 0 + l.ForEachIf(func(n int) bool { + c = n + return n != 2 + }) + expectEq(t, c, 2) } -``` - -### func [NewSkipList]() - -```go -func NewSkipList[K Ordered, V any]() *SkipList[K, V] -``` - -NewSkipList creates a new SkipList for Ordered key type. - -### func [NewSkipListFromMap]() - -```go -func NewSkipListFromMap[K Ordered, V any](m map[K]V) *SkipList[K, V] -``` - -NewSkipListFromMap creates a new SkipList from a map. - -### func [NewSkipListFunc]() - -```go -func NewSkipListFunc[K any, V any](keyCmp CompareFn[K]) *SkipList[K, V] -``` - -NewSkipListFunc creates a new SkipList with specified compare function keyCmp. - -### func \(\*SkipList\[K, V\]\) [Clear]() - -```go -func (sl *SkipList[K, V]) Clear() -``` - -### func \(\*SkipList\[K, V\]\) [Find]() - -```go -func (sl *SkipList[K, V]) Find(key K) *V -``` - -Find returns the value associated with the passed key if the key is in the skiplist, otherwise returns nil. - -### func \(\*SkipList\[K, V\]\) [FindRange]() - -```go -func (sl *SkipList[K, V]) FindRange(first, last K) MapIterator[K, V] -``` - -FindRange returns an iterator in range \[first, last\) \(last is not includeed\). - -### func \(\*SkipList\[K, V\]\) [ForEach]() - -```go -func (sl *SkipList[K, V]) ForEach(op func(K, V)) -``` - -### func \(\*SkipList\[K, V\]\) [ForEachIf]() - -```go -func (sl *SkipList[K, V]) ForEachIf(op func(K, V) bool) -``` - -### func \(\*SkipList\[K, V\]\) [ForEachMutable]() - -```go -func (sl *SkipList[K, V]) ForEachMutable(op func(K, *V)) -``` - -### func \(\*SkipList\[K, V\]\) [ForEachMutableIf]() - -```go -func (sl *SkipList[K, V]) ForEachMutableIf(op func(K, *V) bool) -``` - -### func \(\*SkipList\[K, V\]\) [Has]() - -```go -func (sl *SkipList[K, V]) Has(key K) bool -``` - -### func \(\*SkipList\[K, V\]\) [Insert]() - -```go -func (sl *SkipList[K, V]) Insert(key K, value V) -``` - -Insert inserts a key\-value pair into the skiplist. If the key is already in the skip list, it's value will be updated. + ``` -### func \(\*SkipList\[K, V\]\) [IsEmpty]() +使用 `ForEachMutable` 或 `ForEachMutable` 可以在遍历时候修改元素的值： ```go -func (sl *SkipList[K, V]) IsEmpty() bool -``` - -### func \(\*SkipList\[K, V\]\) [Iterate]() - -```go -func (sl *SkipList[K, V]) Iterate() MapIterator[K, V] -``` - -### func \(\*SkipList\[K, V\]\) [Len]() - -```go -func (sl *SkipList[K, V]) Len() int -``` - -### func \(\*SkipList\[K, V\]\) [LowerBound]() - -```go -func (sl *SkipList[K, V]) LowerBound(key K) MapIterator[K, V] -``` - -### func \(\*SkipList\[K, V\]\) [Remove]() - -```go -func (sl *SkipList[K, V]) Remove(key K) bool -``` - -Remove removes the key\-value pair associated with the passed key and returns true if the key is in the skiplist, otherwise returns false. - -### func \(\*SkipList\[K, V\]\) [UpperBound]() - -```go -func (sl *SkipList[K, V]) UpperBound(key K) MapIterator[K, V] -``` - -## type [Stack]() - -Stack s is a container adaptor that provides the functionality of a stack, a LIFO \(last\-in, first\-out\) data structure. - -```go -type Stack[T any] struct { - // contains filtered or unexported fields +func TestSkipList_ForEachMutable(t *testing.T) { + sl := newSkipListN(100) + sl.ForEachMutable(func(k int, v *int) { + *v = -*v + }) + for i := 0; i < sl.Len(); i++ { + expectEq(t, *sl.Find(i), -i) + } } ``` -### func [NewStack]() +### 算法 -```go -func NewStack[T any]() *Stack[T] -``` +受语言功能限制，绝大部分算法只支持 Slice。算法的函数名以 `If`、`Func` 结尾的，表示可以传递一个自定义的比较函数。 -NewStack creates a new Stack object. +#### 生成型 -### func [NewStackCap]() +- Range 返回一个 [begin, end) 的整数构成的 Slice +- Generate 用给定的函数生成一个序列填充到 Slice 中 -```go -func NewStackCap[T any](capicity int) *Stack[T] -``` +#### 计算型 -NewStackCap creates a new Stack object with the specified capicity. +- Sum 求和 +- SumAs 求和并以另一种类型的结果返回（比如 `int64` 返回 `[]int32` 的和）。 +- Average 求平均值。 +- AverageAs 求平均值并以另一种类型的结果返回（比如 `float64` 返回 `[]int` 的和）。 +- Count 返回和指定值相当的个数 +- CountIf 返回让指定函数返回 `true` 的元素的个数 -### func \(\*Stack\[T\]\) [Cap]() +#### 比较 -```go -func (s *Stack[T]) Cap() int -``` +- Equal 判断两个序列是否相等 +- Compare 比较两个序列，按字典序返回 -1、0、1 分别表示起大小关系 -### func \(\*Stack\[T\]\) [Clear]() +#### 查找 -```go -func (s *Stack[T]) Clear() -``` +- Min, Max 求最大最小值 +- MinN、MaxN、MinMax 返回 slice 中的最大和最小值 +- Find 线性查找第一个指定的值，返回其下标 +- FindIf 线性查找指定函数返回 `true` 的值，返回其下标 +- AllOf、AnyOf、NoneOf 返回区间中是否全部、任何一个、没有一个元素能使传入的函数返回 `true` -### func \(\*Stack\[T\]\) [IsEmpty]() +#### 排序 -```go -func (s *Stack[T]) IsEmpty() bool -``` +- Sort 排序 +- DescSort 降序排序 +- StableSort 稳定排序 +- DescStableSort 降序稳定排序 +- IsSorted 是否是排序的 +- IsDescSorted 是否是降序排序的 -### func \(\*Stack\[T\]\) [Len]() +#### 二分查找 -```go -func (s *Stack[T]) Len() int -``` +参考 C++STL。 -### func \(\*Stack\[T\]\) [MustPop]() +- BinarySearch +- LowerBound +- UpperBound -```go -func (s *Stack[T]) MustPop() T -``` +### 接口设计和命名 -### func \(\*Stack\[T\]\) [Pop]() +较多地参考了 C++ STL。T 表示模板。是的，Go 的范型不是模板，但是谁让 C++ 那么影响力，而 STL 又那么有名呢。 -```go -func (s *Stack[T]) Pop() (val T, ok bool) -``` +很多库的设计采用小的代码仓库或者一个仓库中拆分成多个子包。 -### func \(\*Stack\[T\]\) [Push]() +比如 ```go -func (s *Stack[T]) Push(t T) -``` - -## type [Unsigned]() +import ( + "github.com/someone/awesomelib/skiplist" + "github.com/someone/awesomelib/binarysearch" +) -Unsigned is a constraint that permits any unsigned integer type. If future releases of Go add new predeclared unsigned integer types, this constraint will be modified to include them. - -```go -type Unsigned interface { - // contains filtered or unexported methods +func main() { + sl := skiplist.New() } ``` -## type [Vector]() - -Vector is a sequence container representing array that can change in size. - -```go -type Vector[T any] []T -``` - -### func [MakeVector]() - -```go -func MakeVector[T any]() Vector[T] -``` - -MakeVector creates an empty Vector object. - -### func [MakeVectorCap]() - -```go -func MakeVectorCap[T any](c int) Vector[T] -``` - -MakeVectorCap creates an empty Vector object with specified capacity. - -### func [MakeVectorOf]() - -```go -func MakeVectorOf[T any](v ...T) Vector[T] -``` - -MakeVectorOf creates an Vector object with initial values. - -### func \(\*Vector\[T\]\) [Append]() - -```go -func (v *Vector[T]) Append(x ...T) -``` - -Append appends the values x... to the tail of the vector. - -### func \(\*Vector\[T\]\) [At]() - -```go -func (v *Vector[T]) At(i int) T -``` - -### func \(\*Vector\[T\]\) [Cap]() - -```go -func (v *Vector[T]) Cap() int -``` - -### func \(\*Vector\[T\]\) [Clear]() - -```go -func (v *Vector[T]) Clear() -``` - -Clear erases all elements from the vector. After this call, Len\(\) returns zero. Leaves the Cap\(\) of the vector unchanged. - -### func \(\*Vector\[T\]\) [Insert]() - -```go -func (v *Vector[T]) Insert(i int, x ...T) -``` - -Insert inserts the values x... into the vector at index i. After the insertion, \(\*v\)\[i\] == x\[0\]. Insert panics if i is out of range. - -Complexity: O\(len\(s\) \+ len\(v\)\). - -### func \(\*Vector\[T\]\) [IsEmpty]() - -```go -func (v *Vector[T]) IsEmpty() bool -``` - -### func \(\*Vector\[T\]\) [Len]() - -```go -func (v *Vector[T]) Len() int -``` - -### func \(\*Vector\[T\]\) [PushBack]() - -```go -func (v *Vector[T]) PushBack(x T) -``` - -### func \(\*Vector\[T\]\) [Remove]() - -```go -func (v *Vector[T]) Remove(i int) -``` - -Remove removes 1 element in the vector. - -Complexity: O\(len\(s\) \- i\). - -### func \(\*Vector\[T\]\) [RemoveLength]() - -```go -func (v *Vector[T]) RemoveLength(i int, len int) -``` - -Remove removes the elements in the range\[i, i\+len\) from the vector. +这种写法看似优雅，但是由于好的名字大家都喜欢，在使用中又不得不引入 import 重命名，而不同的使用者别名不一样，增加代码读写的心智负担。 -### func \(\*Vector\[T\]\) [RemoveRange]() +我不太喜欢这种风格。 -```go -func (v *Vector[T]) RemoveRange(i, j int) -``` - -Remove removes the elements in the range\[i, j\) from the vector. - -### func \(\*Vector\[T\]\) [Reserve]() - -```go -func (v *Vector[T]) Reserve(l int) -``` - -Reserve increases the capacity of the vector \(the total number of elements that the vector can hold without requiring reallocation\)to a value that's greater or equal to l. If l is greater than the current Cap\(\), new storage is allocated, otherwise the function does nothing. +因此本库全部在 `stl4go` 包下，期望不会和别人的库重名。 -Reserve\(\) does not change the size of the vector. - -### func \(\*Vector\[T\]\) [Set]() - -```go -func (v *Vector[T]) Set(i int, x T) -``` - -### func \(\*Vector\[T\]\) [Shrink]() - -```go -func (v *Vector[T]) Shrink() -``` +### TODO -Shrink removes unused capacity from the vector. +参见 [Issue](https://github.com/chen3feng/stl4go/issues)。 +以及更详细的文档。 +## Go Doc -Generated by [gomarkdoc]() +点击查看[生成的文档](generated_doc.md). +## Reference - +- [C++ STL](https://en.wikipedia.org/wiki/Standard_Template_Library) +- [liyue201/gostl](https://github.com/liyue201/gostl) +- [zyedidia/generic](https://github.com/zyedidia/generic) +- [hlccd/goSTL](https://github.com/hlccd/goSTL) diff --git a/updatedoc.sh b/updatedoc.sh index a988f78..6f4649b 100755 --- a/updatedoc.sh +++ b/updatedoc.sh @@ -1,4 +1,3 @@ #!/bin/bash -gomarkdoc -o README.md -e . -gomarkdoc -o README_zh.md -e . +gomarkdoc -o generated_doc.md -e .