Initial commit

Author: lispad

.gitignore

@@ -0,0 +1,2 @@
+.idea
+testdata/

.golangci.yml

@@ -0,0 +1,80 @@
+run:
+  concurrency: 4
+  timeout: 1m
+  issue-exit-code: 1
+  tests: false
+
+output:
+  format: colored-line-number # use 'golangci-lint run --out-format junit-xml' to have Jenkins-compatible results
+  print-issued-lines: true
+  print-linter-name: true
+  uniq-by-line: true
+  sort-results: true
+
+linters:
+  enable-all: false
+  presets:
+    - bugs
+    - comment
+    - error
+    - format
+    - import
+    - performance
+    - style
+    - metalinter
+  disable:
+    - scopelint  # deprecated
+    - interfacer # deprecated
+    - golint     # deprecated, 'style' preset uses Revive
+    - maligned   # deprecated, replaced with govet fieldalignment
+    - varnamelen
+    - wsl
+    - gomnd
+    - ireturn
+    - nlreturn
+
+linters-settings:
+  govet:
+    check-shadowing: true
+    enable:
+      - asmdecl
+      - assign
+      - atomic
+      - atomicalign
+      - bools
+      - buildtag
+      - cgocall
+      - composites
+      - copylocks
+      - deepequalerrors
+      - errorsas
+      - fieldalignment
+      - findcall
+      - framepointer
+      - httpresponse
+      - ifaceassert
+      - loopclosure
+      - lostcancel
+      - nilfunc
+      - nilness
+      - printf
+      - reflectvaluecompare
+      - shadow
+      - shift
+      - sigchanyzer
+      - sortslice
+      - stdmethods
+      - stringintconv
+      - structtag
+      - testinggoroutine
+      - tests
+      - unmarshal
+      - unreachable
+      - unsafeptr
+      - unusedresult
+      - unusedwrite
+  tagliatelle:
+    case:
+      rules:
+        json: snake
+        yaml: snake

LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 lispad.me
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,11 @@
+test: fuzz
+	go test -cover github.com/lispad/go-generics-tools/binheap
+
+fuzz:
+	go test -fuzz=FuzzEmptyMinHeap -fuzztime=10s github.com/lispad/go-generics-tools/binheap
+	go test -fuzz=FuzzEmptyMaxHeap -fuzztime=10s github.com/lispad/go-generics-tools/binheap
+	go test -fuzz=FuzzTopN$$ -fuzztime=10s github.com/lispad/go-generics-tools/binheap
+	go test -fuzz=FuzzTopNImmutable -fuzztime=10s github.com/lispad/go-generics-tools/binheap
+
+lint:
+	golangci-lint run binheap

README.md

@@ -0,0 +1,82 @@
+# Heap structure, using go generics
+
+Introduction
+------------
+
+The Heap package contains simple [binary heap](https://en.wikipedia.org/wiki/Binary_heap) implementation, using Golang
+generics. There are several heap implementations
+
+- generic Heap implementation, that could be used for `any` type,
+- `ComparableHeap` for [comparable](https://go.dev/ref/spec#Comparison_operators) types. Additional `Search`
+  and `Delete` are implemented,
+- for [`constraints.Ordered`](https://pkg.go.dev/golang.org/x/exp/constraints#Ordered) there are syntax sugar
+  constructors for min, max heaps;
+
+Also use-cases provided:
+
+- `TopN` that allows getting N top elements from slice.
+  `TopN` swaps top N elements to first N elements of slice, no additional allocations are done. All slice elements are
+  kept, only order is changed.
+- `TopNHeap` allows to get N top, pushing elements from stream without allocation slice for all elements. Only O(N)
+  memory is used.
+- `TopNImmutable` allocated new slice for heap, input slice is not mutated.
+
+Both TopN and TopNImmutable has methods for creating min and max tops for `constraints.Ordered`.
+
+Usage Example
+-----------------
+
+    package main
+    
+    import (
+        "fmt"
+
+        "github.com/lispad/go-generics-heap/binheap"
+    )
+    
+    func main() {
+        someData := []float64{1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0}
+        mins := binheap.MinN[float64](someData, 3)
+        fmt.Printf("--- top 3 min elements: %v\n", mins)
+        maxs := binheap.MaxN[float64](someData, 3)
+        fmt.Printf("--- top 3 max elements: %v\n\n", maxs)
+  
+        heap := binheap.EmptyMaxHeap[string]()
+        heap.Push("foo")
+        heap.Push("zzz")
+        heap.Push("bar")
+        heap.Push("baz")
+        heap.Push("foobar")
+        heap.Push("foobaz")
+        fmt.Printf("--- heap has %d elements, max element:\n%s\n\n", heap.Len(), heap.Peak())
+    }
+
+A bit more examples could be found in `examples` directory
+
+Benchmark
+-----------------
+Theoretical complexity for getting TopN from slice with size M, N <= M: O(N*ln(M)). When N << M, the heap-based TopN
+could be much faster than sorting slice and getting top. E.g. For top-3 from 10k elements approach is ln(10^5)/ln(3) ~=
+8.38 times faster.
+
+#### Benchmark
+
+    BenchmarkSortedMaxN-8      	10303648	   136.0 ns/op	   0 B/op	   0 allocs/op
+    BenchmarkMaxNImmutable-8   	398996316	   3.029 ns/op	   0 B/op	   0 allocs/op
+    BenchmarkMaxN-8            	804041455	   1.819 ns/op	   0 B/op	   0 allocs/op
+
+Compatibility
+-------------
+Minimal Golang version is 1.18. Generics and fuzz testing are used.
+
+Installation
+----------------------
+
+To install package, run:
+
+    go get github.com/lispad/go-generics-heap/binheap
+
+License
+-------
+
+The binheap package is licensed under the MIT license. Please see the LICENSE file for details.

binheap/generic.go

@@ -0,0 +1,119 @@
+// Package binheap provides implementation of binary heap for any type
+// with use of golang generics, and top-N heap usecases.
+package binheap
+
+// Heap provides basic methods: Push, Peak, Pop, Replace top element and PushPop.
+type Heap[T any] struct {
+	comparator func(x, y T) bool
+	data       []T
+}
+
+// EmptyHeap creates empty heap with provided comparator.
+func EmptyHeap[T any](comparator func(x, y T) bool) Heap[T] {
+	return Heap[T]{
+		comparator: comparator,
+	}
+}
+
+// FromSlice creates heap, based on provided slice.
+// Slice could be reordered.
+func FromSlice[T any](data []T, comparator func(x, y T) bool) Heap[T] {
+	h := Heap[T]{
+		data:       data,
+		comparator: comparator,
+	}
+	n := h.Len()
+	for i := n/2 - 1; i >= 0; i-- {
+		h.down(i, n)
+	}
+
+	return h
+}
+
+// Push inserts element to heap.
+func (h *Heap[T]) Push(x T) {
+	h.data = append(h.data, x)
+	h.up(h.Len() - 1)
+}
+
+// Len returns count of elements in heap.
+func (h *Heap[T]) Len() int {
+	return len(h.data)
+}
+
+// Peak returns top element without deleting.
+func (h *Heap[T]) Peak() T {
+	return h.data[0]
+}
+
+// Pop returns top element with removing it.
+func (h *Heap[T]) Pop() T {
+	n := h.Len() - 1
+	h.swap(0, n)
+	h.down(0, n)
+	result := h.data[n]
+	h.data = h.data[0:n]
+
+	return result
+}
+
+// PushPop pushes x to the heap and then pops top element.
+func (h *Heap[T]) PushPop(x T) T {
+	if h.Len() > 0 && h.comparator(h.data[0], x) {
+		x, h.data[0] = h.data[0], x
+		h.down(0, h.Len())
+	}
+
+	return x
+}
+
+// Replace extracts the root of the heap, and push a new item.
+func (h *Heap[T]) Replace(x T) (result T) {
+	result, h.data[0] = h.data[0], x
+	h.fix(0)
+	return
+}
+
+func (h *Heap[T]) fix(i int) (result T) {
+	if !h.down(i, h.Len()) {
+		h.up(i)
+	}
+
+	return result
+}
+
+func (h *Heap[T]) swap(i, j int) {
+	h.data[i], h.data[j] = h.data[j], h.data[i]
+}
+
+func (h *Heap[T]) up(j int) {
+	for {
+		i := (j - 1) / 2 // parent
+		if i == j || !h.comparator(h.data[j], h.data[i]) {
+			break
+		}
+		h.swap(i, j)
+		j = i
+	}
+}
+
+func (h *Heap[T]) down(i0, n int) bool {
+	i := i0
+	for {
+		j1 := 2*i + 1
+		if j1 >= n || j1 < 0 { // j1 < 0 after int overflow
+			break
+		}
+		j := j1 // left child
+		if j2 := j1 + 1; j2 < n && h.comparator(h.data[j2], h.data[j1]) {
+			j = j2 // = 2*i + 2  // right child
+		}
+		if !h.comparator(h.data[j], h.data[i]) {
+			break
+		}
+		h.swap(i, j)
+		i = j
+	}
+
+	return i > i0
+}

binheap/generic_test.go

@@ -0,0 +1,72 @@
+package binheap_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"github.com/lispad/go-generics-tools/binheap"
+)
+
+func TestEmptyHeap(t *testing.T) {
+	h := binheap.EmptyHeap[string](func(a, b string) bool { return len(a) > len(b) })
+	assert.Equal(t, 0, h.Len())
+	h.Push("1")
+	assert.Equal(t, 1, h.Len())
+	h.Push("22")
+	assert.Equal(t, 2, h.Len())
+	h.Push("4444")
+	assert.Equal(t, 3, h.Len())
+	h.Push("88888888")
+	assert.Equal(t, 4, h.Len())
+	h.Push("")
+	assert.Equal(t, 5, h.Len())
+	h.Push("55555")
+	assert.Equal(t, 6, h.Len())
+	h.Push("1")
+	assert.Equal(t, 7, h.Len())
+	h.Push("7777777")
+	assert.Equal(t, 8, h.Len())
+	h.Push("999999999")
+	assert.Equal(t, 9, h.Len())
+	h.Push("333")
+	assert.Equal(t, 10, h.Len())
+
+	assert.Equal(t, "999999999", h.Peak())
+	assert.Equal(t, 10, h.Len())
+	assert.Equal(t, "999999999", h.PushPop("4444")) // push less than max value, max will be returned
+	assert.Equal(t, 10, h.Len())
+	assert.Equal(t, "88888888", h.Peak())
+	assert.Equal(t, 10, h.Len())
+	assert.Equal(t, "0000000000", h.PushPop("0000000000")) // value will be returned, heap is unchanged
+	assert.Equal(t, 10, h.Len())
+	assert.Equal(t, "88888888", h.Peak())
+	assert.Equal(t, 10, h.Len())
+
+	assert.Equal(t, "88888888", h.Replace("22"))
+	assert.Equal(t, 10, h.Len())
+	assert.Equal(t, "7777777", h.Pop())
+	assert.Equal(t, 9, h.Len())
+	assert.Equal(t, "55555", h.Pop())
+	assert.Equal(t, 8, h.Len())
+	assert.Equal(t, "4444", h.Pop())
+	assert.Equal(t, 7, h.Len())
+	assert.Equal(t, "4444", h.Pop())
+	assert.Equal(t, 6, h.Len())
+	assert.Equal(t, "333", h.Pop())
+	assert.Equal(t, 5, h.Len())
+	h.Push("999999999")
+	assert.Equal(t, 6, h.Len())
+	assert.Equal(t, "999999999", h.Pop())
+	assert.Equal(t, 5, h.Len())
+	assert.Equal(t, "22", h.Pop())
+	assert.Equal(t, 4, h.Len())
+	assert.Equal(t, "22", h.Pop())
+	assert.Equal(t, 3, h.Len())
+	assert.Equal(t, "1", h.Pop())
+	assert.Equal(t, 2, h.Len())
+	assert.Equal(t, "1", h.Pop())
+	assert.Equal(t, 1, h.Len())
+	assert.Equal(t, "", h.Pop())
+	assert.Equal(t, 0, h.Len())
+}