feat: update documentation

Author: joetifa2003

README.md

@@ -47,7 +47,8 @@ type BatchAllocator struct {
 
 type BatchAllocatorOption func(alloc *BatchAllocator)
 
-// Option to specify bucket size when creating BatchAllocator
+// WithBucketSize Option to specify bucket size when creating BatchAllocator
+// You can allocate more memory than the bucketsize in one allocation, it will allocate a new bucket and put the data in it.
 func WithBucketSize(size int) BatchAllocatorOption {
 	return func(alloc *BatchAllocator) {
 		alloc.bucketSize = size

batchallocator/batch.go

@@ -50,7 +50,7 @@ func Example_arena() {
 func ExampleWithBucketSize() {
 	alloc := batchallocator.New(
 		allocator.NewC(),
-		batchallocator.WithBucketSize(mm.SizeOf[int]()*15), // configure the allocator to allocate size of 15 ints in one go.
+		batchallocator.WithBucketSize(mm.SizeOf[int]()*15), // configure the allocator to allocate size of 15 ints per bucket.
 	)
 	defer alloc.Destroy()
 

batchallocator/example_test.go

@@ -0,0 +1,34 @@
+package hashmap
+
+import (
+	"fmt"
+
+	"github.com/joetifa2003/mm-go/allocator"
+	"github.com/joetifa2003/mm-go/batchallocator"
+)
+
+func Example() {
+	alloc := batchallocator.New(allocator.NewC())
+	defer alloc.Destroy()
+
+	hm := New[int, int](alloc)
+	defer hm.Free() // can be removed
+
+	hm.Set(1, 10)
+	hm.Set(2, 20)
+	hm.Set(3, 30)
+
+	sumKeys := 0
+	sumValues := 0
+	for k, v := range hm.Iter() {
+		sumKeys += k
+		sumValues += v
+	}
+
+	fmt.Println(sumKeys)
+	fmt.Println(sumValues)
+
+	// Output:
+	// 6
+	// 60
+}

hashmap/example_test.go

@@ -47,14 +47,14 @@ func (hm *Hashmap[K, V]) extend() {
 		}
 
 		for _, p := range pairs.Iter() {
-			hm.Insert(p.key, p.value)
+			hm.Set(p.key, p.value)
 		}
 	}
 }
 
-// Insert inserts a new value V if key K doesn't exist,
+// Set inserts a new value V if key K doesn't exist,
 // Otherwise update the key K with value V
-func (hm *Hashmap[K, V]) Insert(key K, value V) {
+func (hm *Hashmap[K, V]) Set(key K, value V) {
 	if ptr, exists := hm.GetPtr(key); exists {
 		*ptr = value
 		return

hashmap/hashmap.go

@@ -29,10 +29,9 @@ func BenchmarkHashmapCAlloc(b *testing.B) {
 		h := hashmap.New[int, int](alloc)
 
 		for i := 0; i < TIMES; i++ {
-			h.Insert(i, i)
+			h.Set(i, i)
 		}
 
-		runtime.GC()
 		h.Free()
 		alloc.Destroy()
 	}
@@ -44,10 +43,9 @@ func BenchmarkHashmapBatchAlloc(b *testing.B) {
 		h := hashmap.New[int, int](alloc)
 
 		for i := 0; i < TIMES; i++ {
-			h.Insert(i, i)
+			h.Set(i, i)
 		}
 
-		runtime.GC()
 		h.Free()
 		alloc.Destroy()
 	}

hashmap/hashmap_test.go

@@ -0,0 +1,33 @@
+package linkedlist
+
+import (
+	"fmt"
+
+	"github.com/joetifa2003/mm-go/allocator"
+)
+
+func Example() {
+	alloc := allocator.NewC()
+	defer alloc.Destroy()
+
+	ll := New[int](alloc)
+	defer ll.Free()
+
+	ll.PushBack(1)
+	ll.PushBack(2)
+	ll.PushBack(3)
+	ll.PushBack(4)
+
+	fmt.Println("PopBack:", ll.PopBack())
+	fmt.Println("PopFront:", ll.PopFront())
+
+	for _, i := range ll.Iter() {
+		fmt.Println(i)
+	}
+
+	// Output:
+	// PopBack: 4
+	// PopFront: 1
+	// 2
+	// 3
+}

linkedlist/example_test.go

@@ -0,0 +1,56 @@
+package minheap_test
+
+import (
+	"fmt"
+
+	"github.com/joetifa2003/mm-go/allocator"
+	"github.com/joetifa2003/mm-go/minheap"
+)
+
+func int_less(a, b int) bool { return a < b }
+
+func Example() {
+	alloc := allocator.NewC()
+	defer alloc.Destroy()
+
+	h := minheap.New[int](alloc, int_less)
+
+	// Push some values onto the heap
+	h.Push(2)
+	h.Push(1)
+	h.Push(4)
+	h.Push(3)
+	h.Push(5)
+
+	// Pop the minimum value from the heap
+	fmt.Println(h.Pop())
+	fmt.Println(h.Pop())
+
+	// Output:
+	// 1
+	// 2
+}
+
+func int_greater(a, b int) bool { return a > b }
+
+func Example_MaxHeap() {
+	alloc := allocator.NewC()
+	defer alloc.Destroy()
+
+	h := minheap.New[int](alloc, int_greater)
+
+	// Push some values onto the heap
+	h.Push(2)
+	h.Push(1)
+	h.Push(4)
+	h.Push(3)
+	h.Push(5)
+
+	// Pop the max value from the heap
+	fmt.Println(h.Pop())
+	fmt.Println(h.Pop())
+
+	// Output:
+	// 5
+	// 4
+}

minheap/example_test.go

@@ -59,6 +59,7 @@ func (h *MinHeap[T]) Free() {
 	allocator.Free(h.alloc, h)
 }
 
+// Remove the first element that makes f return true
 func (h *MinHeap[T]) Remove(f func(T) bool) {
 	for i := 0; i < h.data.Len(); i++ {
 		if f(h.data.UnsafeAt(i)) {
@@ -120,6 +121,7 @@ func (h *MinHeap[T]) removeAt(index int) {
 	}
 }
 
+// Iter returns an iterator over the elements of the heap.
 func (h *MinHeap[T]) Iter() iter.Seq2[int, T] {
 	return h.data.Iter()
 }

minheap/minheap.go

@@ -5,8 +5,8 @@ import (
 
 	"github.com/joetifa2003/mm-go/allocator"
 	"github.com/joetifa2003/mm-go/batchallocator"
-	"github.com/joetifa2003/mm-go/hashmap"
 	"github.com/joetifa2003/mm-go/mmstring"
+	"github.com/joetifa2003/mm-go/vector"
 )
 
 func Example() {
@@ -30,19 +30,19 @@ func Example() {
 	// Foo Bar
 }
 
-func Example_complex() {
+func Example_datastructures() {
 	alloc := batchallocator.New(allocator.NewC())
 	defer alloc.Destroy() // all the memory allocated bellow will be freed, no need to free it manually.
 
-	m := hashmap.New[*mmstring.MMString, *mmstring.MMString](alloc)
-	m.Insert(mmstring.From(alloc, "hello"), mmstring.From(alloc, "world"))
-	m.Insert(mmstring.From(alloc, "foo"), mmstring.From(alloc, "bar"))
+	m := vector.New[*mmstring.MMString](alloc)
+	m.Push(mmstring.From(alloc, "hello"))
+	m.Push(mmstring.From(alloc, "world"))
 
 	for k, v := range m.Iter() {
-		fmt.Println(k.GetGoString(), v.GetGoString())
+		fmt.Println(k, v.GetGoString())
 	}
 
 	// Output:
-	// hello world
-	// foo bar
+	// 0 hello
+	// 1 world
 }

mmstring/example_test.go

@@ -0,0 +1,51 @@
+package typedarena_test
+
+import (
+	"fmt"
+
+	"github.com/joetifa2003/mm-go/allocator"
+	"github.com/joetifa2003/mm-go/typedarena"
+)
+
+type Entity struct {
+	VelocityX float32
+	VelocityY float32
+	PositionX float32
+	PositionY float32
+}
+
+func Example() {
+	alloc := allocator.NewC()
+	defer alloc.Destroy()
+
+	arena := typedarena.New[Entity](
+		alloc,
+		10,
+	)
+	defer arena.Free() // frees all memory
+
+	for i := 0; i < 10; i++ {
+		e := arena.Alloc() // *Entity
+		e.VelocityX = float32(i)
+		e.VelocityY = float32(i)
+		e.PositionX = float32(i)
+		e.PositionY = float32(i)
+		fmt.Println(e.VelocityX, e.VelocityY, e.PositionX, e.PositionY)
+	}
+
+	entities := arena.AllocMany(10) // allocate slice of 10 entities (cannot exceed 10 here because chunk size is 10 above, this limitation doesn't exist in batchallocator)
+
+	_ = entities
+
+	// Output:
+	// 0 0 0 0
+	// 1 1 1 1
+	// 2 2 2 2
+	// 3 3 3 3
+	// 4 4 4 4
+	// 5 5 5 5
+	// 6 6 6 6
+	// 7 7 7 7
+	// 8 8 8 8
+	// 9 9 9 9
+}

typedarena/example_test.go

@@ -1,3 +1,4 @@
+// typedarena is a growable typed arena that allocates memory in fixed chunks , it's faster that batchallocator but more limited, you can use batchallocator if you want to allocate multiple different types, and you want to use an arena like behavior spanning multiple datastructures (like vector, linkedlist, hashmap etc..), typedarena is much faster when you are only allocating one type.
 package typedarena
 
 import (