Update docs (#27)

chen3feng · Aug 2, 2022 · 54e2bb1 · 54e2bb1
1 parent cc3c55d
commit 54e2bb1
Show file tree

Hide file tree

Showing 2 changed files with 192 additions and 23 deletions.
diff --git a/README.md b/README.md
@@ -29,6 +29,8 @@ Package stl4go is a generic container and algorithm library for go.
 - [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 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>)
@@ -38,11 +40,14 @@ Package stl4go is a generic container and algorithm library for go.
 - [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>)
@@ -68,6 +73,8 @@ Package stl4go is a generic container and algorithm library for go.
 - [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 Container](<#type-container>)
 - [type DList](<#type-dlist>)
   - [func NewDList[T any]() *DList[T]](<#func-newdlist>)
@@ -144,7 +151,7 @@ Package stl4go is a generic container and algorithm library for go.
   - [func (v *Vector[T]) Shrink()](<#func-vectort-shrink>)
 
 
-## func [AllOf](<https://github.com/chen3feng/stl4go/blob/master/lookup.go#L115>)
+## func [AllOf](<https://github.com/chen3feng/stl4go/blob/master/lookup.go#L130>)
 
 ```go
 func AllOf[T any](a []T, pred func(T) bool) bool
@@ -154,7 +161,7 @@ AllOf return true if pred\(e\) returns true for all emements e in a.
 
 Complexity: O\(len\(a\)\).
 
-## func [AnyOf](<https://github.com/chen3feng/stl4go/blob/master/lookup.go#L127>)
+## func [AnyOf](<https://github.com/chen3feng/stl4go/blob/master/lookup.go#L142>)
 
 ```go
 func AnyOf[T any](a []T, pred func(T) bool) bool
@@ -172,6 +179,28 @@ func Average[T Numeric](a []T) T
 
 Average returns the average value of a.
 
+## func [BinarySearch](<https://github.com/chen3feng/stl4go/blob/master/binary_search.go#L100>)
+
+```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](<https://github.com/chen3feng/stl4go/blob/master/binary_search.go#L115>)
+
+```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](<https://github.com/chen3feng/stl4go/blob/master/compare.go#L26>)
 
 ```go
@@ -252,15 +281,27 @@ func Equals[T comparable](a, b T) bool
 
 Equals wraps the '==' operator for comparable types.
 
-## func [Find](<https://github.com/chen3feng/stl4go/blob/master/lookup.go#L89>)
+## func [Find](<https://github.com/chen3feng/stl4go/blob/master/lookup.go#L90>)
 
 ```go
 func Find[T comparable](a []T, x T) (index int, ok bool)
 ```
 
-Find find the value x in the given slice a linearly. return \(index, true\) if found, return \(\_, false\) if not found. Complexity: O\(len\(a\)\).
+Find find the first value x in the given slice a linearly. return \(index, true\) if found, return \(\_, false\) if not found.
 
-## func [Generate](<https://github.com/chen3feng/stl4go/blob/master/generate.go#L17>)
+Complexity: O\(len\(a\)\).
+
+## func [FindIf](<https://github.com/chen3feng/stl4go/blob/master/lookup.go#L104>)
+
+```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](<https://github.com/chen3feng/stl4go/blob/master/generate.go#L18>)
 
 ```go
 func Generate[T any](a []T, gen func() T)
@@ -270,7 +311,7 @@ Generate fill each element of \`a\`\` with \`gen\(\)\`.
 
 Complexity: O\(len\(a\)\).
 
-## func [Index](<https://github.com/chen3feng/stl4go/blob/master/lookup.go#L103>)
+## func [Index](<https://github.com/chen3feng/stl4go/blob/master/lookup.go#L118>)
 
 ```go
 func Index[T comparable](a []T, x T) int
@@ -310,6 +351,28 @@ func Less[T Ordered](a, b T) bool
 
 Less wraps the '\<' operator for ordered types.
 
+## func [LowerBound](<https://github.com/chen3feng/stl4go/blob/master/binary_search.go#L8>)
+
+```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](<https://github.com/chen3feng/stl4go/blob/master/binary_search.go#L32>)
+
+```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](<https://github.com/chen3feng/stl4go/blob/master/lookup.go#L6>)
 
 ```go
@@ -370,7 +433,7 @@ MinN return the minimum value in the sequence \`a\`.
 
 Complexity: O\(len\(a\)\).
 
-## func [NoneOf](<https://github.com/chen3feng/stl4go/blob/master/lookup.go#L139>)
+## func [NoneOf](<https://github.com/chen3feng/stl4go/blob/master/lookup.go#L154>)
 
 ```go
 func NoneOf[T any](a []T, pred func(T) bool) bool
@@ -380,13 +443,13 @@ NoneOf return true pred\(e\) returns true for none emements e in a.
 
 Complexity: O\(len\(a\)\).
 
-## func [Range](<https://github.com/chen3feng/stl4go/blob/master/generate.go#L6>)
+## func [Range](<https://github.com/chen3feng/stl4go/blob/master/generate.go#L7>)
 
 ```go
 func Range[T Numeric](first, last T) []T
 ```
 
-Range make a \[\]T filled with values in the \`\[first, last\)\` sequence.
+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\).
 
@@ -458,7 +521,7 @@ 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\)\), N=len\(a\).
+Complexity: O\(N\*log\(N\)\), where N=len\(a\).
 
 ## func [SortFunc](<https://github.com/chen3feng/stl4go/blob/master/sort.go#L98>)
 
@@ -478,7 +541,7 @@ 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\)\), N=len\(a\).
+Complexity: O\(N\*log\(N\)^2\), where N=len\(a\).
 
 ## func [StableSortFunc](<https://github.com/chen3feng/stl4go/blob/master/sort.go#L106>)
 
@@ -558,6 +621,28 @@ UniqueCopy remove adjacent repeated elements from the input slice. return the re
 
 Complexity: O\(len\(a\)\).
 
+## func [UpperBound](<https://github.com/chen3feng/stl4go/blob/master/binary_search.go#L54>)
+
+```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](<https://github.com/chen3feng/stl4go/blob/master/binary_search.go#L78>)
+
+```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 [Container](<https://github.com/chen3feng/stl4go/blob/master/container.go#L4-L8>)
 
 Container is a holder object that stores a collection of other objects.