esort

Overview ¶

Package esort provides mechanisms for sorting user-defined types according to compound criteria extensibly. It is mutually compatible with package sort from the standard library. The package name comes from the combination of the words "extensible" and "sort" and shortened as "esort."

Consider a case of sorting a user-defined type of a Person:

type Person struct {
	GivenName string
	ID int
}

Suppose GivenName is to be sorted in descending order and ties of the GivenName by ID in ascending order:

sorter := esort.New().
	ByString(func(p Person) string { return p.GivenName }, esort.Desc).
	ByInt(func(p Person) int { return p.ID }, esort.Asc)

The data can then be sorted:

var data []Person

sort.Slice(data, func(i, j int) bool { return sorter.Less(data[i], data[j]) })

The same mechanism can be used directly with generics:

slices.SortFunc(data, sorter.Less)

Sorting Instructions ¶

The methods prefixed with By copy the current sorting rule set and add a new instruction to the copy. Each rule set is evaluated according to the order in which the instructions were added to the Sorter, so earlier sorting rules carry higher sorting weight than the previous.

A Sorter without rules is invalid and panics upon use.

Due to the copy on write semantics of the instructions API, rule sets can be templatized:

base := esort.New().
	ByString(func(p Person) string { return p.GivenName }, esort.Desc).

idAsc := base.ByInt(func(p Person) int { return p.ID }, esort.Asc)
idDesc := base.ByInt(func(p Person) int { return p.ID }, esort.Desc)

Efficiency ¶

Prefer using the simple, scalar By methods for comparing individual fields versus encoding their logic in the Sorter.ByFunc method. These individual methods are implemented efficiently.

Prefer:

sorter := esort.New().
	ByString(func(p Person) string { return p.GivenName }, esort.Desc).
	ByInt(func(p Person) int { return p.ID }, esort.Asc)

Over:

sorter := esort.New().
	ByFunc(func(l, r Person) bool {
		if l.GivenName != r.GivenName {
			return l.GivenName < r.GivenName
		}
	}, esort.Desc).
	ByInt(func(p Person) int { return p.ID }, esort.Asc)

Prefer defining the sorters as top-level variables if they have a static sorting basis. They will allocate zero memory during later program runtime — provided of course no user-defined functions registered with ByFunc do.

User-Defined Sorting Functions ¶

The ByFunc method enables types to be sorted by user-defined functions. The ByFunc method follows the same logic as the other instructions; it is appended to the rule set and evaluated accordingly.

If the function provided to ByFunc compares only one sorting basis, it may be implemented in a naive fashion whereby it only compares one side of the basis. Consider a data-transmission object (DTO)

func lessDTO(l, r *dto.SomeData) bool {
	return l.GetField() < r.GetField()
}

sorter := esort.New().
	ByFunc(lessDTO, esort.Asc)

The function lessDTO needn't consider the inverse case:

func lessDTO(l, r *dto.SomeData) bool {
	if l.GetField() < r.GetField() {
		return true
	}
	return r.GetField() < l.GetField()
}

The Sorter checks inverse cases automatically.

Ergonomics of Value Accessors ¶

The examples above are implemented using anonymous functions, similar to this:

func(p Person) string { return p.GivenName }

You are free to use free-standing, top-level functions:

func name(p Person) string { return p.GivenName }

sorter := esort.New().
	ByFunc(name, esort.Asc)

And method expressions on the types, though consider whether getters are even appropriate for the API first:

func (p Person) GivenName string { return p.givenName }

sorter := esort.New().
	ByFunc(p.GivenName, esort.Asc)

Performance ¶

A hand-implemented sort.Interface.Less function readily beats a Sorter. As implemented today, a Sorter with a simple double-compound sort criteria takes approximately 5-7x the time of a hand-written Less.