dsa-ruby 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d48c162c54e6f3b5a72e0ec6c5bfb01ea194db9aa01edd8b3acf22ec8e65d2a
-  data.tar.gz: 90dec8d0903d522bd53c1928f1b4bfe4e3183c51ac0cd6c6c2089864eeaf31ed
+  metadata.gz: 263fc0d28c00fb0c51f2728871cc4f13e5f8d5d8c2011cd42523d440003bcd3e
+  data.tar.gz: 72d323d5c5b3527ee5ad9c4ec85b2949ff1ec90a6258928e83ced26358bc7466
 SHA512:
-  metadata.gz: ffc6d6ee8215956588a61c477fbf92c8a441d43ded58525f758086c07433389616c9f538bac40d2de30f113d184beec0cfb155d236cc7ddb08da815b9d1aa75f
-  data.tar.gz: 700cbc183e14b7fe0884c52b43a49c686530e6276deea50a3eaf6b7df9e65dfd23b51ccc21c38d5af38bed62496f59e1314c43c59a20d0587344d495606406c3
+  metadata.gz: 8d0dced01fb73b0a2e76d32795bbf57ffb84ffeaee0d790089d63e5e33365a7113247ede84e080b6e4fdcf4b30ad0459e42f81ed42bc6c18e7d49b29ad3cbcb6
+  data.tar.gz: 6855c1c3e893b55ae698e966094117d5f3105f39c4724bcd09fb478570ebd4ade85d6817f24b19172cd3a3787b0b625360ef49cdb1a5b100cc263a1cdd067d8c

data/README.md

@@ -24,8 +24,7 @@ require "dsa-ruby"
 ### MinHeap / MaxHeap
 
 ```ruby
-heap = DSA::MinHeap.new
-heap.push(5, 3, 7, 1)
+heap = DSA::MinHeap.new([5, 3, 7, 1])
 heap.pop   # => 1
 heap.peek  # => 3
 
@@ -33,6 +32,13 @@ max_heap = DSA::MaxHeap.new([5, 3, 7, 1])
 max_heap.pop  # => 7
 ```
 
+Or build incrementally with chained pushes:
+
+```ruby
+heap = DSA::MinHeap.new
+heap.push(5).push(3).push(7).push(1)
+```
+
 ### PriorityQueue
 
 ```ruby
@@ -58,7 +64,7 @@ dq.pop_front   # => 1
 dq.pop_back    # => 2
 
 # Enumerable support
-dq.push_back(1, 2, 3)
+dq.push_back(1).push_back(2).push_back(3)
 dq.map { |x| x * 2 }  # => [2, 4, 6]
 ```
 

data/lib/dsa-ruby/binary_search_tree.rb

@@ -1,154 +1,289 @@
-module DSA
-  class BinarySearchTree
-    Node = Struct.new(:val, :left, :right, keyword_init: true)
+# DSA::BinarySearchTree - A binary search tree data structure.
+#
+# Supports insertion, deletion, search, and tree traversals.
+# Duplicate values are not inserted.
+#
+# @example
+#   bst = DSA::BinarySearchTree.new
+#   bst.insert(5).insert(3).insert(7).insert(1).insert(4)
+#   bst.search(3)       # => true
+#   bst.min             # => 1
+#   bst.max             # => 7
+#   bst.inorder         # => [1, 3, 4, 5, 7]
+#   bst.preorder        # => [5, 3, 1, 4, 7]
+#   bst.postorder       # => [1, 4, 3, 7, 5]
+#   bst.delete(3)
+class DSA::BinarySearchTree
+  # Internal node structure for the binary search tree.
+  #
+  # @!attribute [rw] val
+  #   @return [Comparable] the value stored in the node
+  # @!attribute [rw] left
+  #   @return [Node, nil] the left child node
+  # @!attribute [rw] right
+  #   @return [Node, nil] the right child node
+  Node = Struct.new(:val, :left, :right, keyword_init: true)
 
-    def initialize
-      @root = nil
-      @size = 0
-    end
-
-    def insert(val)
-      @root, added = insert_recursive(@root, val)
-      @size += 1 if added
-      self
-    end
-
-    def search(val)
-      !!find_node(@root, val)
-    end
+  # Initialize a new empty binary search tree.
+  #
+  # @return [DSA::BinarySearchTree] a new empty tree
+  def initialize
+    @root = nil
+    @size = 0
+  end
 
-    def delete(val)
-      @root, deleted = delete_recursive(@root, val)
-      @size -= 1 if deleted
-      deleted
-    end
+  # Inserts a value into the tree. Duplicates are ignored.
+  #
+  # @param val [Comparable] the value to insert
+  # @return [DSA::BinarySearchTree] self for method chaining
+  # @example
+  #   bst.insert(5).insert(3).insert(7)
+  def insert(val)
+    @root, added = insert_recursive(@root, val)
+    @size += 1 if added
+    self
+  end
 
-    def min
-      raise IndexError, "tree is empty" if empty?
-      find_min(@root).val
-    end
+  # Searches for a value in the tree.
+  #
+  # @param val [Comparable] the value to search for
+  # @return [Boolean] true if the value exists in the tree
+  # @example
+  #   bst.insert(5)
+  #   bst.search(5)  # => true
+  #   bst.search(3)  # => false
+  def search(val)
+    !!find_node(@root, val)
+  end
 
-    def max
-      raise IndexError, "tree is empty" if empty?
-      find_max(@root).val
-    end
+  # Deletes a value from the tree if it exists.
+  #
+  # @param val [Comparable] the value to delete
+  # @return [Boolean] true if the value was deleted, false if not found
+  # @example
+  #   bst.insert(5).insert(3)
+  #   bst.delete(3)  # => true
+  #   bst.delete(8)  # => false
+  def delete(val)
+    @root, deleted = delete_recursive(@root, val)
+    @size -= 1 if deleted
+    deleted
+  end
 
-    def inorder
-      return [] if empty?
-      result = []
-      traverse_inorder(@root, result)
-      result
-    end
+  # Returns the minimum value in the tree.
+  #
+  # @return [Comparable] the minimum value
+  # @raise [IndexError] if the tree is empty
+  # @example
+  #   bst.insert(5).insert(3).insert(1)
+  #   bst.min  # => 1
+  def min
+    raise IndexError, "tree is empty" if empty?
+    find_min(@root).val
+  end
 
-    def preorder
-      return [] if empty?
-      result = []
-      traverse_preorder(@root, result)
-      result
-    end
+  # Returns the maximum value in the tree.
+  #
+  # @return [Comparable] the maximum value
+  # @raise [IndexError] if the tree is empty
+  # @example
+  #   bst.insert(5).insert(3).insert(7)
+  #   bst.max  # => 7
+  def max
+    raise IndexError, "tree is empty" if empty?
+    find_max(@root).val
+  end
 
-    def postorder
-      return [] if empty?
-      result = []
-      traverse_postorder(@root, result)
-      result
-    end
+  # Returns an array of values in inorder traversal (left, root, right).
+  #
+  # @return [Array<Comparable>] values in inorder sequence (sorted order)
+  # @example
+  #   bst.insert(5).insert(3).insert(7)
+  #   bst.inorder  # => [3, 5, 7]
+  def inorder
+    return [] if empty?
+    result = []
+    traverse_inorder(@root, result)
+    result
+  end
 
-    def size
-      @size
-    end
+  # Returns an array of values in preorder traversal (root, left, right).
+  #
+  # @return [Array<Comparable>] values in preorder sequence
+  # @example
+  #   bst.insert(5).insert(3).insert(7)
+  #   bst.preorder  # => [5, 3, 7]
+  def preorder
+    return [] if empty?
+    result = []
+    traverse_preorder(@root, result)
+    result
+  end
 
-    def empty?
-      @size == 0
-    end
+  # Returns an array of values in postorder traversal (left, right, root).
+  #
+  # @return [Array<Comparable>] values in postorder sequence
+  # @example
+  #   bst.insert(5).insert(3).insert(7)
+  #   bst.postorder  # => [3, 7, 5]
+  def postorder
+    return [] if empty?
+    result = []
+    traverse_postorder(@root, result)
+    result
+  end
 
-    def to_a
-      inorder
-    end
+  # Returns the number of elements in the tree.
+  #
+  # @return [Integer] the number of elements
+  # @example
+  #   bst.insert(5).insert(3)
+  #   bst.size  # => 2
+  def size
+    @size
+  end
 
-    private
+  # Checks if the tree is empty.
+  #
+  # @return [Boolean] true if the tree contains no elements
+  # @example
+  #   bst = DSA::BinarySearchTree.new
+  #   bst.empty?  # => true
+  def empty?
+    @size == 0
+  end
 
-    def insert_recursive(node, val)
-      if node.nil?
-        return [Node.new(val: val, left: nil, right: nil), true]
-      end
+  # Returns a defensive copy of the tree as an array (inorder traversal).
+  #
+  # @return [Array<Comparable>] an array of values in sorted order
+  # @example
+  #   bst.insert(5).insert(3).insert(7)
+  #   bst.to_a  # => [3, 5, 7]
+  def to_a
+    inorder
+  end
 
-      if val < node.val
-        node.left, added = insert_recursive(node.left, val)
-      elsif val > node.val
-        node.right, added = insert_recursive(node.right, val)
-      else
-        added = false
-      end
+  private
 
-      [node, added]
+  # Recursively inserts a value into the tree.
+  #
+  # @param node [Node, nil] the current node being examined
+  # @param val [Comparable] the value to insert
+  # @return [Array] tuple of (updated node, whether a new node was added)
+  def insert_recursive(node, val)
+    if node.nil?
+      return [Node.new(val: val, left: nil, right: nil), true]
     end
 
-    def find_node(node, val)
-      return nil unless node
-      return node if node.val == val
-
-      if val < node.val
-        find_node(node.left, val)
-      else
-        find_node(node.right, val)
-      end
+    if val < node.val
+      node.left, added = insert_recursive(node.left, val)
+    elsif val > node.val
+      node.right, added = insert_recursive(node.right, val)
+    else
+      added = false
     end
 
-    def delete_recursive(node, val)
-      return [nil, false] unless node
+    [node, added]
+  end
 
-      if val < node.val
-        node.left, deleted = delete_recursive(node.left, val)
-      elsif val > node.val
-        node.right, deleted = delete_recursive(node.right, val)
-      else
-        deleted = true
-        return [delete_node(node), true]
-      end
+  # Finds a node with the given value.
+  #
+  # @param node [Node, nil] the current node being examined
+  # @param val [Comparable] the value to find
+  # @return [Node, nil] the node if found, nil otherwise
+  def find_node(node, val)
+    return nil unless node
+    return node if node.val == val
 
-      [node, deleted]
+    if val < node.val
+      find_node(node.left, val)
+    else
+      find_node(node.right, val)
     end
+  end
 
-    def delete_node(node)
-      return node.right unless node.left
-      return node.left unless node.right
+  # Recursively deletes a value from the tree.
+  #
+  # @param node [Node, nil] the current node being examined
+  # @param val [Comparable] the value to delete
+  # @return [Array] tuple of (updated node, whether the value was deleted)
+  def delete_recursive(node, val)
+    return [nil, false] unless node
 
-      successor = find_min(node.right)
-      node.val = successor.val
-      node.right, _ = delete_recursive(node.right, successor.val)
-      node
+    if val < node.val
+      node.left, deleted = delete_recursive(node.left, val)
+    elsif val > node.val
+      node.right, deleted = delete_recursive(node.right, val)
+    else
+      deleted = true
+      return [delete_node(node), true]
     end
 
-    def find_min(node)
-      node = node.left while node.left
-      node
-    end
+    [node, deleted]
+  end
 
-    def find_max(node)
-      node = node.right while node.right
-      node
-    end
+  # Handles the three cases for node deletion.
+  #
+  # @param node [Node] the node to delete
+  # @return [Node, nil] the replacement node
+  def delete_node(node)
+    return node.right unless node.left
+    return node.left unless node.right
 
-    def traverse_inorder(node, result)
-      return unless node
-      traverse_inorder(node.left, result)
-      result << node.val
-      traverse_inorder(node.right, result)
-    end
+    successor = find_min(node.right)
+    node.val = successor.val
+    node.right, _ = delete_recursive(node.right, successor.val)
+    node
+  end
 
-    def traverse_preorder(node, result)
-      return unless node
-      result << node.val
-      traverse_preorder(node.left, result)
-      traverse_preorder(node.right, result)
-    end
+  # Finds the node with the minimum value in a subtree.
+  #
+  # @param node [Node] the root of the subtree
+  # @return [Node] the node with the minimum value
+  def find_min(node)
+    node = node.left while node.left
+    node
+  end
 
-    def traverse_postorder(node, result)
-      return unless node
-      traverse_postorder(node.left, result)
-      traverse_postorder(node.right, result)
-      result << node.val
-    end
+  # Finds the node with the maximum value in a subtree.
+  #
+  # @param node [Node] the root of the subtree
+  # @return [Node] the node with the maximum value
+  def find_max(node)
+    node = node.right while node.right
+    node
+  end
+
+  # Recursively traverses the tree in inorder.
+  #
+  # @param node [Node, nil] the current node
+  # @param result [Array] the array to accumulate values
+  def traverse_inorder(node, result)
+    return unless node
+    traverse_inorder(node.left, result)
+    result << node.val
+    traverse_inorder(node.right, result)
+  end
+
+  # Recursively traverses the tree in preorder.
+  #
+  # @param node [Node, nil] the current node
+  # @param result [Array] the array to accumulate values
+  def traverse_preorder(node, result)
+    return unless node
+    result << node.val
+    traverse_preorder(node.left, result)
+    traverse_preorder(node.right, result)
+  end
+
+  # Recursively traverses the tree in postorder.
+  #
+  # @param node [Node, nil] the current node
+  # @param result [Array] the array to accumulate values
+  def traverse_postorder(node, result)
+    return unless node
+    traverse_postorder(node.left, result)
+    traverse_postorder(node.right, result)
+    result << node.val
   end
 end

data/lib/dsa-ruby/deque.rb

@@ -1,57 +1,138 @@
-module DSA
-  class Deque
-    def initialize
-      @deque = []
-      @head = 0
-    end
-
-    def push_front(val)
-      @deque.unshift(val)
-      self
-    end
-
-    def push_back(val)
-      @deque.push(val)
-      self
-    end
-
-    def pop_front
-      raise IndexError, "deque is empty" if empty?
-      @deque.shift
-    end
-
-    def pop_back
-      raise IndexError, "deque is empty" if empty?
-      @deque.pop
-    end
-
-    def front
-      raise IndexError, "deque is empty" if empty?
-      @deque.first
-    end
-
-    def back
-      raise IndexError, "deque is empty" if empty?
-      @deque.last
-    end
-
-    def size
-      @deque.size
-    end
-
-    def empty?
-      @deque.empty?
-    end
-
-    def to_a
-      @deque.dup
-    end
-
-    include Enumerable
-
-    def each(&block)
-      return enum_for(:each) unless block_given?
-      @deque.each(&block)
-    end
+# DSA::Deque - Double-ended queue data structure.
+#
+# Supports efficient insertion and removal from both ends.
+# Includes Enumerable for functional-style operations.
+#
+# @example
+#   dq = DSA::Deque.new
+#   dq.push_front(1).push_back(2)
+#   dq.pop_front   # => 1
+#   dq.pop_back    # => 2
+#
+#   # Enumerable support
+#   dq.push_back(1).push_back(2).push_back(3)
+#   dq.map { |x| x * 2 }  # => [2, 4, 6]
+class DSA::Deque
+  # Initialize a new empty deque.
+  #
+  # @return [DSA::Deque] a new empty deque
+  def initialize
+    @deque = []
+    @head = 0
+  end
+
+  # Inserts a value at the front of the deque.
+  #
+  # @param val [Object] the value to insert
+  # @return [DSA::Deque] self for method chaining
+  # @example
+  #   dq.push_front(1).push_front(2)
+  def push_front(val)
+    @deque.unshift(val)
+    self
+  end
+
+  # Inserts a value at the back of the deque.
+  #
+  # @param val [Object] the value to insert
+  # @return [DSA::Deque] self for method chaining
+  # @example
+  #   dq.push_back(1).push_back(2)
+  def push_back(val)
+    @deque.push(val)
+    self
+  end
+
+  # Removes and returns the value at the front of the deque.
+  #
+  # @return [Object] the value at the front
+  # @raise [IndexError] if the deque is empty
+  # @example
+  #   dq.push_back(1).push_back(2)
+  #   dq.pop_front  # => 1
+  def pop_front
+    raise IndexError, "deque is empty" if empty?
+    @deque.shift
+  end
+
+  # Removes and returns the value at the back of the deque.
+  #
+  # @return [Object] the value at the back
+  # @raise [IndexError] if the deque is empty
+  # @example
+  #   dq.push_back(1).push_back(2)
+  #   dq.pop_back  # => 2
+  def pop_back
+    raise IndexError, "deque is empty" if empty?
+    @deque.pop
+  end
+
+  # Returns the value at the front of the deque without removing it.
+  #
+  # @return [Object] the value at the front
+  # @raise [IndexError] if the deque is empty
+  # @example
+  #   dq.push_back(1).push_back(2)
+  #   dq.front  # => 1
+  def front
+    raise IndexError, "deque is empty" if empty?
+    @deque.first
+  end
+
+  # Returns the value at the back of the deque without removing it.
+  #
+  # @return [Object] the value at the back
+  # @raise [IndexError] if the deque is empty
+  # @example
+  #   dq.push_back(1).push_back(2)
+  #   dq.back  # => 2
+  def back
+    raise IndexError, "deque is empty" if empty?
+    @deque.last
+  end
+
+  # Returns the number of elements in the deque.
+  #
+  # @return [Integer] the number of elements
+  # @example
+  #   dq.push_back(1).push_back(2)
+  #   dq.size  # => 2
+  def size
+    @deque.size
+  end
+
+  # Checks if the deque is empty.
+  #
+  # @return [Boolean] true if the deque contains no elements
+  # @example
+  #   dq = DSA::Deque.new
+  #   dq.empty?  # => true
+  def empty?
+    @deque.empty?
+  end
+
+  # Returns a defensive copy of the deque as an array.
+  #
+  # @return [Array] an array containing all elements (front to back order)
+  # @example
+  #   dq.push_back(1).push_back(2).push_back(3)
+  #   dq.to_a  # => [1, 2, 3]
+  def to_a
+    @deque.dup
+  end
+
+  # Includes Enumerable for functional-style operations like map, select, etc.
+  include Enumerable
+
+  # Yields each element in the deque from front to back.
+  #
+  # @yield [val] yields each value to the block
+  # @return [Enumerator] if no block given
+  # @example
+  #   dq.push_back(1).push_back(2).push_back(3)
+  #   dq.each { |x| puts x }  # prints 1, 2, 3
+  def each(&block)
+    return enum_for(:each) unless block_given?
+    @deque.each(&block)
   end
 end