[chore] Add annotations to SortedList[T]

typed/collections/sortedcontainers/sortedlist/functional.go

@@ -1,24 +1,29 @@
 package sortedlist
 
+// Reduce applies a function against an accumulator and each element in the list (from left to right) to reduce it to a single value.
 func (l SortedList[T]) Reduce(handler func(T, T) T, initial ...T) (T, error) {
 	return l.elements.Reduce(handler, initial...)
 }
 
+// ReduceRight applies a function against an accumulator and each element in the list (from right to left) to reduce it to a single value.
 func (l SortedList[T]) ReduceRight(handler func(T, T) T, initial ...T) (T, error) {
 	return l.elements.ReduceRight(handler, initial...)
 }
 
+// Filter creates a new list with all elements that pass the condition implemented by the provided function.
 func (l SortedList[T]) Filter(condition func(T) bool) SortedList[T] {
 	return SortedList[T]{
 		l.elements.Filter(condition),
 		l.cmp,
 	}
 }
 
+// Some checks if at least one element in the list passes the condition implemented by the provided function.
 func (l SortedList[T]) Some(condition func(T) bool) bool {
 	return l.elements.Some(condition)
 }
 
+// Every checks if all elements in the list pass the condition implemented by the provided function.
 func (l SortedList[T]) Every(condition func(T) bool) bool {
 	return l.elements.Every(condition)
 }

typed/collections/sortedcontainers/sortedlist/modify.go

@@ -5,10 +5,12 @@ import (
 	"slices"
 )
 
+// parseCount returns the count of elements to be parsed based on the length of the sorted list and the given counts.
 func (l SortedList[T]) parseCount(counts ...int) int {
 	return list.ParseCount(l.Len(), counts...)
 }
 
+// Remove removes the specified element from the sorted list, according to the given count, and returns the modified list.
 func (l *SortedList[T]) Remove(element T, counts ...int) *SortedList[T] {
 	count := l.parseCount(counts...)
 	index, exist := slices.BinarySearchFunc(l.elements, element, l.cmp)
@@ -28,22 +30,26 @@ func (l *SortedList[T]) Remove(element T, counts ...int) *SortedList[T] {
 	return l
 }
 
+// RemoveRange removes a range of elements from the sorted list and returns a new sorted list.
 func (l *SortedList[T]) RemoveRange(start, end int) SortedList[T] {
 	return SortedList[T]{
 		l.elements.Splice(start, end-start),
 		l.cmp,
 	}
 }
 
+// Clear removes all elements from the sorted list and returns the modified list.
 func (l *SortedList[T]) Clear() *SortedList[T] {
 	_ = l.elements.Clear()
 	return l
 }
 
+// Pop removes and returns the element at the specified indexes from the sorted list.
 func (l *SortedList[T]) Pop(indexes ...int) (element T, err error) {
 	return l.elements.Pop(indexes...)
 }
 
+// Insert inserts an element into the sorted list at the appropriate position and returns the modified list.
 func (l *SortedList[T]) Insert(element T) *SortedList[T] {
 	index, exist := slices.BinarySearchFunc(l.elements, element, l.cmp)
 	if exist {
@@ -55,6 +61,7 @@ func (l *SortedList[T]) Insert(element T) *SortedList[T] {
 	return l
 }
 
+// Reverse reverses the order of elements in the sorted list and returns the modified list.
 func (l *SortedList[T]) Reverse() *SortedList[T] {
 	_ = l.elements.Reverse()
 	l.cmp = func(a, b T) int {
@@ -63,13 +70,15 @@ func (l *SortedList[T]) Reverse() *SortedList[T] {
 	return l
 }
 
+// RemoveIf removes elements from the sorted list based on the specified condition and returns a new sorted list.
 func (l *SortedList[T]) RemoveIf(condition func(T) bool, counts ...int) SortedList[T] {
 	return SortedList[T]{
 		l.elements.RemoveIf(condition, counts...),
 		l.cmp,
 	}
 }
 
+// RemoveRightIf removes elements from the end of the sorted list based on the specified condition and returns a new sorted list.
 func (l *SortedList[T]) RemoveRightIf(condition func(T) bool, counts ...int) SortedList[T] {
 	return SortedList[T]{
 		l.elements.RemoveRightIf(condition, counts...),

typed/collections/sortedcontainers/sortedlist/search.go

@@ -5,6 +5,8 @@ import (
 	"slices"
 )
 
+// IndexOf returns the index of the first occurrence of the specified element in the sorted list,
+// or -1 if the element is not found.
 func (l SortedList[T]) IndexOf(element T) int {
 	index, exist := slices.BinarySearchFunc(l.elements, element, l.cmp)
 	if !exist {
@@ -16,6 +18,8 @@ func (l SortedList[T]) IndexOf(element T) int {
 	return index + 1
 }
 
+// LastIndexOf returns the index of the last occurrence of the specified element in the sorted list,
+// or -1 if the element is not found.
 func (l SortedList[T]) LastIndexOf(element T) int {
 	index, exist := slices.BinarySearchFunc(l.elements, element, l.cmp)
 	if !exist {
@@ -27,34 +31,42 @@ func (l SortedList[T]) LastIndexOf(element T) int {
 	return index - 1
 }
 
+// At returns the element at the specified index in the sorted list, or an error if the index is out of range.
 func (l SortedList[T]) At(index int) (T, error) {
 	return l.elements.At(index)
 }
 
+// Find returns the first element satisfying the given predicate function, along with a boolean indicating its existence.
 func (l SortedList[T]) Find(by func(T) bool) (T, bool) {
 	return l.elements.Find(by)
 }
 
+// FindIndex returns the index of the first element satisfying the given predicate function, or -1 if not found.
 func (l SortedList[T]) FindIndex(by func(T) bool) int {
 	return l.elements.FindIndex(by)
 }
 
+// FindLast returns the last element satisfying the given predicate function, along with a boolean indicating its existence.
 func (l SortedList[T]) FindLast(by func(T) bool) (T, bool) {
 	return l.elements.FindLast(by)
 }
 
+// FindLastIndex returns the index of the last element satisfying the given predicate function, or -1 if not found.
 func (l SortedList[T]) FindLastIndex(by func(T) bool) int {
 	return l.elements.FindLastIndex(by)
 }
 
+// Head returns the first element of the sorted list, or an error if the list is empty.
 func (l SortedList[T]) Head() (T, error) {
 	return l.elements.Head()
 }
 
+// Tail returns the last element of the sorted list, or an error if the list is empty.
 func (l SortedList[T]) Tail() (T, error) {
 	return l.elements.Tail()
 }
 
+// Max returns the maximum element in the sorted list, along with an error if the list is empty.
 func (l SortedList[T]) Max() (element T, err error) {
 	if l.Empty() {
 		err = common.ErrEmptyList
@@ -64,6 +76,7 @@ func (l SortedList[T]) Max() (element T, err error) {
 	return
 }
 
+// Min returns the minimum element in the sorted list, along with an error if the list is empty.
 func (l SortedList[T]) Min() (element T, err error) {
 	if l.Empty() {
 		err = common.ErrEmptyList

typed/collections/sortedcontainers/sortedlist/sortedlist.go

@@ -1,3 +1,4 @@
+// Package sortedlist provides a sorted list data structure.
 package sortedlist
 
 import (
@@ -6,31 +7,37 @@ import (
 	"slices"
 )
 
+// SortedList is a type representing a sorted list data structure.
 type SortedList[T any] struct {
 	elements arraylist.ArrayList[T]
 	cmp      func(a, b T) int
 }
 
+// AscendOrder is a comparison function that returns the result of comparing two elements in ascending order.
 func AscendOrder[T cmp.Ordered](a, b T) int {
 	return cmp.Compare(a, b)
 }
 
+// DescendOrder is a comparison function that returns the result of comparing two elements in descending order.
 func DescendOrder[T cmp.Ordered](a, b T) int {
 	return -cmp.Compare(a, b)
 }
 
-func NewSortedList[T any](cmp func(a, b T) int, elements ...T) *SortedList[T] {
+// NewSortedList creates and returns a new SortedList with the provided comparison function and initial elements.
+func NewSortedList[T any](f func(a, b T) int, elements ...T) *SortedList[T] {
 	arr := arraylist.Of(elements...)
-	if !slices.IsSortedFunc(arr, cmp) {
-		slices.SortFunc(arr, cmp)
+	if !slices.IsSortedFunc(arr, f) {
+		slices.SortFunc(arr, f)
 	}
-	return &SortedList[T]{arr, cmp}
+	return &SortedList[T]{arr, f}
 }
 
+// Len returns the number of elements in the sorted list.
 func (l SortedList[T]) Len() int {
 	return l.elements.Len()
 }
 
+// Count returns the number of occurrences of the specified element in the sorted list.
 func (l SortedList[T]) Count(element T) (count int) {
 	index, exist := slices.BinarySearchFunc(l.elements, element, l.cmp)
 	if !exist {
@@ -45,19 +52,23 @@ func (l SortedList[T]) Count(element T) (count int) {
 	return
 }
 
+// Includes checks if the specified element is present in the sorted list.
 func (l SortedList[T]) Includes(element T) bool {
 	_, exist := slices.BinarySearchFunc(l.elements, element, l.cmp)
 	return exist
 }
 
+// Empty returns true if the sorted list is empty, otherwise false.
 func (l SortedList[T]) Empty() bool {
 	return l.elements.Empty()
 }
 
+// Copy creates a copy of the sorted list and returns it.
 func (l SortedList[T]) Copy() SortedList[T] {
 	return SortedList[T]{l.elements.Copy(), l.cmp}
 }
 
+// Slice returns a new sorted list that is a subset of the original sorted list based on the provided slice parameters.
 func (l SortedList[T]) Slice(args ...int) SortedList[T] {
 	f := l.cmp
 	if len(args) >= 3 && args[2] < 0 {
@@ -68,20 +79,24 @@ func (l SortedList[T]) Slice(args ...int) SortedList[T] {
 	return SortedList[T]{l.elements.Slice(args...), f}
 }
 
+// ToReversed returns a new sorted list with the elements in reversed order.
 func (l SortedList[T]) ToReversed() SortedList[T] {
 	list := l.Copy()
 	_ = list.Reverse()
 	return list
 }
 
+// ToArray returns a copy of the elements in the sorted list as a regular slice.
 func (l SortedList[T]) ToArray() []T {
 	return l.elements.Copy()
 }
 
+// Equal compares the sorted list with another sorted list and returns true if they are equal, otherwise false.
 func (l SortedList[T]) Equal(another SortedList[T]) bool {
 	return l.elements.Equal(another.elements)
 }
 
+// ToList returns a copy of the sorted list's underlying arraylist.
 func (l SortedList[T]) ToList() arraylist.ArrayList[T] {
 	return l.elements.Copy()
 }