add CRUD operations and JSON regression coverage

Author: cornelk

README.md

@@ -7,21 +7,70 @@
 
 ## Overview
 
-A Golang Map that keeps track of the insert order of items.
+A Go map that preserves insertion order for manual operations and JSON marshalling.
+Nested JSON objects are unmarshalled as ordered maps too.
 
-The current version can be used as a replacement for `map[string]any` and allows JSON unmarshalling into it.
-No manual adding of items is currently possible.
+## Installation
+
+```bash
+go get github.com/cornelk/orderedmap
+```
+
+Requires Go 1.24 or later.
 
 ## Usage
 
-Unmarshall and marshall JSON:
+```go
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+
+	"github.com/cornelk/orderedmap"
+)
+
+func main() {
+	var m orderedmap.Map
+
+	m.Set("name", "Alice")
+	m.Set("age", 30)
+
+	if value, ok := m.Get("name"); ok {
+		fmt.Println(value)
+	}
 
+	m.Range(func(key string, value any) bool {
+		fmt.Printf("%s: %v\n", key, value)
+		return true
+	})
+
+	data, _ := json.Marshal(&m)
+	fmt.Println(string(data))
+}
 ```
-var m Map
-input := `{"423":"abc","231":"dbh","152":"xyz"}`
 
-m.UnmarshalJSON([]byte(input))
+JSON input order is preserved when unmarshalling and marshalling:
+
+```go
+var m orderedmap.Map
+input := `{"423":"abc","231":"dbh","152":"xyz"}`
 
-output, _ := m.MarshalJSON()
-# unlike the standard Golang map, the output will be exact the same and not in random key order
+json.Unmarshal([]byte(input), &m)
+output, _ := json.Marshal(&m)
+// Output: {"423":"abc","231":"dbh","152":"xyz"}
 ```
+
+## API
+
+- `Set(key string, value any)` adds or updates a value without moving existing keys.
+- `Get(key string) (any, bool)` retrieves a value.
+- `Delete(key string) bool` removes a value.
+- `GetAndDelete(key string) (any, bool)` retrieves and removes a value.
+- `Clear()` removes all values.
+- `Len() int` returns the number of entries.
+- `Range(func(key string, value any) bool)` iterates in insertion order.
+
+## License
+
+Apache-2.0 License - See LICENSE file for details.

map.go

@@ -9,10 +9,12 @@ import (
 )
 
 // Map implements a map that keeps the item order.
+// It preserves the insertion order of keys for both JSON unmarshalling
+// and manual operations.
 type Map struct {
-	// Data holds the map entries in unsorted order.
+	// Data holds the map entries with their sequence indices.
 	Data map[string]Entry
-	// Keys contains the map keys in sorted order.
+	// Keys contains the map keys in insertion order.
 	Keys []string
 }
 
@@ -21,9 +23,88 @@ func (m *Map) Len() int {
 	return len(m.Keys)
 }
 
+// Get retrieves the value for the given key.
+// Returns the value and true if the key exists, or nil and false otherwise.
+func (m *Map) Get(key string) (any, bool) {
+	if m.Data == nil {
+		return nil, false
+	}
+	entry, exists := m.Data[key]
+	if !exists {
+		return nil, false
+	}
+	return entry.Value, true
+}
+
+// Set adds or updates a key-value pair in the map.
+// If the key already exists, its value is updated without changing position.
+// If the key is new, it is appended to the end of the insertion order.
+func (m *Map) Set(key string, value any) {
+	if m.Data == nil {
+		m.Data = make(map[string]Entry)
+	}
+
+	if _, exists := m.Data[key]; !exists {
+		m.Keys = append(m.Keys, key)
+	}
+
+	m.Data[key] = Entry{
+		index: nextSequence(),
+		Value: value,
+	}
+}
+
+// Delete removes a key-value pair from the map.
+// Returns true if the key existed and was deleted, false otherwise.
+//
+// Performance note: This operation is O(n) where n is the number of keys,
+// as it requires searching through the Keys slice to find and remove the key.
+func (m *Map) Delete(key string) bool {
+	if m.Data == nil {
+		return false
+	}
+
+	if _, exists := m.Data[key]; !exists {
+		return false
+	}
+
+	delete(m.Data, key)
+
+	for i, k := range m.Keys {
+		if k == key {
+			m.Keys = append(m.Keys[:i], m.Keys[i+1:]...)
+			break
+		}
+	}
+
+	return true
+}
+
+// GetAndDelete retrieves and removes a key in one operation.
+// Returns the value and true if the key existed, or nil and false otherwise.
+//
+// Performance note: This operation is O(n) due to the underlying Delete operation.
+func (m *Map) GetAndDelete(key string) (value any, loaded bool) {
+	value, loaded = m.Get(key)
+	if loaded {
+		m.Delete(key)
+	}
+	return value, loaded
+}
+
+// Clear removes all entries from the map, resulting in an empty map.
+func (m *Map) Clear() {
+	m.Data = make(map[string]Entry)
+	m.Keys = nil
+}
+
 // Range calls f sequentially for each key and value present in the map.
 // If f returns false, range stops the iteration.
 func (m *Map) Range(f func(key string, value any) bool) {
+	if m.Data == nil || len(m.Keys) == 0 {
+		return
+	}
+
 	for _, key := range m.Keys {
 		entry := m.Data[key]
 		if !f(key, entry.Value) {
@@ -44,31 +125,41 @@ func (m *Map) UnmarshalJSON(b []byte) error {
 
 // MarshalJSON implements the json.Marshaler interface.
 func (m *Map) MarshalJSON() ([]byte, error) {
-	var buf bytes.Buffer
+	if m == nil || len(m.Keys) == 0 {
+		return []byte("{}"), nil
+	}
+
+	buf := bytes.NewBuffer(make([]byte, 0, len(m.Keys)*20))
 	buf.WriteString("{")
 
+	lastIdx := len(m.Keys) - 1
 	for i, key := range m.Keys {
-		buf.WriteString(fmt.Sprintf("%q:", key))
+		keyData, err := json.Marshal(key)
+		if err != nil {
+			return nil, fmt.Errorf("marshalling key %q: %w", key, err)
+		}
+		buf.Write(keyData)
+		buf.WriteByte(':')
 
 		value := m.Data[key].Value
 		b, err := json.Marshal(value)
 		if err != nil {
-			return nil, fmt.Errorf("marshalling entry: %w", err)
+			return nil, fmt.Errorf("marshalling entry for key %q: %w", key, err)
 		}
 		buf.Write(b)
 
-		if i < len(m.Keys)-1 {
-			buf.WriteString(",")
+		if i < lastIdx {
+			buf.WriteByte(',')
 		}
 	}
 
-	buf.WriteString("}")
+	buf.WriteByte('}')
 	return buf.Bytes(), nil
 }
 
-// rebuildKeys build the sorted keys slice.
+// rebuildKeys builds the keys slice sorted by insertion order.
 func (m *Map) rebuildKeys() {
-	m.Keys = []string{}
+	m.Keys = make([]string, 0, len(m.Data))
 	for name := range m.Data {
 		m.Keys = append(m.Keys, name)
 	}