Add non-breaking API aliases for consistency

Introduce lookup/query/pop/search aliases across selected tree types to improve cross-family API consistency without changing existing behavior, and add regression tests for alias contracts.

Author: evolve75

CHANGELOG.md

@@ -8,6 +8,12 @@ Changes section to scan for breaking or behavioral changes.
 
 ### 3.0.0pre / 2026-02-10
 
+* Add non-breaking API aliases for consistency:
+  `Tree::AATree#lookup`, `Tree::BTree#lookup`,
+  `Tree::FenwickTree#query`, `Tree::SegmentTree#query`,
+  `Tree::BinaryHeapNode#pop`, `Tree::BinaryMaxHeapNode#pop`,
+  and `Tree::TrieNode#search`.
+* Add alias-focused regression tests to lock these compatibility contracts.
 * Make `Tree::TrieNode#<<` use trie word-insert semantics (`insert(word)`)
   instead of generic child-node attachment semantics.
 * Add `<<` insertion shorthand to `Tree::AATree` and `Tree::BTree` for

lib/tree/aatree.rb

@@ -115,6 +115,14 @@ def search(key)
       nil
     end
 
+    # Alias for {#search} to support lookup-oriented naming.
+    #
+    # @param [Object] key The key to search for.
+    # @return [Object, nil] The matching value, or +nil+.
+    def lookup(key)
+      search(key)
+    end
+
     # Delete a key from the AA tree.
     #
     # @param [Object] key The key to delete.

lib/tree/binaryheap.rb

@@ -125,6 +125,13 @@ def extract
       removed
     end
 
+    # Alias for {#extract} using priority-queue naming.
+    #
+    # @return [Object, nil] The removed minimum value, or +nil+ if empty.
+    def pop
+      extract
+    end
+
     # Searches for a node matching the specified key (content).
     #
     # @param [Object] key The search key (node content).

lib/tree/binarymaxheap.rb

@@ -125,6 +125,13 @@ def extract
       removed
     end
 
+    # Alias for {#extract} using priority-queue naming.
+    #
+    # @return [Object, nil] The removed maximum value, or +nil+ if empty.
+    def pop
+      extract
+    end
+
     # Searches for a node matching the specified key (content).
     #
     # @param [Object] key The search key (node content).

lib/tree/btree.rb

@@ -176,6 +176,14 @@ def search(key)
       entry&.value
     end
 
+    # Alias for {#search} to support lookup-oriented naming.
+    #
+    # @param [Object] key The key to search for.
+    # @return [Object, nil] The matching value, or +nil+.
+    def lookup(key)
+      search(key)
+    end
+
     # Delete a key from the B-tree.
     #
     # @param [Object] key The key to delete.

lib/tree/fenwicktree.rb

@@ -169,6 +169,15 @@ def range_sum(left, right)
       sum(right) - sum(left - 1)
     end
 
+    # Alias for {#range_sum} with query-oriented naming.
+    #
+    # @param [Integer] left The starting index.
+    # @param [Integer] right The ending index.
+    # @return [Numeric] Sum in the specified range.
+    def query(left, right)
+      range_sum(left, right)
+    end
+
     # Read the value at the specified index.
     #
     # @param [Integer] index Zero-based index.

lib/tree/segmenttree.rb

@@ -142,6 +142,15 @@ def range_sum(left, right)
       query_sum(1, 0, @size - 1, left, right)
     end
 
+    # Alias for {#range_sum} with query-oriented naming.
+    #
+    # @param [Integer] left The starting index.
+    # @param [Integer] right The ending index.
+    # @return [Numeric] Sum in the specified range.
+    def query(left, right)
+      range_sum(left, right)
+    end
+
     # Read the value at the specified index.
     #
     # @param [Integer] index Zero-based index.

lib/tree/trie.rb

@@ -122,6 +122,9 @@ def include?(word)
       node&.terminal? == true
     end
 
+    # Alias for {#include?} to support search-oriented naming.
+    alias search include?
+
     # Returns +true+ if the trie includes the specified prefix.
     #
     # @param [String] prefix The prefix to look up.

test/test_api_alias_consistency.rb

@@ -0,0 +1,84 @@
+# test_api_alias_consistency.rb - This file is part of the RubyTree package.
+#
+# Copyright (c) 2026 Anupam Sengupta
+#
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without modification,
+# are permitted provided that the following conditions are met:
+#
+# - Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.
+#
+# - Redistributions in binary form must reproduce the above copyright notice, this
+#   list of conditions and the following disclaimer in the documentation and/or
+#   other materials provided with the distribution.
+#
+# - Neither the name of the organization nor the names of its contributors may
+#   be used to endorse or promote products derived from this software without
+#   specific prior written permission.
+#
+#   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+# ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+# frozen_string_literal: true
+
+require 'test/unit'
+require_relative '../lib/tree/aatree'
+require_relative '../lib/tree/binaryheap'
+require_relative '../lib/tree/binarymaxheap'
+require_relative '../lib/tree/btree'
+require_relative '../lib/tree/fenwicktree'
+require_relative '../lib/tree/segmenttree'
+require_relative '../lib/tree/trie'
+
+module TestTree
+  # Alias-consistency tests for Phase 2 API harmonization.
+  class TestApiAliasConsistency < Test::Unit::TestCase
+    def test_key_value_lookup_alias
+      aa = Tree::AATree.new([[10, 'a']])
+      bt = Tree::BTree.new(2, [{ key: 10, value: 'a' }])
+
+      assert_equal(aa.search(10), aa.lookup(10))
+      assert_equal(bt.search(10), bt.lookup(10))
+    end
+
+    def test_aggregate_query_alias
+      fenwick = Tree::FenwickTree.new(4, [1, 2, 3, 4])
+      segment = Tree::SegmentTree.new(4, [1, 2, 3, 4])
+
+      assert_equal(fenwick.range_sum(1, 3), fenwick.query(1, 3))
+      assert_equal(segment.range_sum(1, 3), segment.query(1, 3))
+    end
+
+    def test_heap_pop_alias
+      min_heap = Tree::BinaryHeapNode.new('root', 3)
+      min_heap.insert('a', 1)
+      min_heap.insert('b', 2)
+      max_heap = Tree::BinaryMaxHeapNode.new('root', 3)
+      max_heap.insert('a', 9)
+      max_heap.insert('b', 8)
+
+      assert_equal(1, min_heap.pop)
+      assert_equal(2, min_heap.extract)
+      assert_equal(9, max_heap.pop)
+      assert_equal(8, max_heap.extract)
+    end
+
+    def test_trie_search_alias
+      trie = Tree::TrieNode.new('')
+      trie.insert('cat')
+
+      assert_equal(trie.include?('cat'), trie.search('cat'))
+      assert_equal(trie.include?('dog'), trie.search('dog'))
+    end
+  end
+end