Merge pull request #4 from mikenye/implement_floor_ceiling

Implement Floor & Ceiling methods, improve code clarity & improve comments.

Author: mikenye

bst/examples_test.go

@@ -195,3 +195,101 @@ func ExampleTree_Predecessor_traversal() {
 	// Node with key 1 has value one (and color: ⬛)
 	// Node with key 0 has value zero (and color: ⬛)
 }
+
+func ExampleTree_Floor() {
+	// Create a tree with even numbers
+	tree := bst.New[int, string, struct{}](func(a, b int) bool {
+		return a < b
+	})
+
+	tree.Insert(2, "two")
+	tree.Insert(4, "four")
+	tree.Insert(6, "six")
+	tree.Insert(8, "eight")
+	tree.Insert(10, "ten")
+
+	// Find floor value for various inputs
+
+	// Exact match
+	if node, found := tree.Floor(6); found {
+		fmt.Printf("Floor(6) = %d: %s\n", tree.Key(node), tree.Value(node))
+	} else {
+		fmt.Println("Floor(6) not found")
+	}
+
+	// Floor value for an odd number (finds the next lower value)
+	if node, found := tree.Floor(7); found {
+		fmt.Printf("Floor(7) = %d: %s\n", tree.Key(node), tree.Value(node))
+	} else {
+		fmt.Println("Floor(7) not found")
+	}
+
+	// Floor value for a value smaller than the minimum
+	if node, found := tree.Floor(1); found {
+		fmt.Printf("Floor(1) = %d: %s\n", tree.Key(node), tree.Value(node))
+	} else {
+		fmt.Println("Floor(1) not found")
+	}
+
+	// Floor value for a value larger than the maximum
+	if node, found := tree.Floor(12); found {
+		fmt.Printf("Floor(12) = %d: %s\n", tree.Key(node), tree.Value(node))
+	} else {
+		fmt.Println("Floor(12) not found")
+	}
+
+	// Output:
+	// Floor(6) = 6: six
+	// Floor(7) = 6: six
+	// Floor(1) not found
+	// Floor(12) = 10: ten
+}
+
+func ExampleTree_Ceiling() {
+	// Create a tree with even numbers
+	tree := bst.New[int, string, struct{}](func(a, b int) bool {
+		return a < b
+	})
+
+	tree.Insert(2, "two")
+	tree.Insert(4, "four")
+	tree.Insert(6, "six")
+	tree.Insert(8, "eight")
+	tree.Insert(10, "ten")
+
+	// Find ceiling value for various inputs
+
+	// Exact match
+	if node, found := tree.Ceiling(6); found {
+		fmt.Printf("Ceiling(6) = %d: %s\n", tree.Key(node), tree.Value(node))
+	} else {
+		fmt.Println("Ceiling(6) not found")
+	}
+
+	// Ceiling value for an odd number (finds the next higher value)
+	if node, found := tree.Ceiling(5); found {
+		fmt.Printf("Ceiling(5) = %d: %s\n", tree.Key(node), tree.Value(node))
+	} else {
+		fmt.Println("Ceiling(5) not found")
+	}
+
+	// Ceiling value for a value smaller than the minimum
+	if node, found := tree.Ceiling(1); found {
+		fmt.Printf("Ceiling(1) = %d: %s\n", tree.Key(node), tree.Value(node))
+	} else {
+		fmt.Println("Ceiling(1) not found")
+	}
+
+	// Ceiling value for a value larger than the maximum
+	if node, found := tree.Ceiling(12); found {
+		fmt.Printf("Ceiling(12) = %d: %s\n", tree.Key(node), tree.Value(node))
+	} else {
+		fmt.Println("Ceiling(12) not found")
+	}
+
+	// Output:
+	// Ceiling(6) = 6: six
+	// Ceiling(5) = 6: six
+	// Ceiling(1) = 2: two
+	// Ceiling(12) not found
+}

bst/tree.go

@@ -239,7 +239,7 @@ func (t *Tree[K, V, M]) Insert(key K, value V) (*Node[K, V, M], bool) {
 		// update trailing pointer
 		parent = currNode
 
-		if !t.less(currNode.key, key) && !t.less(key, currNode.key) {
+		if t.keysEqual(currNode.key, key) {
 
 			// If key already exists, update the value
 			currNode.value = value
@@ -582,7 +582,7 @@ func (t *Tree[K, V, M]) Search(key K) (*Node[K, V, M], bool) {
 	for currNode != t.nil {
 
 		// if we've found the matching node, return it
-		if !t.less(currNode.key, key) && !t.less(key, currNode.key) {
+		if t.keysEqual(currNode.key, key) {
 			return currNode, true
 		}
 
@@ -876,3 +876,88 @@ func (t *Tree[K, V, M]) TraverseInOrder(n *Node[K, V, M], f TraversalFunc[K, V,
 func (t *Tree[K, V, M]) Value(n *Node[K, V, M]) V {
 	return n.value
 }
+
+// keysEqual determines if two keys are equal by using the less function.
+//
+// Two keys are considered equal if neither is less than the other.
+//
+// This is a helper method that improves performance by avoiding duplicate calls to the less function.
+func (t *Tree[K, V, M]) keysEqual(a, b K) bool {
+	return !t.less(a, b) && !t.less(b, a)
+}
+
+// Floor finds the largest key in the tree less than or equal to key.
+//
+// Returns:
+//   - (*Node[K, V, M], true) if a key ≤ key exists in the tree.
+//   - (nil, false) if no such key exists.
+func (t *Tree[K, V, M]) Floor(key K) (*Node[K, V, M], bool) {
+	if t.IsNil(t.root) {
+		return t.nil, false
+	}
+
+	var floor *Node[K, V, M] = t.nil
+	current := t.root
+
+	for !t.IsNil(current) {
+		// If current key equals the search key, we found an exact match
+		if t.keysEqual(current.key, key) {
+			return current, true
+		}
+
+		// If current key is greater than search key, go left
+		if t.less(key, current.key) {
+			current = current.left
+		} else {
+			// If current key is less than search key, this is a potential floor value
+			// Update floor and continue searching in the right subtree for larger values
+			floor = current
+			current = current.right
+		}
+	}
+
+	// If we found a floor value, return it
+	if !t.IsNil(floor) {
+		return floor, true
+	}
+
+	return t.nil, false
+}
+
+// Ceiling finds the smallest key in the tree greater than or equal to key.
+//
+// Returns:
+//   - (*Node[K, V, M], true) if a key ≥ key exists in the tree.
+//   - (nil, false) if no such key exists.
+func (t *Tree[K, V, M]) Ceiling(key K) (*Node[K, V, M], bool) {
+	if t.IsNil(t.root) {
+		return t.nil, false
+	}
+
+	var ceiling *Node[K, V, M] = t.nil
+	current := t.root
+
+	for !t.IsNil(current) {
+		// If current key equals the search key, we found an exact match
+		if t.keysEqual(current.key, key) {
+			return current, true
+		}
+
+		// If current key is less than search key, go right
+		if t.less(current.key, key) {
+			current = current.right
+		} else {
+			// If current key is greater than search key, this is a potential ceiling value
+			// Update ceiling and continue searching in the left subtree for smaller values
+			ceiling = current
+			current = current.left
+		}
+	}
+
+	// If we found a ceiling value, return it
+	if !t.IsNil(ceiling) {
+		return ceiling, true
+	}
+
+	return t.nil, false
+}

bst/tree_test.go

@@ -856,3 +856,123 @@ func TestTree_Contains(t *testing.T) {
 	assert.False(t, treeA.Contains(nB), "node from tree B should not exist in node A")
 	assert.True(t, treeB.Contains(nB), "expected to find node B in tree B")
 }
+
+func TestTree_Floor(t *testing.T) {
+	tree := New[int, string, struct{}](func(a, b int) bool {
+		return a < b
+	})
+
+	// Test with empty tree
+	n, found := tree.Floor(5)
+	assert.False(t, found, "Floor in empty tree should return not found")
+	assert.True(t, tree.IsNil(n), "Floor in empty tree should return nil node")
+
+	// Insert some values
+	tree.Insert(10, "ten")
+	tree.Insert(5, "five")
+	tree.Insert(15, "fifteen")
+	tree.Insert(3, "three")
+	tree.Insert(7, "seven")
+	tree.Insert(12, "twelve")
+	tree.Insert(17, "seventeen")
+
+	// Test exact matches
+	n, found = tree.Floor(10)
+	assert.True(t, found, "Floor for existing key should be found")
+	assert.Equal(t, 10, tree.Key(n), "Floor(10) should return node with key 10")
+	assert.Equal(t, "ten", tree.Value(n), "Floor(10) should return node with value 'ten'")
+
+	// Test where floor is less than key
+	n, found = tree.Floor(6)
+	assert.True(t, found, "Floor(6) should find a node")
+	assert.Equal(t, 5, tree.Key(n), "Floor(6) should return node with key 5")
+	assert.Equal(t, "five", tree.Value(n), "Floor(6) should return node with value 'five'")
+
+	// Test where floor is less than smallest key
+	n, found = tree.Floor(2)
+	assert.False(t, found, "Floor(2) should not find a node")
+	assert.True(t, tree.IsNil(n), "Floor(2) should return nil node")
+
+	// Test where floor is largest key
+	n, found = tree.Floor(20)
+	assert.True(t, found, "Floor(20) should find a node")
+	assert.Equal(t, 17, tree.Key(n), "Floor(20) should return node with key 17")
+	assert.Equal(t, "seventeen", tree.Value(n), "Floor(20) should return node with value 'seventeen'")
+}
+
+func TestTree_Ceiling(t *testing.T) {
+	tree := New[int, string, struct{}](func(a, b int) bool {
+		return a < b
+	})
+
+	// Test with empty tree
+	n, found := tree.Ceiling(5)
+	assert.False(t, found, "Ceiling in empty tree should return not found")
+	assert.True(t, tree.IsNil(n), "Ceiling in empty tree should return nil node")
+
+	// Insert some values
+	tree.Insert(10, "ten")
+	tree.Insert(5, "five")
+	tree.Insert(15, "fifteen")
+	tree.Insert(3, "three")
+	tree.Insert(7, "seven")
+	tree.Insert(12, "twelve")
+	tree.Insert(17, "seventeen")
+
+	// Test exact matches
+	n, found = tree.Ceiling(10)
+	assert.True(t, found, "Ceiling for existing key should be found")
+	assert.Equal(t, 10, tree.Key(n), "Ceiling(10) should return node with key 10")
+	assert.Equal(t, "ten", tree.Value(n), "Ceiling(10) should return node with value 'ten'")
+
+	// Test where ceiling is greater than key
+	n, found = tree.Ceiling(6)
+	assert.True(t, found, "Ceiling(6) should find a node")
+	assert.Equal(t, 7, tree.Key(n), "Ceiling(6) should return node with key 7")
+	assert.Equal(t, "seven", tree.Value(n), "Ceiling(6) should return node with value 'seven'")
+
+	// Test where ceiling is smallest key
+	n, found = tree.Ceiling(1)
+	assert.True(t, found, "Ceiling(1) should find a node")
+	assert.Equal(t, 3, tree.Key(n), "Ceiling(1) should return node with key 3")
+	assert.Equal(t, "three", tree.Value(n), "Ceiling(1) should return node with value 'three'")
+
+	// Test where key is larger than largest in tree
+	n, found = tree.Ceiling(20)
+	assert.False(t, found, "Ceiling(20) should not find a node")
+	assert.True(t, tree.IsNil(n), "Ceiling(20) should return nil node")
+}
+
+// TestTree_UncoveredSetMethods tests the uncovered set methods
+func TestTree_UncoveredSetMethods(t *testing.T) {
+	tree := New[int, string, struct{}](func(a, b int) bool {
+		return a < b
+	})
+
+	// Create a test node
+	node, _ := tree.Insert(10, "original value")
+
+	// Test SetValue
+	tree.SetValue(node, "new value")
+	assert.Equal(t, "new value", tree.Value(node), "SetValue should update the node's value")
+
+	// Test SetLeft and SetRight
+	leftNode, _ := tree.Insert(5, "left")
+	rightNode, _ := tree.Insert(15, "right")
+
+	// Save original relationships
+	originalLeft := node.left
+	originalRight := node.right
+
+	// Manually change the relationships with SetLeft and SetRight
+	tree.SetLeft(node, rightNode) // Intentionally incorrect for testing
+	tree.SetRight(node, leftNode) // Intentionally incorrect for testing
+
+	// Verify the changes took effect
+	assert.Equal(t, rightNode, tree.Left(node), "SetLeft should update the node's left child")
+	assert.Equal(t, leftNode, tree.Right(node), "SetRight should update the node's right child")
+
+	// Restore original structure to avoid affecting other tests
+	tree.SetLeft(node, originalLeft)
+	tree.SetRight(node, originalRight)
+}