Add Item function to Stepper (#25)

The Stepper.Item function returns a struct that contains a key and a value, or nil if there is no value at the current position. This allows the key as well as the value to be retrieved from the current position.

go.mod

@@ -1,3 +1,3 @@
 module github.com/gammazero/radixtree
 
-go 1.20
+go 1.21

stepper.go

@@ -56,16 +56,23 @@ func (s *Stepper) Next(radix byte) bool {
 	return true
 }
 
+// Item returns an Item containing the key and value at the current Stepper
+// position, or returns nil if no value is present at the position.
+func (s *Stepper) Item() *Item {
+	// Only return item if all of this node's prefix was matched. Otherwise,
+	// have not fully traversed into this node (edge not completely traversed).
+	if s.p == len(s.node.prefix) {
+		return s.node.leaf
+	}
+	return nil
+}
+
 // Value returns the value at the current Stepper position, and true or false
 // to indicate if a value is present at the position.
 func (s *Stepper) Value() (any, bool) {
-	// Only return value if all of this node's prefix was matched.  Otherwise,
-	// have not fully traversed into this node (edge not completely traversed).
-	if s.p != len(s.node.prefix) {
-		return nil, false
-	}
-	if s.node.leaf == nil {
+	item := s.Item()
+	if item == nil {
 		return nil, false
 	}
-	return s.node.leaf.value, true
+	return item.value, true
 }

stepper_test.go

@@ -24,6 +24,10 @@ func TestStepper(t *testing.T) {
 	if ok || val != nil {
 		t.Fatal("should not have value at 't'")
 	}
+	item := iter.Item()
+	if item != nil {
+		t.Fatal("should not have item at 't'")
+	}
 	if !iter.Next('o') {
 		t.Fatal("'o' should have advanced iterator")
 	}
@@ -44,6 +48,13 @@ func TestStepper(t *testing.T) {
 	if !ok || val != "TOM" {
 		t.Fatalf("expected \"TOM\" at 'm', got %q", val)
 	}
+	item = iter.Item()
+	if item == nil || item.Value() != "TOM" {
+		t.Fatalf("expected value \"TOM\" at 'm'")
+	}
+	if item.Key() != "tom" {
+		t.Fatalf("expected key \"tom\" at 'm'")
+	}
 	if !iter.Next('a') {
 		t.Fatal("'a' should have advanced iterator")
 	}

tree.go

@@ -20,7 +20,7 @@ type radixNode struct {
 	// segment used in the parent to index this child.
 	prefix string
 	edges  []edge
-	leaf   *leaf
+	leaf   *Item
 }
 
 // WalkFunc is the type of the function called for each value visited by Walk
@@ -39,11 +39,14 @@ type WalkFunc func(key string, value any) bool
 // If the function returns true Inspect stops immediately and returns.
 type InspectFunc func(link, prefix, key string, depth, children int, hasValue bool, value any) bool
 
-type leaf struct {
+type Item struct {
 	key   string
 	value any
 }
 
+func (kv *Item) Key() string { return kv.key }
+func (kv *Item) Value() any  { return kv.value }
+
 type edge struct {
 	radix byte
 	node  *radixNode
@@ -108,7 +111,7 @@ func (t *Tree) Put(key string, value any) bool {
 		// data, so add child that has a prefix of the unmatched key data and
 		// set its value to the new value.
 		newChild := &radixNode{
-			leaf: &leaf{
+			leaf: &Item{
 				key:   key,
 				value: value,
 			},
@@ -139,7 +142,7 @@ func (t *Tree) Put(key string, value any) bool {
 			isNewValue = true
 			t.size++
 		}
-		node.leaf = &leaf{
+		node.leaf = &Item{
 			key:   key,
 			value: value,
 		}