README.md

🍕 github.com/elliotchance/pie

Enjoy a slice! pie is a code generator for dealing with slices that focuses on type safety, performance and immutability.

• Quick Start
  • Built-in Types
  • Custom Types And Structs
  • Limiting Functions Generated
• Functions
• FAQ
  • What are the requirements?
  • What are the goals of pie?
  • Can I contribute?
  • Why is the emoji a slice of pizza instead of a pie?

Quick Start

Install/update:

go get -u github.com/elliotchance/pie

Built-in Types

pie ships with some slice types ready to go (pun intended). These include:

• typeStrings[]string
• typeFloat64s[]float64
• typeInts[]int

These can be used without needing go generate. For example:

package main

import (
    "github.com/elliotchance/pie/pie"
    "fmt"
)

func main() {
    name := pie.Strings{"Bob", "Sally", "John", "Jane"}.
        Unselect(func (name string) {
            return strings.HasPrefix(name, "J")
        }).
        Transform(strings.ToUpper).
        Last()

    fmt.Println(name) // "SALLY"
}

Custom Types And Structs

Annotate the slice type in your source code:

type Car struct {
    Name, Color string
}

//go:generate pie Cars
type Cars []Car

Run go generate. This will create a file called cars_pie.go. You should commit this with the rest of your code. Run go generate any time you need to add more types.

Now you can use the slices:

cars := Cars{
    {"Bob", "blue"},
    {"Sally", "green"},
    {"John", "red"},
    {"Jane", "red"},
}

redCars := cars.Select(func(car Car) bool {
    return car.Color == "red"
})

// redCars = Cars{{"John", "red"}, {"Jane", "red"}}

Or, more complex operations can be chained:

cars.Unselect(func (car Car) {
        return strings.HasPrefix(car.Name, "J")
    }).
    Transform(func (car Car) Car {
        car.Name = strings.ToUpper(car.Name)
        
        return car
    }).
    Last()

// Car{"SALLY", "green"}

Limiting Functions Generated

By default all functions will be generated. This is easy to get going but creates a lot of unused code. You can limit the functions generated by chaining the function names with a dot syntax, like:

//go:generate myInts.Average.Sum myStrings.Select

This will only generate myInts.Average, myInts.Sum and myStrings.Select.

Functions

Function	String	Number	Struct	Big-O	Description
Append	✓	✓	✓	n	A new slice with the elements appended to the end.
AreSorted	✓	✓		n	Check if the slice is already sorted.
AreUnique	✓	✓		n	Check if the slice contains only unique elements.
Average		✓		n	The average (mean) value, or a zeroed value.
Contains	✓	✓	✓	n	Check if the value exists in the slice.
Extend	✓	✓	✓	n	A new slice with the elements from each slice appended to the end.
First	✓	✓	✓	1	The first element, or a zeroed value.
FirstOr	✓	✓	✓	1	The first element, or a default value.
Join	✓			n	A string from joining each of the elements.
JSONString	✓	✓	✓	n	The JSON encoded string.
Last	✓	✓	✓	1	The last element, or a zeroed value.
LastOr	✓	✓	✓	1	The last element, or a default value.
Len	✓	✓	✓	1	Number of elements.
Max	✓	✓		n	The maximum value, or a zeroes value.
Min	✓	✓		n	The minimum value, or a zeroed value.
Reverse	✓	✓	✓	n	Reverse elements.
Select	✓	✓	✓	n	A new slice containing only the elements that returned true from the condition.
Sort	✓	✓		n⋅log(n)	Return a new sorted slice.
Sum		✓		n	Sum (total) of all elements.
ToStrings	✓	✓	✓	n	Transforms each element to a string.
Transform	✓	✓	✓	n	A new slice where each element has been transformed.
Unique	✓	✓		n⋅log(n)	Return a new slice with only unique elements.
Unselect	✓	✓	✓	n	A new slice containing only the elements that returned false from the condition.

FAQ

What are the requirements?

pie supports many Go versions, all the way back to Go 1.8.

What are the goals of pie?

1. Type safety. I never want to hit runtime bugs because I could pass in the wrong type, or perform an invalid type case out the other end.

2. Performance. The functions need to be as fast as native Go implementations otherwise there's no point in this library existing.

3. Nil-safe. All of the functions will happily accept nil and treat them as empty slices. Apart from less possible panics, it makes it easier to chain.

4. Immutable. Functions never modify inputs, unlike some built-ins such as sort.Strings.

Can I contribute?

Absolutely. Pull requests are always welcome. Your PR must include:

1. Unit tests.
2. Update the README to list the new functions.

Why is the emoji a slice of pizza instead of a pie?

I wanted to pick a name for the project that was short and had an associated emoji. I liked pie, but then I found out that the pie emoji is not fully supported everywhere. I didn't want to change the name of the project to cake, but pizza pie still made sense. I'm not sure if I will change it back to a pie later.