dsa-ruby 1.0.0 → 1.0.2

data/lib/dsa-ruby/linked_list.rb

@@ -1,17 +1,43 @@
 module DSA
+  # Linked list data structures module.
+  #
+  # Provides both singly and doubly linked list implementations.
   module LinkedList
+    # Node for a singly linked list.
+    #
+    # @!attribute [rw] val
+    #   @return [Object] the value stored in the node
+    # @!attribute [rw] next
+    #   @return [Node, nil] the next node in the list
     class Node
       attr_accessor :val, :next
 
+      # Initialize a new singly linked list node.
+      #
+      # @param val [Object] the value to store
+      # @param nxt [Node, nil] the next node (default: nil)
       def initialize(val = 0, nxt = nil)
         @val = val
         @next = nxt
       end
     end
 
+    # Node for a doubly linked list.
+    #
+    # @!attribute [rw] val
+    #   @return [Object] the value stored in the node
+    # @!attribute [rw] next
+    #   @return [DoublyNode, nil] the next node in the list
+    # @!attribute [rw] prev
+    #   @return [DoublyNode, nil] the previous node in the list
     class DoublyNode
       attr_accessor :val, :next, :prev
 
+      # Initialize a new doubly linked list node.
+      #
+      # @param val [Object] the value to store
+      # @param nxt [DoublyNode, nil] the next node (default: nil)
+      # @param prev [DoublyNode, nil] the previous node (default: nil)
       def initialize(val = 0, nxt = nil, prev = nil)
         @val = val
         @next = nxt
@@ -19,18 +45,48 @@ module DSA
       end
     end
 
+    # DSA::LinkedList::Singly - Singly linked list implementation.
+    #
+    # Each node points only to the next node. Supports push (prepend),
+    # append, pop (from front), delete, find, and reverse!.
+    # Includes Enumerable for functional-style operations.
+    #
+    # @example
+    #   list = DSA::LinkedList::Singly.new
+    #   list.push(1).push(2).push(3)
+    #   list.pop        # => 3
+    #   list.to_a       # => [2, 1]
+    #   list.reverse!
+    #   list.to_a       # => [1, 2]
     class Singly
+      # Initialize a new empty singly linked list.
+      #
+      # @return [DSA::LinkedList::Singly] a new empty list
       def initialize
         @head = nil
         @size = 0
       end
 
+      # Prepends a value to the front of the list.
+      #
+      # @param val [Object] the value to prepend
+      # @return [DSA::LinkedList::Singly] self for method chaining
+      # @example
+      #   list.push(2).push(1)
+      #   list.to_a  # => [1, 2]
       def push(val)
         @head = Node.new(val, @head)
         @size += 1
         self
       end
 
+      # Appends a value to the end of the list.
+      #
+      # @param val [Object] the value to append
+      # @return [DSA::LinkedList::Singly] self for method chaining
+      # @example
+      #   list.append(1).append(2)
+      #   list.to_a  # => [1, 2]
       def append(val)
         new_node = Node.new(val)
         if @head.nil?
@@ -44,6 +100,13 @@ module DSA
         self
       end
 
+      # Removes and returns the value at the front of the list.
+      #
+      # @return [Object] the value at the front
+      # @raise [IndexError] if the list is empty
+      # @example
+      #   list.push(1).push(2)
+      #   list.pop  # => 2
       def pop
         raise IndexError, "list is empty" unless @head
 
@@ -53,11 +116,26 @@ module DSA
         val
       end
 
+      # Returns the value at the front of the list without removing it.
+      #
+      # @return [Object] the value at the front
+      # @raise [IndexError] if the list is empty
+      # @example
+      #   list.push(1).push(2)
+      #   list.peek  # => 2
       def peek
         raise IndexError, "list is empty" unless @head
         @head.val
       end
 
+      # Deletes the first occurrence of a value from the list.
+      #
+      # @param val [Object] the value to delete
+      # @return [Boolean] true if the value was found and deleted
+      # @example
+      #   list.push(1).push(2).push(3)
+      #   list.delete(2)  # => true
+      #   list.delete(5)  # => false
       def delete(val)
         return false unless @head
 
@@ -80,6 +158,14 @@ module DSA
         false
       end
 
+      # Finds the first node with the given value.
+      #
+      # @param val [Object] the value to find
+      # @return [Node, nil] the node if found, nil otherwise
+      # @example
+      #   list.push(1).push(2)
+      #   list.find(2)  # => #<Node @val=2>
+      #   list.find(5)  # => nil
       def find(val)
         node = @head
         while node
@@ -89,6 +175,13 @@ module DSA
         nil
       end
 
+      # Reverses the list in-place.
+      #
+      # @return [DSA::LinkedList::Singly] self for method chaining
+      # @example
+      #   list.push(1).push(2).push(3)
+      #   list.reverse!
+      #   list.to_a  # => [1, 2, 3]
       def reverse!
         return self unless @head
 
@@ -104,14 +197,32 @@ module DSA
         self
       end
 
+      # Returns the number of elements in the list.
+      #
+      # @return [Integer] the number of elements
+      # @example
+      #   list.push(1).push(2)
+      #   list.size  # => 2
       def size
         @size
       end
 
+      # Checks if the list is empty.
+      #
+      # @return [Boolean] true if the list contains no elements
+      # @example
+      #   list = DSA::LinkedList::Singly.new
+      #   list.empty?  # => true
       def empty?
         @size == 0
       end
 
+      # Returns an array of all values in the list (front to back).
+      #
+      # @return [Array] an array of values in list order
+      # @example
+      #   list.push(1).push(2).push(3)
+      #   list.to_a  # => [3, 2, 1]
       def to_a
         result = []
         node = @head
@@ -122,8 +233,16 @@ module DSA
         result
       end
 
+      # Includes Enumerable for functional-style operations like map, select, etc.
       include Enumerable
 
+      # Yields each value in the list from front to back.
+      #
+      # @yield [val] yields each value to the block
+      # @return [Enumerator] if no block given
+      # @example
+      #   list.push(1).push(2).push(3)
+      #   list.each { |x| puts x }  # prints 3, 2, 1
       def each(&block)
         return enum_for(:each) unless block_given?
         node = @head
@@ -134,13 +253,35 @@ module DSA
       end
     end
 
+    # DSA::LinkedList::Doubly - Doubly linked list implementation.
+    #
+    # Each node points to both the next and previous nodes.
+    # Supports push_front, push_back, pop_front, pop_back, delete, and find.
+    # Includes Enumerable for functional-style operations.
+    #
+    # @example
+    #   dll = DSA::LinkedList::Doubly.new
+    #   dll.push_back(1).push_back(2).push_back(3)
+    #   dll.pop_front   # => 1
+    #   dll.pop_back    # => 3
+    #   dll.to_a        # => [2]
     class Doubly
+      # Initialize a new empty doubly linked list.
+      #
+      # @return [DSA::LinkedList::Doubly] a new empty list
       def initialize
         @head = nil
         @tail = nil
         @size = 0
       end
 
+      # Inserts a value at the front of the list.
+      #
+      # @param val [Object] the value to insert
+      # @return [DSA::LinkedList::Doubly] self for method chaining
+      # @example
+      #   dll.push_front(2).push_front(1)
+      #   dll.to_a  # => [1, 2]
       def push_front(val)
         node = DoublyNode.new(val, @head, nil)
         @head.prev = node if @head
@@ -150,6 +291,13 @@ module DSA
         self
       end
 
+      # Inserts a value at the back of the list.
+      #
+      # @param val [Object] the value to insert
+      # @return [DSA::LinkedList::Doubly] self for method chaining
+      # @example
+      #   dll.push_back(1).push_back(2)
+      #   dll.to_a  # => [1, 2]
       def push_back(val)
         node = DoublyNode.new(val, nil, @tail)
         @tail.next = node if @tail
@@ -159,6 +307,13 @@ module DSA
         self
       end
 
+      # Removes and returns the value at the front of the list.
+      #
+      # @return [Object] the value at the front
+      # @raise [IndexError] if the list is empty
+      # @example
+      #   dll.push_back(1).push_back(2)
+      #   dll.pop_front  # => 1
       def pop_front
         raise IndexError, "list is empty" unless @head
 
@@ -170,6 +325,13 @@ module DSA
         val
       end
 
+      # Removes and returns the value at the back of the list.
+      #
+      # @return [Object] the value at the back
+      # @raise [IndexError] if the list is empty
+      # @example
+      #   dll.push_back(1).push_back(2)
+      #   dll.pop_back  # => 2
       def pop_back
         raise IndexError, "list is empty" unless @tail
 
@@ -181,16 +343,38 @@ module DSA
         val
       end
 
+      # Returns the value at the front of the list without removing it.
+      #
+      # @return [Object] the value at the front
+      # @raise [IndexError] if the list is empty
+      # @example
+      #   dll.push_back(1).push_back(2)
+      #   dll.front  # => 1
       def front
         raise IndexError, "list is empty" unless @head
         @head.val
       end
 
+      # Returns the value at the back of the list without removing it.
+      #
+      # @return [Object] the value at the back
+      # @raise [IndexError] if the list is empty
+      # @example
+      #   dll.push_back(1).push_back(2)
+      #   dll.back  # => 2
       def back
         raise IndexError, "list is empty" unless @tail
         @tail.val
       end
 
+      # Deletes the first occurrence of a value from the list.
+      #
+      # @param val [Object] the value to delete
+      # @return [Boolean] true if the value was found and deleted
+      # @example
+      #   dll.push_back(1).push_back(2).push_back(3)
+      #   dll.delete(2)  # => true
+      #   dll.delete(5)  # => false
       def delete(val)
         node = @head
         while node
@@ -207,6 +391,14 @@ module DSA
         false
       end
 
+      # Finds the first node with the given value.
+      #
+      # @param val [Object] the value to find
+      # @return [DoublyNode, nil] the node if found, nil otherwise
+      # @example
+      #   dll.push_back(1).push_back(2)
+      #   dll.find(2)  # => #<DoublyNode @val=2>
+      #   dll.find(5)  # => nil
       def find(val)
         node = @head
         while node
@@ -216,14 +408,32 @@ module DSA
         nil
       end
 
+      # Returns the number of elements in the list.
+      #
+      # @return [Integer] the number of elements
+      # @example
+      #   dll.push_back(1).push_back(2)
+      #   dll.size  # => 2
       def size
         @size
       end
 
+      # Checks if the list is empty.
+      #
+      # @return [Boolean] true if the list contains no elements
+      # @example
+      #   dll = DSA::LinkedList::Doubly.new
+      #   dll.empty?  # => true
       def empty?
         @size == 0
       end
 
+      # Returns an array of all values in the list (front to back).
+      #
+      # @return [Array] an array of values in list order
+      # @example
+      #   dll.push_back(1).push_back(2).push_back(3)
+      #   dll.to_a  # => [1, 2, 3]
       def to_a
         result = []
         node = @head
@@ -234,8 +444,16 @@ module DSA
         result
       end
 
+      # Includes Enumerable for functional-style operations like map, select, etc.
       include Enumerable
 
+      # Yields each value in the list from front to back.
+      #
+      # @yield [val] yields each value to the block
+      # @return [Enumerator] if no block given
+      # @example
+      #   dll.push_back(1).push_back(2).push_back(3)
+      #   dll.each { |x| puts x }  # prints 1, 2, 3
       def each(&block)
         return enum_for(:each) unless block_given?
         node = @head

data/lib/dsa-ruby/priority_queue.rb

@@ -1,43 +1,109 @@
-module DSA
-  class PriorityQueue
-    def initialize(type: :min)
-      @heap = type == :min ? MinHeap.new : MaxHeap.new
-    end
-
-    def push(item, priority)
-      @counter ||= 0
-      @heap.push([priority, @counter, item])
-      @counter += 1
-      self
-    end
-
-    def pop
-      raise IndexError, "priority queue is empty" if empty?
-      _, _, item = @heap.pop
-      item
-    end
-
-    def peek
-      raise IndexError, "priority queue is empty" if empty?
-      _, _, item = @heap.peek
-      item
-    end
-
-    def priority_peek
-      raise IndexError, "priority queue is empty" if empty?
-      @heap.peek[0]
-    end
-
-    def size
-      @heap.size
-    end
-
-    def empty?
-      @heap.empty?
-    end
-
-    private
-
-    attr_reader :heap
+# DSA::PriorityQueue - A priority queue data structure.
+#
+# Uses a heap internally to provide efficient priority-based ordering.
+# Supports both min and max priority ordering.
+#
+# @example Min Priority Queue (default)
+#   pq = DSA::PriorityQueue.new(type: :min)
+#   pq.push("task_a", 3)
+#   pq.push("task_b", 1)
+#   pq.push("task_c", 2)
+#   pq.pop  # => "task_b" (lowest priority value first)
+#
+# @example Max Priority Queue
+#   pq = DSA::PriorityQueue.new(type: :max)
+#   pq.push("task_a", 3)
+#   pq.push("task_b", 1)
+#   pq.pop  # => "task_a" (highest priority value first)
+class DSA::PriorityQueue
+  # Initialize a new priority queue.
+  #
+  # @param type [Symbol] :min for minimum priority first, :max for maximum priority first
+  # @return [DSA::PriorityQueue] a new priority queue
+  # @example
+  #   DSA::PriorityQueue.new          # min priority queue
+  #   DSA::PriorityQueue.new(type: :max)  # max priority queue
+  def initialize(type: :min)
+    @heap = type == :min ? MinHeap.new : MaxHeap.new
   end
+
+  # Inserts an item with a given priority.
+  #
+  # @param item [Object] the item to insert
+  # @param priority [Comparable] the priority value (lower = higher priority in min queue)
+  # @return [DSA::PriorityQueue] self for method chaining
+  # @example
+  #   pq.push("task", 5).push("another", 3)
+  def push(item, priority)
+    @counter ||= 0
+    @heap.push([priority, @counter, item])
+    @counter += 1
+    self
+  end
+
+  # Removes and returns the item with the highest/lowest priority.
+  #
+  # @return [Object] the item with the highest priority (max) or lowest (min)
+  # @raise [IndexError] if the priority queue is empty
+  # @example
+  #   pq.push("task_a", 3)
+  #   pq.push("task_b", 1)
+  #   pq.pop  # => "task_b"
+  def pop
+    raise IndexError, "priority queue is empty" if empty?
+    _, _, item = @heap.pop
+    item
+  end
+
+  # Returns the item with the highest/lowest priority without removing it.
+  #
+  # @return [Object] the item with the highest priority (max) or lowest (min)
+  # @raise [IndexError] if the priority queue is empty
+  # @example
+  #   pq.push("task_a", 3)
+  #   pq.push("task_b", 1)
+  #   pq.peek  # => "task_b"
+  def peek
+    raise IndexError, "priority queue is empty" if empty?
+    _, _, item = @heap.peek
+    item
+  end
+
+  # Returns the priority value of the top item without removing it.
+  #
+  # @return [Comparable] the priority value of the top item
+  # @raise [IndexError] if the priority queue is empty
+  # @example
+  #   pq.push("task", 5)
+  #   pq.priority_peek  # => 5
+  def priority_peek
+    raise IndexError, "priority queue is empty" if empty?
+    @heap.peek[0]
+  end
+
+  # Returns the number of items in the priority queue.
+  #
+  # @return [Integer] the number of items
+  # @example
+  #   pq.push("task_a", 3).push("task_b", 1)
+  #   pq.size  # => 2
+  def size
+    @heap.size
+  end
+
+  # Checks if the priority queue is empty.
+  #
+  # @return [Boolean] true if the priority queue contains no items
+  # @example
+  #   pq = DSA::PriorityQueue.new
+  #   pq.empty?  # => true
+  def empty?
+    @heap.empty?
+  end
+
+  private
+
+  # @!attribute [r] heap
+  #   @return [DSA::MinHeap, DSA::MaxHeap] the internal heap used for priority ordering
+  attr_reader :heap
 end

data/lib/dsa-ruby/queue.rb

@@ -1,34 +1,80 @@
-module DSA
-  class Queue
-    def initialize
-      @elements = []
-    end
+# DSA::Queue - First-In-First-Out (FIFO) data structure.
+#
+# @example
+#   queue = DSA::Queue.new
+#   queue.enqueue("a").enqueue("b").enqueue("c")
+#   queue.dequeue  # => "a"
+#   queue.peek     # => "b"
+class DSA::Queue
+  # Initialize a new empty queue.
+  #
+  # @return [DSA::Queue] a new empty queue
+  def initialize
+    @elements = []
+  end
 
-    def enqueue(val)
-      @elements.push(val)
-      self
-    end
+  # Adds a value to the back of the queue.
+  #
+  # @param val [Object] the value to add to the queue
+  # @return [DSA::Queue] self for method chaining
+  # @example Enqueue with chaining
+  #   queue.enqueue("a").enqueue("b").enqueue("c")
+  def enqueue(val)
+    @elements.push(val)
+    self
+  end
 
-    def dequeue
-      raise IndexError, "queue is empty" if empty?
-      @elements.shift
-    end
+  # Removes and returns the value at the front of the queue.
+  #
+  # @return [Object] the value at the front of the queue
+  # @raise [IndexError] if the queue is empty
+  # @example
+  #   queue.enqueue("a").enqueue("b")
+  #   queue.dequeue  # => "a"
+  def dequeue
+    raise IndexError, "queue is empty" if empty?
+    @elements.shift
+  end
 
-    def peek
-      raise IndexError, "queue is empty" if empty?
-      @elements.first
-    end
+  # Returns the value at the front of the queue without removing it.
+  #
+  # @return [Object] the value at the front of the queue
+  # @raise [IndexError] if the queue is empty
+  # @example
+  #   queue.enqueue("a").enqueue("b")
+  #   queue.peek  # => "a"
+  def peek
+    raise IndexError, "queue is empty" if empty?
+    @elements.first
+  end
 
-    def size
-      @elements.size
-    end
+  # Returns the number of elements in the queue.
+  #
+  # @return [Integer] the number of elements
+  # @example
+  #   queue.enqueue("a").enqueue("b")
+  #   queue.size  # => 2
+  def size
+    @elements.size
+  end
 
-    def empty?
-      @elements.empty?
-    end
+  # Checks if the queue is empty.
+  #
+  # @return [Boolean] true if the queue contains no elements
+  # @example
+  #   queue = DSA::Queue.new
+  #   queue.empty?  # => true
+  def empty?
+    @elements.empty?
+  end
 
-    def to_a
-      @elements.dup
-    end
+  # Returns a defensive copy of the queue as an array.
+  #
+  # @return [Array] an array containing all elements in queue order (front to back)
+  # @example
+  #   queue.enqueue("a").enqueue("b").enqueue("c")
+  #   queue.to_a  # => ["a", "b", "c"]
+  def to_a
+    @elements.dup
   end
 end