Improve documentation and benchmarks

Create a slower benchmark. Rename the ones that are similar.

README.md

@@ -11,34 +11,33 @@ Reference](https://pkg.go.dev/badge/github.com/maruel/natural.svg)](https://pkg.
 
 ## Benchmarks
 
-On Go 1.10.1.
-
-On a Xeon:
+On Go 1.18.3.
 
 ```
-$ go test -bench=. -benchmem -cpu 1
+$ go test -bench=. -cpu 1
 goos: linux
 goarch: amd64
 pkg: github.com/maruel/natural
-BenchmarkNative                200000000       8.63 ns/op     0 B/op     0 allocs/op
-BenchmarkLessStringOnly        100000000       18.7 ns/op     0 B/op     0 allocs/op
-BenchmarkLessDigits             50000000       30.5 ns/op     0 B/op     0 allocs/op
-BenchmarkLessStringDigits       50000000       31.3 ns/op     0 B/op     0 allocs/op
-BenchmarkLessDigitsTwoGroups    20000000       64.4 ns/op     0 B/op     0 allocs/op
+cpu: Intel(R) Core(TM) i7-10700 CPU @ 2.90GHz
+BenchmarkLessDigitsTwoGroupsNative 329085624     3.628 ns/op   0 B/op   0 allocs/op
+BenchmarkLessDigitsTwoGroups        31792579    38.07 ns/op    0 B/op   0 allocs/op
+BenchmarkLessStringOnly            147547137     8.127 ns/op   0 B/op   0 allocs/op
+BenchmarkLessDigitsOnly             65866989    17.92 ns/op    0 B/op   0 allocs/op
+BenchmarkLess10Blocks                5997386   198.3 ns/op     0 B/op   0 allocs/op
 ```
 
 On a Raspberry Pi 3:
 
 ```
-$ go test -bench=. -benchmem -cpu 1
+$ go test -bench=. -cpu 1
 goos: linux
 goarch: arm
 pkg: github.com/maruel/natural
-BenchmarkNative                 10000000        148 ns/op     0 B/op      0 allocs/op
-BenchmarkLessStringOnly          5000000        312 ns/op     0 B/op      0 allocs/op
-BenchmarkLessDigits              2000000        656 ns/op     0 B/op      0 allocs/op
-BenchmarkLessStringDigits        2000000        679 ns/op     0 B/op      0 allocs/op
-BenchmarkLessDigitsTwoGroups     1000000       1480 ns/op     0 B/op      0 allocs/op
+BenchmarkLessDigitsTwoGroupsNative  13044535    85.86 ns/op    0 B/op   0 allocs/op
+BenchmarkLessDigitsTwoGroups         1576779   751.7 ns/op     0 B/op   0 allocs/op
+BenchmarkLessStringOnly              8470698   141.5 ns/op     0 B/op   0 allocs/op
+BenchmarkLessDigitsOnly              3674454   326.4 ns/op     0 B/op   0 allocs/op
+BenchmarkLess10Blocks                 314845  3821 ns/op       0 B/op   0 allocs/op
 ```
 
 Coverage:

natsort.go

@@ -4,6 +4,10 @@
 
 // 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.
 package natural
 
 import (
@@ -12,9 +16,9 @@ import (
 
 // Less does a 'natural' comparison on the two strings.
 //
-// This is occasionally nicknamed 'natsort'.
+// It treats digits as decimal numbers, so that Less("10", "2") return true.
 //
-// It treats decimal numbers as value, so that Less("10", "2") return true.
+// This function does no memory allocation.
 func Less(a, b string) bool {
 	for {
 		if a == b {

natsort_test.go

@@ -54,7 +54,11 @@ func TestLessNot(t *testing.T) {
 	}
 }
 
-func BenchmarkNative(b *testing.B) {
+// BenchmarkLessDigitsTwoGroupsNative benchmarks calling a function that just
+// does a < b without taking into account the digits, using the same string as
+// BenchmarkLessDigitsTwoGroups.
+func BenchmarkLessDigitsTwoGroupsNative(b *testing.B) {
+	b.ReportAllocs()
 	for i := 0; i < b.N; i++ {
 		if less("a01a2", "a01a01") {
 			b.Fatal("unexpected result")
@@ -67,33 +71,41 @@ func less(a, b string) bool {
 	return a < b
 }
 
-func BenchmarkLessStringOnly(b *testing.B) {
+// BenchmarkLessDigitsTwoGroups compares "a01a2" and "a01a01".
+func BenchmarkLessDigitsTwoGroups(b *testing.B) {
+	b.ReportAllocs()
 	for i := 0; i < b.N; i++ {
-		if Less("abcd", "abc") {
+		if Less("a01a2", "a01a01") {
 			b.Fatal("unexpected result")
 		}
 	}
 }
 
-func BenchmarkLessDigits(b *testing.B) {
+// BenchmarkLessStringOnly doesn't contain digits.
+func BenchmarkLessStringOnly(b *testing.B) {
+	b.ReportAllocs()
 	for i := 0; i < b.N; i++ {
-		if Less("10", "2") {
+		if Less("abcd", "abc") {
 			b.Fatal("unexpected result")
 		}
 	}
 }
 
-func BenchmarkLessStringDigits(b *testing.B) {
+// BenchmarkLessDigitsOnly contains only digits.
+func BenchmarkLessDigitsOnly(b *testing.B) {
+	b.ReportAllocs()
 	for i := 0; i < b.N; i++ {
-		if Less("a10", "a2") {
+		if Less("10", "2") {
 			b.Fatal("unexpected result")
 		}
 	}
 }
 
-func BenchmarkLessDigitsTwoGroups(b *testing.B) {
+// BenchmarkLess10Blocks benchmark a mix of 10 strings and digits.
+func BenchmarkLess10Blocks(b *testing.B) {
+	b.ReportAllocs()
 	for i := 0; i < b.N; i++ {
-		if Less("a01a2", "a01a01") {
+		if Less("a01a01a01a01a01a01a01a01a01a2", "a01a01a01a01a01a01a01a01a01a01") {
 			b.Fatal("unexpected result")
 		}
 	}