Add << support for trie, AA tree, and B-tree

Override TrieNode#<< to insert words via insert(word) semantics.\n\nAdd << shorthand to AATree and BTree for [key, value], { key:, value: }, and Entry inputs, with tests in both test-unit and RSpec suites.\n\nUse add() during JSON reconstruction to avoid coupling structural rebuilds to << overrides, and document that FenwickTree and SegmentTree intentionally do not support <<.\n\nUpdate CHANGELOG with the operator behavior changes.

Author: evolve75

CHANGELOG.md

@@ -6,6 +6,13 @@ Changes section to scan for breaking or behavioral changes.
 
 ## Release History
 
+### 3.0.0pre / 2026-02-10
+
+* 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
+  `[key, value]`, `{ key:, value: }`, and `Entry` inputs.
+
 ### 3.0.0pre / 2026-02-09
 
 * Add runnable example scripts for each supported tree type under `examples/`

lib/tree/aatree.rb

@@ -87,6 +87,18 @@ def insert(key, value = nil)
       inserted
     end
 
+    # Insert an entry using natural +<<+ syntax.
+    #
+    # @param [Array, Hash, Tree::AATree::Entry] entry Input entry as
+    #   +[key, value]+, +{ key:, value: }+, or {Tree::AATree::Entry}.
+    # @return [Tree::AATree::Entry] The inserted entry.
+    #
+    # @raise [ArgumentError] If the input format is unsupported.
+    def <<(entry)
+      key, value = entry_to_pair(entry)
+      insert(key, value)
+    end
+
     # Search for a key in the AA tree.
     #
     # @param [Object] key The key to search for.
@@ -271,6 +283,48 @@ def <=>(other)
 
     private
 
+    # Convert a supported entry input into a key/value pair.
+    #
+    # @param [Array, Hash, Tree::AATree::Entry] entry Input entry.
+    # @return [Array<Object, Object>] The +[key, value]+ pair.
+    #
+    # @raise [ArgumentError] If the input format is unsupported.
+    def entry_to_pair(entry)
+      return [entry.key, entry.value] if entry.is_a?(Entry)
+      return array_entry_to_pair(entry) if entry.is_a?(Array)
+      return hash_entry_to_pair(entry) if entry.is_a?(Hash)
+
+      raise ArgumentError, 'AA tree << expects [key, value], { key:, value: }, or Entry.'
+    end
+
+    # Convert an array entry into a key/value pair.
+    #
+    # @param [Array] entry Input as +[key, value]+.
+    # @return [Array<Object, Object>] The +[key, value]+ pair.
+    #
+    # @raise [ArgumentError] If the array shape is invalid.
+    def array_entry_to_pair(entry)
+      raise ArgumentError, 'AA tree << expects [key, value].' unless entry.length == 2
+
+      [entry[0], entry[1]]
+    end
+
+    # Convert a hash entry into a key/value pair.
+    #
+    # @param [Hash] entry Input as +{ key:, value: }+.
+    # @return [Array<Object, Object>] The +[key, value]+ pair.
+    #
+    # @raise [ArgumentError] If the hash shape is invalid.
+    def hash_entry_to_pair(entry)
+      has_symbol_key = entry.key?(:key)
+      has_string_key = entry.key?('key')
+      raise ArgumentError, 'AA tree << expects { key:, value: }.' unless has_symbol_key || has_string_key
+
+      key = has_symbol_key ? entry[:key] : entry['key']
+      value = entry.key?(:value) ? entry[:value] : entry['value']
+      [key, value]
+    end
+
     # Insert an entry into a node and return the new subtree root.
     #
     # @param [Tree::AATree::Node, nil] node The current subtree root.

lib/tree/btree.rb

@@ -152,6 +152,18 @@ def insert(key, value = nil)
       insert_non_full(root, Entry.new(key, value))
     end
 
+    # Insert an entry using natural +<<+ syntax.
+    #
+    # @param [Array, Hash, Tree::BTree::Entry] entry Input entry as
+    #   +[key, value]+, +{ key:, value: }+, or {Tree::BTree::Entry}.
+    # @return [Tree::BTree::Entry] The inserted entry.
+    #
+    # @raise [ArgumentError] If the input format is unsupported.
+    def <<(entry)
+      key, value = entry_to_pair(entry)
+      insert(key, value)
+    end
+
     # Search for a key in the B-tree.
     #
     # @param [Object] key The key to search for.
@@ -351,6 +363,48 @@ def <=>(other)
 
     private
 
+    # Convert a supported entry input into a key/value pair.
+    #
+    # @param [Array, Hash, Tree::BTree::Entry] entry Input entry.
+    # @return [Array<Object, Object>] The +[key, value]+ pair.
+    #
+    # @raise [ArgumentError] If the input format is unsupported.
+    def entry_to_pair(entry)
+      return [entry.key, entry.value] if entry.is_a?(Entry)
+      return array_entry_to_pair(entry) if entry.is_a?(Array)
+      return hash_entry_to_pair(entry) if entry.is_a?(Hash)
+
+      raise ArgumentError, 'B-tree << expects [key, value], { key:, value: }, or Entry.'
+    end
+
+    # Convert an array entry into a key/value pair.
+    #
+    # @param [Array] entry Input as +[key, value]+.
+    # @return [Array<Object, Object>] The +[key, value]+ pair.
+    #
+    # @raise [ArgumentError] If the array shape is invalid.
+    def array_entry_to_pair(entry)
+      raise ArgumentError, 'B-tree << expects [key, value].' unless entry.length == 2
+
+      [entry[0], entry[1]]
+    end
+
+    # Convert a hash entry into a key/value pair.
+    #
+    # @param [Hash] entry Input as +{ key:, value: }+.
+    # @return [Array<Object, Object>] The +[key, value]+ pair.
+    #
+    # @raise [ArgumentError] If the hash shape is invalid.
+    def hash_entry_to_pair(entry)
+      has_symbol_key = entry.key?(:key)
+      has_string_key = entry.key?('key')
+      raise ArgumentError, 'B-tree << expects { key:, value: }.' unless has_symbol_key || has_string_key
+
+      key = has_symbol_key ? entry[:key] : entry['key']
+      value = entry.key?(:value) ? entry[:value] : entry['value']
+      [key, value]
+    end
+
     # Maximum entries per node.
     #
     # @return [Integer] The maximum entry count.

lib/tree/fenwicktree.rb

@@ -56,6 +56,10 @@ module Tree
   #
   # Indices are zero-based for public methods.
   #
+  # @note The +<<+ operator is intentionally not supported for this class.
+  #   Fenwick trees require explicit indexed updates via {#update} or {#[]=},
+  #   and do not model append-style insertion semantics.
+  #
   class FenwickTree
     include Enumerable
     include Comparable

lib/tree/segmenttree.rb

@@ -54,6 +54,10 @@ module Tree
   #
   # Indices are zero-based for public methods.
   #
+  # @note The +<<+ operator is intentionally not supported for this class.
+  #   Segment trees require explicit indexed updates via {#update} or {#[]=},
+  #   and do not model append-style insertion semantics.
+  #
   class SegmentTree
     include Enumerable
     include Comparable

lib/tree/trie.rb

@@ -97,6 +97,21 @@ def insert(word)
       current
     end
 
+    # Insert a word into the trie using natural +<<+ syntax.
+    #
+    # This overrides {Tree::TreeNode#<<}. For trie nodes, +<<+ inserts a word
+    # (string) instead of attaching a child node directly.
+    #
+    # @param [String] word The word to insert.
+    # @return [Tree::TrieNode] The terminal node for the inserted word.
+    #
+    # @raise [ArgumentError] If the word is empty or not a string.
+    #
+    # @see #insert
+    def <<(word)
+      insert(word)
+    end
+
     # Returns +true+ if the trie includes the specified word.
     #
     # @param [String] word The word to look up.

lib/tree/utils/json_converter.rb

@@ -125,7 +125,7 @@ def json_create(json_hash)
           json_hash['children']&.each do |child|
             next unless child
 
-            node << child
+            node.add(child)
           end
 
           node

spec/tree/aa_tree_spec.rb

@@ -155,4 +155,20 @@ def build_tree(entries)
       expect { tree.insert(nil, 'a') }.to raise_error(ArgumentError)
     end
   end
+
+  describe '<<' do
+    it 'returns the inserted entry' do
+      tree = build_tree([])
+      inserted = tree << [10, 'a']
+
+      expect(inserted.key).to eq(10)
+    end
+
+    it 'stores the inserted key/value pair' do
+      tree = build_tree([])
+      tree << [10, 'a']
+
+      expect(tree.search(10)).to eq('a')
+    end
+  end
 end

spec/tree/b_tree_spec.rb

@@ -207,4 +207,20 @@ def inorder_keys(node, result = [])
       expect(tree <=> 123).to be_nil
     end
   end
+
+  describe '<<' do
+    it 'returns the inserted entry' do
+      tree = described_class.new(2)
+      inserted = tree << [10, 'a']
+
+      expect(inserted.key).to eq(10)
+    end
+
+    it 'stores the inserted key/value pair' do
+      tree = described_class.new(2)
+      tree << [10, 'a']
+
+      expect(tree.search(10)).to eq('a')
+    end
+  end
 end

spec/tree/trie_node_spec.rb

@@ -80,4 +80,20 @@ def build_trie(words)
       expect(root.words_with_prefix('do')).to eq(%w[dog])
     end
   end
+
+  describe '<<' do
+    it 'inserts a word' do
+      root = described_class.new('')
+      root << 'cat'
+
+      expect(root.include?('cat')).to be(true)
+    end
+
+    it 'returns the terminal node for the inserted word' do
+      root = described_class.new('')
+      terminal = root << 'cat'
+
+      expect(terminal.terminal?).to be(true)
+    end
+  end
 end