feat: hashmap

Author: billowdev

README.md

@@ -1 +1,218 @@
-# fastmap
+# `fastmap` Generic HashMap Package
+
+A type-safe, generic HashMap implementation in Go with both thread-safe and non-thread-safe variants.
+
+## Installation
+
+```bash
+go get github.com/billowdev/fastmap
+```
+
+## Features
+
+- Generic type support for keys and values
+- Thread-safe implementation available
+- Type-safe operations
+- Functional programming utilities
+- Zero dependencies
+- Comprehensive test coverage
+
+## Usage
+
+### Basic Operations (Non-Thread-Safe)
+
+```go
+// Initialize
+hashMap := fastmap.NewHashMap[string, YourType]()
+
+// Add/Update
+hashMap.Put("key", value)
+
+// Get
+value, exists := hashMap.Get("key")
+
+// Remove
+hashMap.Remove("key")
+
+// Get size
+size := hashMap.Size()
+
+// Update existing value
+success := hashMap.UpdateValue("key", newValue)
+```
+
+### Thread-Safe Operations
+
+```go
+// Initialize thread-safe map
+safeMap := fastmap.NewThreadSafeHashMap[string, YourType]()
+
+// Basic Operations
+safeMap.Put("key", value)
+value, exists := safeMap.Get("key")
+safeMap.Remove("key")
+
+// Safe iteration
+safeMap.ForEach(func(key string, value YourType) {
+    // Process each key-value pair safely
+})
+
+// Check existence
+if safeMap.Contains("key") {
+    // Key exists, safe for concurrent access
+}
+
+// Get all keys safely
+keys := safeMap.Keys()
+for _, key := range keys {
+    // Process keys
+}
+
+// Get all values safely
+values := safeMap.Values()
+for _, value := range values {
+    // Process values
+}
+
+// Clear all entries safely
+safeMap.Clear()
+
+// Check if empty
+if safeMap.IsEmpty() {
+    // Map is empty
+}
+
+// Merge two thread-safe maps
+otherMap := fastmap.NewThreadSafeHashMap[string, YourType]()
+otherMap.Put("other", value)
+safeMap.PutAll(otherMap)
+
+// Convert to regular map
+regularMap := safeMap.ToMap()
+
+// Create from regular map
+traditional := map[string]YourType{"key": value}
+safeMap = fastmap.FromThreadSafeMap(traditional)
+```
+
+### Thread-Safe Functional Operations
+
+```go
+// Filter with thread safety
+activeUsers := safeMap.Filter(func(key string, user User) bool {
+    return user.Active
+})
+
+// Transform with thread safety
+processedUsers := safeMap.Map(func(key string, user User) User {
+    user.LastProcessed = time.Now()
+    return user
+})
+
+// Conditional updates with thread safety
+if safeMap.UpdateValue("user1", updatedUser) {
+    // Update successful
+}
+```
+
+### Real-World Example (Thread-Safe)
+
+```go
+// User management system with concurrent access
+type UserSystem struct {
+    users *fastmap.ThreadSafeHashMap[string, User]
+}
+
+func NewUserSystem() *UserSystem {
+    return &UserSystem{
+        users: fastmap.NewThreadSafeHashMap[string, User](),
+    }
+}
+
+// Safe concurrent operations
+func (s *UserSystem) AddUser(id string, user User) {
+    s.users.Put(id, user)
+}
+
+func (s *UserSystem) GetActiveUsers() []User {
+    activeUsers := s.users.Filter(func(id string, user User) bool {
+        return user.Active && !user.Deleted
+    })
+    return activeUsers.Values()
+}
+
+func (s *UserSystem) UpdateUserStatus(id string, active bool) bool {
+    if user, exists := s.users.Get(id); exists {
+        user.Active = active
+        return s.users.UpdateValue(id, user)
+    }
+    return false
+}
+
+func (s *UserSystem) ProcessUsers() {
+    s.users.ForEach(func(id string, user User) {
+        // Safe concurrent processing
+        log.Printf("Processing user: %s", id)
+    })
+}
+
+// Usage in concurrent environment
+func main() {
+    system := NewUserSystem()
+    
+    // Concurrent operations
+    go func() {
+        system.AddUser("1", User{Name: "John", Active: true})
+    }()
+    
+    go func() {
+        system.UpdateUserStatus("1", false)
+    }()
+    
+    go func() {
+        activeUsers := system.GetActiveUsers()
+        for _, user := range activeUsers {
+            log.Printf("Active user: %s", user.Name)
+        }
+    }()
+}
+```
+
+## Migration Guide
+
+### Traditional Map vs HashMap
+
+```go
+// Traditional
+traditional := make(map[string]YourType)
+traditional[key] = value
+
+// Non-Thread-Safe HashMap
+hashMap := fastmap.NewHashMap[string, YourType]()
+hashMap.Put(key, value)
+
+// Thread-Safe HashMap
+safeMap := fastmap.NewThreadSafeHashMap[string, YourType]()
+safeMap.Put(key, value)
+```
+
+## Performance
+
+- Built on Go's native map implementation
+- Minimal method call overhead
+- O(1) average case for basic operations
+- Thread-safe operations use sync.RWMutex
+- Read operations allow concurrent access
+- Write operations ensure exclusive access
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch
+3. Commit your changes
+4. Push to the branch
+5. Create a Pull Request
+
+## License
+
+This project is licensed under the MIT License

conversion.go

@@ -0,0 +1,29 @@
+package fastmap
+
+// ToMap returns the underlying map
+// Example:
+//
+//	standardMap := hashMap.ToMap()
+//	for k, v := range standardMap {
+//	    fmt.Printf("%v: %v\n", k, v)
+//	}
+func (h *HashMap[K, V]) ToMap() map[K]V {
+	result := make(map[K]V, len(h.data))
+	for k, v := range h.data {
+		result[k] = v
+	}
+	return result
+}
+
+// FromMap creates a new HashMap from a regular map
+// Example:
+//
+//	regularMap := map[string]int{"one": 1, "two": 2}
+//	hashMap := FromMap(regularMap)
+func FromMap[K comparable, V any](m map[K]V) *HashMap[K, V] {
+	h := NewHashMap[K, V]()
+	for k, v := range m {
+		h.Put(k, v)
+	}
+	return h
+}

conversion_benchmark_test.go

@@ -0,0 +1,28 @@
+package fastmap
+
+import (
+	"fmt"
+	"testing"
+)
+
+func BenchmarkHashMapToMap(b *testing.B) {
+	h := NewHashMap[string, int]()
+	for i := 0; i < 1000; i++ {
+		h.Put(fmt.Sprintf("key%d", i), i)
+	}
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		h.ToMap()
+	}
+}
+
+func BenchmarkHashMapFromMap(b *testing.B) {
+	m := make(map[string]int)
+	for i := 0; i < 1000; i++ {
+		m[fmt.Sprintf("key%d", i)] = i
+	}
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		FromMap(m)
+	}
+}

conversion_test.go

@@ -0,0 +1,106 @@
+// conversion_test.go
+package fastmap
+
+import (
+	"fmt"
+	"reflect"
+	"sync"
+	"testing"
+)
+
+func TestToMap(t *testing.T) {
+	h := NewHashMap[string, int]()
+	h.Put("one", 1)
+	h.Put("two", 2)
+
+	want := map[string]int{"one": 1, "two": 2}
+	got := h.ToMap()
+
+	if !reflect.DeepEqual(got, want) {
+		t.Errorf("ToMap() = %v, want %v", got, want)
+	}
+}
+
+func TestFromMap(t *testing.T) {
+	original := map[string]int{"one": 1, "two": 2}
+	h := FromMap(original)
+
+	if h.Size() != len(original) {
+		t.Errorf("FromMap() size = %v, want %v", h.Size(), len(original))
+	}
+
+	for k, v := range original {
+		if got, exists := h.Get(k); !exists || got != v {
+			t.Errorf("FromMap() value for key %v = %v, want %v", k, got, v)
+		}
+	}
+}
+func TestConversionEdgeCases(t *testing.T) {
+	t.Run("empty map", func(t *testing.T) {
+		h := FromMap(map[string]int{})
+		if h.Size() != 0 {
+			t.Error("FromMap empty map failed")
+		}
+		if len(h.ToMap()) != 0 {
+			t.Error("ToMap empty map failed")
+		}
+	})
+
+	t.Run("nil map", func(t *testing.T) {
+		var m map[string]int
+		h := FromMap(m)
+		if h.Size() != 0 {
+			t.Error("FromMap nil map failed")
+		}
+	})
+
+	t.Run("large map", func(t *testing.T) {
+		m := make(map[string]int)
+		for i := 0; i < 10000; i++ {
+			m[fmt.Sprintf("key%d", i)] = i
+		}
+		h := FromMap(m)
+		if !reflect.DeepEqual(h.ToMap(), m) {
+			t.Error("Large map conversion failed")
+		}
+	})
+
+	t.Run("concurrent access", func(t *testing.T) {
+		var wg sync.WaitGroup
+
+		for i := 0; i < 100; i++ {
+			wg.Add(1)
+			go func(i int) {
+				defer wg.Done()
+				m := map[string]int{fmt.Sprintf("key%d", i): i}
+				temp := FromMap(m)
+				temp.ToMap()
+			}(i)
+		}
+		wg.Wait()
+	})
+
+	t.Run("non-string keys", func(t *testing.T) {
+		m := map[int]string{1: "one", 2: "two"}
+		h := FromMap(m)
+		if !reflect.DeepEqual(h.ToMap(), m) {
+			t.Error("Integer key conversion failed")
+		}
+	})
+
+	t.Run("pointer values", func(t *testing.T) {
+		type Data struct {
+			value int // Changed field name to be used
+		}
+		m := map[string]*Data{"a": {1}, "b": {2}}
+		h := FromMap(m)
+		convertedMap := h.ToMap()
+
+		// Compare values explicitly
+		for k, v := range m {
+			if got, exists := convertedMap[k]; !exists || got.value != v.value {
+				t.Errorf("For key %s, got %v, want %v", k, got, v)
+			}
+		}
+	})
+}