gollections

README

Gollections

This is a set of utilities aimed at reducing boilerplate code when using slices, maps and extending functionality by new collection implementations such as ordered map or set.

Supports Go version 1.20.

For example, you want to group some users by their role names converted to lowercase:

var users = []User{
    {name: "Bob", age: 26, roles: []Role{{"Admin"}, {"manager"}}},
    {name: "Alice", age: 35, roles: []Role{{"Manager"}}},
    {name: "Tom", age: 18},
}

You can make clear code, extensive, but without dependencies:

var namesByRole = map[string][]string{}
for _, u := range users {
    roles := u.Roles()
    if len(roles) == 0 {
        lr := ""
        names := namesByRole[lr]
        names = append(names, u.Name())
        namesByRole[lr] = names
    } else {
        for _, r := range roles {
            lr := strings.ToLower(r.Name())
            names := namesByRole[lr]
            names = append(names, u.Name())
            namesByRole[lr] = names
        }
    }
}

assert.Equal(t, namesByRole[""], []string{"Tom"})
assert.Equal(t, namesByRole["manager"], []string{"Bob", "Alice"})
assert.Equal(t, namesByRole["admin"], []string{"Bob"})

Or you can write more compact code using the collections API, like so:

var namesByRole = group.ByMultipleKeys(users, func(u User) []string {
    return convert.AndConvert(u.Roles(), Role.Name, strings.ToLower)
}, User.Name)

assert.Equal(t, namesByRole[""], []string{"Tom"})
assert.Equal(t, namesByRole["manager"], []string{"Bob", "Alice"})
assert.Equal(t, namesByRole["admin"], []string{"Bob"})

Installation

go get -u github.com/m4gshm/gollections

or

go get -u github.com/m4gshm/gollections@HEAD

Main packages

All packages consists of functions placed in the package and subpackages aimed to make short aliases of that functions. For example the function slice.SortByOrdered has aliases sort.By and sort.Of.

slice and map_

Contains utility functions of converting, filtering (searching), reducing, cloning elements of embedded slices and maps. The functions compute result in-place. For delayed computations see loops or collection functions.

even := func(i int) bool { return i%2 == 0 }
result := slice.Reduce(
    slice.Convert(
        slice.Filter(slice.Of(1, 2, 3, 4), even),
        strconv.Itoa,
    ),
    op.Sum[string],
)

assert.Equal(t, "24", result)

More examples here and here.

mutable and immutable collections

Provides implelentations of Vector, Set and Map.

Mutables support content appending, updating and deleting (the ordered map implementation is not supported delete operations).
Immutables are read-only datasets.

Detailed description of implementations below.

predicate and breakable break/predicate

Provides predicate builder api that used for filtering collection elements.

bob, _ := slice.First(users, where.Eq(User.Name, "Bob"))

assert.Equal(t, "Bob", bob.Name())

loop, kv/loop and breakable versions break/loop, break/kv/loop

Low level iteration api based on next function.

type (
    next[T any]      func() (element T, ok bool)
    kvNext[K, V any] func() (key K, value V, ok bool)
)

The function retrieves a next element from a dataset and returns ok==true if successful.
The API in most cases is similar to the slice API but with delayed computation which means that the methods don’t compute a result but only return a loop provider. The loop provider is type with a Next method that returns a next processed element.

even := func(i int) bool { return i%2 == 0 }
loopStream := loop.Convert(loop.Filter(loop.Of(1, 2, 3, 4), even).Next, strconv.Itoa)

assert.Equal(t, []string{"2", "4"}, loop.Slice(loopStream.Next))

Breakable loops additionaly have error returned value.

type (
    next[T any]      func() (element T, ok bool, err error)
    kvNext[K, V any] func() (key K, value V, ok bool, err error)
)

It is used for computations where an error may occur.

iter := loop.Conv(loop.Of("1", "2", "3", "ddd4", "5"), strconv.Atoi)
result, err := loop.Slice(iter.Next)

assert.Equal(t, []int{1, 2, 3}, result)
assert.ErrorContains(t, err, "invalid syntax")

Mutable collections

Supports write operations (append, delete, replace).

• Vector - the simplest based on built-in slice collection.

_ *mutable.Vector[int]   = vector.Of(1, 2, 3)
_ collection.Vector[int] = &mutable.Vector[int]{}

• Set - collection of unique items, prevents duplicates.

_ *mutable.Set[int]   = set.Of(1, 2, 3)
_ collection.Set[int] = &mutable.Set[int]{}

• Map - built-in map wrapper that supports stream functions.

_ *mutable.Map[int, string]   = map_.Of(k.V(1, "1"), k.V(2, "2"), k.V(3, "3"))
_ collection.Map[int, string] = mutable.NewMapOf(map[int]string{1: "2", 2: "2", 3: "3"})

• OrderedSet - collection of unique items, prevents duplicates, provides iteration in order of addition.

_ *ordered.Set[int]   = set.Of(1, 2, 3)
_ collection.Set[int] = &ordered.Set[int]{}

• OrderedMap - same as the Map, but supports iteration in the order in which elements are added.

_ *ordered.Map[int, string]   = map_.Of(k.V(1, "1"), k.V(2, "2"), k.V(3, "3"))
_ collection.Map[int, string] = ordered.NewMapOf(
    /*order  */ []int{3, 1, 2},
    /*uniques*/ map[int]string{1: "2", 2: "2", 3: "3"},
)

Immutable containers

The same underlying interfaces but for read-only use cases.

Collection functions

There are three groups of operations:

• Immediate - retrieves the result in place (Sort, Reduce, Track, TrackEach, For, ForEach)

• Intermediate - only defines a computation (Convert, Filter, Flatt, Group).

• Final - applies intermediates and retrieves a result (First, Slice, Reduce)

Intermediates should wrap one by one to make a lazy computation chain that can be applied to the latest final operation.

var groupedByLength = group.Of(set.Of(
    "seventh", "seventh", //duplicate
    "first", "second", "third", "fourth",
    "fifth", "sixth", "eighth",
    "ninth", "tenth", "one", "two", "three", "1",
    "second", //duplicate
), func(v string) int { return len(v) },
).FilterKey(
    more.Than(3),
).ConvertValue(
    func(v string) string { return v + "_" },
).Map()

assert.Equal(t, map[int][]string{
    5: {"first_", "third_", "fifth_", "sixth_", "ninth_", "tenth_", "three_"},
    6: {"second_", "fourth_", "eighth_"},
    7: {"seventh_"},
}, groupedByLength)