github.com/m4gshm/gollections@v0.0.13-0.20240331203319-a34a86e58a24/collection/api.go (about)

     1  // Package collection consists of common operations of Iterable based collections
     2  package collection
     3  
     4  import (
     5  	"golang.org/x/exp/constraints"
     6  
     7  	breakLoop "github.com/m4gshm/gollections/break/loop"
     8  	"github.com/m4gshm/gollections/comparer"
     9  	kvloop "github.com/m4gshm/gollections/kv/loop"
    10  	"github.com/m4gshm/gollections/loop"
    11  	loopconvert "github.com/m4gshm/gollections/loop/convert"
    12  	"github.com/m4gshm/gollections/op/check/not"
    13  )
    14  
    15  // Convert returns a loop that applies the 'converter' function to the collection elements
    16  func Convert[From, To any, IT Iterable[From]](collection IT, converter func(From) To) loop.Loop[To] {
    17  	b := collection.Loop()
    18  	return loop.Convert(b, converter)
    19  }
    20  
    21  // Conv returns a breakable loop that applies the 'converter' function to the collection elements
    22  func Conv[From, To any, IT Iterable[From]](collection IT, converter func(From) (To, error)) breakLoop.Loop[To] {
    23  	b := collection.Loop()
    24  	return loop.Conv(b, converter)
    25  }
    26  
    27  // FilterAndConvert returns a loop that filters source elements and converts them
    28  func FilterAndConvert[From, To any, IT Iterable[From]](collection IT, filter func(From) bool, converter func(From) To) loop.Loop[To] {
    29  	b := collection.Loop()
    30  	f := loop.FilterAndConvert(b, filter, converter)
    31  	return f
    32  }
    33  
    34  // Flat returns a loop that converts the collection elements into slices and then flattens them to one level
    35  func Flat[From, To any, IT Iterable[From]](collection IT, by func(From) []To) loop.Loop[To] {
    36  	b := collection.Loop()
    37  	f := loop.Flat(b, by)
    38  	return f
    39  }
    40  
    41  // Flatt returns a breakable loop that converts the collection elements into slices and then flattens them to one level
    42  func Flatt[From, To comparable, IT Iterable[From]](collection IT, flattener func(From) ([]To, error)) breakLoop.Loop[To] {
    43  	return loop.Flatt(collection.Loop(), flattener)
    44  }
    45  
    46  // FilterAndFlat filters source elements and extracts slices of 'To' by the 'flattener' function
    47  func FilterAndFlat[From, To any, IT Iterable[From]](collection IT, filter func(From) bool, flattener func(From) []To) loop.Loop[To] {
    48  	b := collection.Loop()
    49  	f := loop.FilterAndFlat(b, filter, flattener)
    50  	return f
    51  }
    52  
    53  // Filter instantiates a loop that checks elements by the 'filter' function and returns successful ones
    54  func Filter[T any, IT Iterable[T]](collection IT, filter func(T) bool) loop.Loop[T] {
    55  	b := collection.Loop()
    56  	f := loop.Filter(b, filter)
    57  	return f
    58  }
    59  
    60  // NotNil instantiates a loop that filters nullable elements
    61  func NotNil[T any, IT Iterable[*T]](collection IT) loop.Loop[*T] {
    62  	return Filter(collection, not.Nil[T])
    63  }
    64  
    65  // PtrVal creates a loop that transform pointers to the values referenced referenced by those pointers.
    66  // Nil pointers are transformet to zero values.
    67  func PtrVal[T any, IT Iterable[*T]](collection IT) loop.Loop[T] {
    68  	return loop.PtrVal(collection.Loop())
    69  }
    70  
    71  // NoNilPtrVal creates a loop that transform only not nil pointers to the values referenced referenced by those pointers.
    72  // Nil pointers are ignored.
    73  func NoNilPtrVal[T any, IT Iterable[*T]](collection IT) loop.Loop[T] {
    74  	return loop.NoNilPtrVal(collection.Loop())
    75  }
    76  
    77  // NilSafe creates a loop that filters not nil elements, converts that ones, filters not nils after converting and returns them
    78  func NilSafe[From, To any, IT Iterable[*From]](collection IT, converter func(*From) *To) loop.Loop[*To] {
    79  	h := collection.Loop()
    80  	return loopconvert.NilSafe(h, converter)
    81  }
    82  
    83  // KeyValue transforms iterable elements to key/value iterator based on applying key, value extractors to the elements
    84  func KeyValue[T any, K comparable, V any, IT Iterable[T]](collection IT, keyExtractor func(T) K, valExtractor func(T) V) kvloop.Loop[K, V] {
    85  	h := collection.Loop()
    86  	return loop.KeyValue(h, keyExtractor, valExtractor)
    87  }
    88  
    89  // First returns the first element that satisfies the condition of the 'predicate' function
    90  func First[T any, IT Iterable[T]](collection IT, predicate func(T) bool) (v T, ok bool) {
    91  	i := collection.Loop()
    92  	return loop.First(i, predicate)
    93  }
    94  
    95  // Firstt returns the first element that satisfies the condition of the 'predicate' function
    96  func Firstt[T any, IT Iterable[T]](collection IT, predicate func(T) (bool, error)) (v T, ok bool, err error) {
    97  	return loop.Firstt(collection.Loop(), predicate)
    98  }
    99  
   100  // Sort sorts the specified sortable collection that contains orderable elements
   101  func Sort[SC any, Cmp ~func(T, T) int, C interface {
   102  	Sort(Cmp) SC
   103  }, T any, O constraints.Ordered](collection C, order func(T) O) SC {
   104  	return collection.Sort(comparer.Of(order))
   105  }