gen

README

gen The Generic General Use Go Functions Library

gen is a generic general use Go functions library with the intention of replacing duplicated code where the same functionality is needed across multiple types, and provides a common interface for the functionality.

The library is designed to be used in a wide variety of projects and is designed to be easy to use.

Installation

go get -u go.structs.dev/gen@latest

Import

It is recommended that you use a . import for this library so that the library functions are available in the current namespace without the gen prefix.

Example:

import . "go.structs.dev/gen"

func main() {
    // ...

    m := Map[string, string]{
        "foo": "bar",
        "bar": "baz",
    }

    // Get a slice of map keys
    keys := m.Keys()

    // ...

    slice1 := []string{"foo", "bar"}
    slice2 := []string{"floob", "bar"}

    // Call the Unique method without the `gen` prefix.
    unique := Unique(slice1, slice2)

    existingmap := map[string]int{
        "foo": 1223,
        "bar": 111,
    }

    // Cast to the generic Map
    m := Map[string, int](existingmap)

    keys = m.Keys()
    values := m.Values()

    // ...

    existingSlice := []string{"foo", "bar", "baz"}

    // Cast to the generic Slice
    s := Slice[string](existingSlice)

    // Convert slice to map

    m := s.Map()
}

Benchmarks

To execute the benchmarks, run the following command:

go test -bench=. ./...

To view benchmarks over time for the main branch of the repository they can be seen on our Benchmark Report Card.

Documentation

Overview

Package gen is a generic general use Go functions library which can be used throughout any project.

As a rule the methods in this package are non-destructive and return a new value rather than modifying the original.

To import this package it is recommended that you use a `.` import like so:

import . "go.structs.dev/gen"

This allows for methods in `gen` to be used directly within the same namespace without needing to prefix them with `gen.`

Index

• func As[T any](in ...T) []T
• func Close[U channel[T], T any](in ...U)
• func Compare[T comparable](a, b []T) error
• func Diff[T comparable](a, b []T) []T
• func Equal[T comparable](a, b []T) bool
• func Exclude[T comparable](a []T, b ...T) []T
• func Has[T comparable](in []T, v T) bool
• func Index[T comparable](in []T, v T) int
• func Indices[T comparable](in []T, v T) []int
• func Intersect[T comparable](a, b []T) []T
• func Match[T comparable](a, b []T) bool
• func ReadOnly[U chan T, T any](in ...U) []<-chan T
• func Unique[U ~[]T, T comparable](in U) []T
• func WriteOnly[U chan T, T any](in ...U) []chan<- T
• type ErrIndexMismatch
  • func (e ErrIndexMismatch[T]) Error() string
• type ErrLengthMismatch
  • func (e ErrLengthMismatch) Error() string
• type FMap
  • func (m FMap[K, V]) Flip() FMap[V, K]
• type Map
  • func (m Map[K, V]) Keys() []K
  • func (m Map[K, V]) Values() []V
• type Slice
  • func (s Slice[T]) Chan(ctx context.Context) <-chan T
  • func (s Slice[T]) Map() Map[T, any]

Functions

func As

func As[T any](in ...T) []T

As allows you to cast N values passed in through a variadic argument to a slice of N values. This is useful for casting disparate struct types to slices of implemented interfaces

Example: As[io.Reader](&bytes.Buffer{}, &bufio.Reader{})

func Close

func Close[U channel[T], T any](in ...U)

Close closes all channels in the input slice

NOTE: If a channel is already closed any panic will be ignored and the channel will be skipped

func Compare

func Compare[T comparable](a, b []T) error

Compare returns nil if the two input slices are equal otherwise it returns an error indicating the issue

func Diff

func Diff[T comparable](a, b []T) []T

Diff returns the symmetric difference between the two input slices

func Equal

func Equal[T comparable](a, b []T) bool

Equal returns true if the two input slices are exactly equal

func Exclude

func Exclude[T comparable](a []T, b ...T) []T

Exclude returns a slice of values from the input slice minus the values supplied in the second argument

func Has

func Has[T comparable](in []T, v T) bool

Has determines if the input slice contains the input value

func Index

func Index[T comparable](in []T, v T) int

Index returns the index of the first occurrence of the input value

func Indices

func Indices[T comparable](in []T, v T) []int

Indices returns a slice of indices for all occurrences of value `v`

func Intersect

func Intersect[T comparable](a, b []T) []T

Intersect returns the intersection between the two input slices

func Match

func Match[T comparable](a, b []T) bool

Match returns true if the two input slices contain equivalent values NOTE: Match ignores ordering

func ReadOnly

func ReadOnly[U chan T, T any](in ...U) []<-chan T

ReadOnly accepts a slice of channels and returns a slice of channels that are read-only.

func Unique

func Unique[U ~[]T, T comparable](in U) []T

Unique returns a slice of unique values from the input slice

func WriteOnly

func WriteOnly[U chan T, T any](in ...U) []chan<- T

WriteOnly accepts a slice of channels and returns a slice of channels that are write-only.

Types

type ErrIndexMismatch

type ErrIndexMismatch[T any] struct {
	I        int
	Expected T
	Actual   T
}

func (ErrIndexMismatch[T]) Error

func (e ErrIndexMismatch[T]) Error() string

type ErrLengthMismatch

type ErrLengthMismatch struct {
	Expected int
	Actual   int
}

func (ErrLengthMismatch) Error

func (e ErrLengthMismatch) Error() string

type FMap

type FMap[K, V comparable] Map[K, V]

FMap is a flippale map where the key and value can be swapped

func (FMap[K, V]) Flip

func (m FMap[K, V]) Flip() FMap[V, K]

Flip returns a new FMap with the key and value swapped

type Map

type Map[K comparable, V any] map[K]V

Map wraps the Go map type in a generic which provides helper functions for accessing slices of keys or values without repeating the the implementation for each type

func (Map[K, V]) Keys

func (m Map[K, V]) Keys() []K

Keys returns a slice of keys from the map

func (Map[K, V]) Values

func (m Map[K, V]) Values() []V

Values returns a slice of values from the map

type Slice

type Slice[T comparable] []T

Slice wraps a slice of values with helper functions

func (Slice[T]) Chan

func (s Slice[T]) Chan(ctx context.Context) <-chan T

Chan converts the slice to a channel of type T

NOTE: This function does NOT use a buffered channel.

func (Slice[T]) Map

func (s Slice[T]) Map() Map[T, any]

Map returns a map of the given slice where the values of the slice are the Map keys