natural

README

natural

Yet another natural sort, with 100% test coverage and a benchmark. It does not allocate memory, doesn't depend on package sort and hence doesn't depend on reflect. It is optimized for speed.

Benchmarks

On Go 1.18.3.

$ go test -bench=. -cpu 1
goos: linux
goarch: amd64
pkg: github.com/maruel/natural
cpu: Intel(R) Core(TM) i7-10700 CPU @ 2.90GHz
BenchmarkLessDigitsTwoGroupsNative 331287298     3.597 ns/op   0 B/op   0 allocs/op
BenchmarkLessDigitsTwoGroups        32479050    36.55 ns/op    0 B/op   0 allocs/op
BenchmarkLessStringOnly            157775884     7.603 ns/op   0 B/op   0 allocs/op
BenchmarkLessDigitsOnly             69210796    17.52 ns/op    0 B/op   0 allocs/op
BenchmarkLess10Blocks                6331066   190.8 ns/op     0 B/op   0 allocs/op

On a Raspberry Pi 3:

$ go test -bench=. -cpu 1
goos: linux
goarch: arm
pkg: github.com/maruel/natural
BenchmarkLessDigitsTwoGroupsNative  14181789    86.57 ns/op    0 B/op   0 allocs/op
BenchmarkLessDigitsTwoGroups         1600195   748.9 ns/op     0 B/op   0 allocs/op
BenchmarkLessStringOnly              8286034   142.3 ns/op     0 B/op   0 allocs/op
BenchmarkLessDigitsOnly              3653055   331.4 ns/op     0 B/op   0 allocs/op
BenchmarkLess10Blocks                 310687  3838 ns/op       0 B/op   0 allocs/op

Coverage:

$ go test -cover
PASS
coverage: 100.0% of statements
ok     github.com/maruel/natural       0.012s

Documentation

Overview

Package natural defines a natural "less" to compare two strings while interpreting natural numbers.

This is occasionally nicknamed 'natsort'.

It does so with no memory allocation.

Example

package main

import (
	"fmt"
	"slices"
	"strings"

	"github.com/maruel/natural"
)

func main() {
	items := []string{
		"gpio10",
		"gpio1",
		"gpio20",
	}
	slices.SortFunc(items, natural.Compare)
	fmt.Println(strings.Join(items, "\n"))
}

Output:

gpio1
gpio10
gpio20

Index

• func Compare(a, b string) int
• func Less(a, b string) bool
• type StringSlice
  • func (p StringSlice) Len() int
  • func (p StringSlice) Less(i, j int) bool
  • func (p StringSlice) Swap(i, j int)

Examples

• Package
• Compare
• Less

Functions

func Compare

func Compare(a, b string) int

Compare does a 'natural' comparison on the two strings.

It treats digits as decimal numbers, so that Compare("10", "2") return >0.

This function does no memory allocation.

Example

package main

import (
	"fmt"
	"slices"
	"strings"

	"github.com/maruel/natural"
)

func main() {
	items := []string{
		"gpio10",
		"gpio1",
		"gpio20",
	}
	slices.SortFunc(items, natural.Compare)
	fmt.Println(strings.Join(items, "\n"))
}

Output:

gpio1
gpio10
gpio20

func Less

func Less(a, b string) bool

Less does a 'natural' comparison on the two strings.

It treats digits as decimal numbers, so that Less("10", "2") return false.

This function does no memory allocation.

Example

package main

import (
	"fmt"
	"sort"
	"strings"

	"github.com/maruel/natural"
)

func main() {
	// The old way to sort before Go 1.23. It is recommended to use the new slices standard package with Compare.
	items := []string{
		"gpio10",
		"gpio1",
		"gpio20",
	}
	sort.Sort(natural.StringSlice(items))
	fmt.Println(strings.Join(items, "\n"))
}

Output:

gpio1
gpio10
gpio20

Types

type StringSlice

type StringSlice []string

StringSlice attaches the methods of Interface to []string, sorting in increasing order using natural order.

It is now obsolete, use slices.Sort() along with natural.Compare instead.

func (StringSlice) Len

func (p StringSlice) Len() int

func (StringSlice) Less

func (p StringSlice) Less(i, j int) bool

func (StringSlice) Swap

func (p StringSlice) Swap(i, j int)