dsa-ruby 1.0.0 → 1.0.2

data/lib/dsa-ruby/stack.rb

@@ -1,34 +1,80 @@
-module DSA
-  class Stack
-    def initialize
-      @elements = []
-    end
+# DSA::Stack - Last-In-First-Out (LIFO) data structure.
+#
+# @example
+#   stack = DSA::Stack.new
+#   stack.push(1).push(2).push(3)
+#   stack.pop  # => 3
+#   stack.peek # => 2
+class DSA::Stack
+  # Initialize a new empty stack.
+  #
+  # @return [DSA::Stack] a new empty stack
+  def initialize
+    @elements = []
+  end
 
-    def push(val)
-      @elements.push(val)
-      self
-    end
+  # Pushes a value onto the top of the stack.
+  #
+  # @param val [Object] the value to push onto the stack
+  # @return [DSA::Stack] self for method chaining
+  # @example Push with chaining
+  #   stack.push(1).push(2).push(3)
+  def push(val)
+    @elements.push(val)
+    self
+  end
 
-    def pop
-      raise IndexError, "stack is empty" if empty?
-      @elements.pop
-    end
+  # Removes and returns the value at the top of the stack.
+  #
+  # @return [Object] the value at the top of the stack
+  # @raise [IndexError] if the stack is empty
+  # @example
+  #   stack.push(1).push(2)
+  #   stack.pop  # => 2
+  def pop
+    raise IndexError, "stack is empty" if empty?
+    @elements.pop
+  end
 
-    def peek
-      raise IndexError, "stack is empty" if empty?
-      @elements.last
-    end
+  # Returns the value at the top of the stack without removing it.
+  #
+  # @return [Object] the value at the top of the stack
+  # @raise [IndexError] if the stack is empty
+  # @example
+  #   stack.push(1).push(2)
+  #   stack.peek  # => 2
+  def peek
+    raise IndexError, "stack is empty" if empty?
+    @elements.last
+  end
 
-    def size
-      @elements.size
-    end
+  # Returns the number of elements in the stack.
+  #
+  # @return [Integer] the number of elements
+  # @example
+  #   stack.push(1).push(2)
+  #   stack.size  # => 2
+  def size
+    @elements.size
+  end
 
-    def empty?
-      @elements.empty?
-    end
+  # Checks if the stack is empty.
+  #
+  # @return [Boolean] true if the stack contains no elements
+  # @example
+  #   stack = DSA::Stack.new
+  #   stack.empty?  # => true
+  def empty?
+    @elements.empty?
+  end
 
-    def to_a
-      @elements.dup
-    end
+  # Returns a defensive copy of the stack as an array.
+  #
+  # @return [Array] an array containing all elements in the stack (top to bottom order)
+  # @example
+  #   stack.push(1).push(2).push(3)
+  #   stack.to_a  # => [3, 2, 1]
+  def to_a
+    @elements.dup
   end
 end

data/lib/dsa-ruby/trie.rb

@@ -1,70 +1,128 @@
-module DSA
-  class Trie
-    Node = Struct.new(:children, :word_end, keyword_init: true) do
-      def initialize
-        super(children: {}, word_end: false)
-      end
-    end
-
+# DSA::Trie - A prefix tree (trie) data structure for string storage and lookup.
+#
+# Efficient for prefix-based searches and word lookups.
+#
+# @example
+#   trie = DSA::Trie.new
+#   trie.insert("apple")
+#   trie.search("apple")     # => true
+#   trie.search("app")       # => false
+#   trie.starts_with("app")  # => true
+#   trie.delete("apple")
+class DSA::Trie
+  # Internal node structure for the trie.
+  #
+  # @!attribute [rw] children
+  #   @return [Hash] map of character to child node
+  # @!attribute [rw] word_end
+  #   @return [Boolean] true if this node marks the end of a word
+  Node = Struct.new(:children, :word_end, keyword_init: true) do
     def initialize
-      @root = Node.new
+      super(children: {}, word_end: false)
     end
+  end
 
-    def insert(word)
-      node = @root
-      word.each_char do |char|
-        node.children[char] ||= Node.new
-        node = node.children[char]
-      end
-      node.word_end = true
-      self
-    end
+  # Initialize a new empty trie.
+  #
+  # @return [DSA::Trie] a new empty trie
+  def initialize
+    @root = Node.new
+  end
 
-    def search(word)
-      node = find_node(word)
-      !!(node && node.word_end)
+  # Inserts a word into the trie.
+  #
+  # @param word [String] the word to insert
+  # @return [DSA::Trie] self for method chaining
+  # @example
+  #   trie.insert("apple").insert("banana")
+  def insert(word)
+    node = @root
+    word.each_char do |char|
+      node.children[char] ||= Node.new
+      node = node.children[char]
     end
+    node.word_end = true
+    self
+  end
 
-    def starts_with(prefix)
-      !!find_node(prefix)
-    end
+  # Searches for an exact word in the trie.
+  #
+  # @param word [String] the word to search for
+  # @return [Boolean] true if the word exists in the trie
+  # @example
+  #   trie.insert("apple")
+  #   trie.search("apple")  # => true
+  #   trie.search("app")    # => false
+  def search(word)
+    node = find_node(word)
+    !!(node && node.word_end)
+  end
 
-    def delete(word)
-      delete_recursive(@root, word, 0)
-    end
+  # Checks if any word in the trie starts with the given prefix.
+  #
+  # @param prefix [String] the prefix to search for
+  # @return [Boolean] true if any word starts with the prefix
+  # @example
+  #   trie.insert("apple")
+  #   trie.starts_with("app")  # => true
+  #   trie.starts_with("ban")  # => false
+  def starts_with(prefix)
+    !!find_node(prefix)
+  end
 
-    private
+  # Deletes a word from the trie if it exists.
+  #
+  # @param word [String] the word to delete
+  # @return [Boolean] true if the word was deleted, false if not found
+  # @example
+  #   trie.insert("apple")
+  #   trie.delete("apple")  # => true
+  #   trie.delete("banana") # => false
+  def delete(word)
+    delete_recursive(@root, word, 0)
+  end
 
-    def find_node(word)
-      node = @root
-      word.each_char do |char|
-        return nil unless node.children[char]
-        node = node.children[char]
-      end
-      node
-    end
+  private
 
-    def delete_recursive(node, word, index)
-      return false unless node
+  # Finds the node corresponding to a given word/prefix.
+  #
+  # @param word [String] the word or prefix to find
+  # @return [Node, nil] the node if found, nil otherwise
+  def find_node(word)
+    node = @root
+    word.each_char do |char|
+      return nil unless node.children[char]
+      node = node.children[char]
+    end
+    node
+  end
 
-      if index == word.length
-        return false unless node.word_end
+  # Recursively deletes a word from the trie.
+  #
+  # @param node [Node] the current node being examined
+  # @param word [String] the word to delete
+  # @param index [Integer] the current character index in the word
+  # @return [Boolean] true if the node should be deleted (no children and not word end)
+  def delete_recursive(node, word, index)
+    return false unless node
 
-        node.word_end = false
-        return node.children.empty?
-      end
+    if index == word.length
+      return false unless node.word_end
 
-      char = word[index]
-      return false unless node.children[char]
+      node.word_end = false
+      return node.children.empty?
+    end
 
-      should_delete = delete_recursive(node.children[char], word, index + 1)
+    char = word[index]
+    return false unless node.children[char]
 
-      if should_delete
-        node.children.delete(char)
-        return !node.word_end && node.children.empty?
-      end
+    should_delete = delete_recursive(node.children[char], word, index + 1)
 
-      false
+    if should_delete
+      node.children.delete(char)
+      return !node.word_end && node.children.empty?
     end
+
+    false
   end
 end

data/lib/dsa-ruby/union_find.rb

@@ -1,50 +1,105 @@
-module DSA
-  class UnionFind
-    def initialize(n)
-      @parent = (0...n).to_a
-      @rank = Array.new(n, 0)
-      @count = n
-    end
-
-    def find(x)
-      raise IndexError, "index out of bounds" if x < 0 || x >= @parent.size
+# DSA::UnionFind - Disjoint-set data structure with path compression and union by rank.
+#
+# Tracks a set of elements partitioned into disjoint subsets. Supports efficient
+# union and find operations.
+#
+# @example
+#   uf = DSA::UnionFind.new(10)
+#   uf.union(1, 2)
+#   uf.union(2, 3)
+#   uf.connected?(1, 3)  # => true
+#   uf.count              # => 8 (started with 10, merged 2 pairs)
+class DSA::UnionFind
+  # Initialize a new UnionFind structure with n disjoint sets.
+  #
+  # @param n [Integer] the number of elements (0 to n-1), each in its own set
+  # @return [DSA::UnionFind] a new UnionFind structure
+  # @example
+  #   uf = DSA::UnionFind.new(10)
+  def initialize(n)
+    @parent = (0...n).to_a
+    @rank = Array.new(n, 0)
+    @count = n
+  end
 
-      @parent[x] = find(@parent[x]) if @parent[x] != x
-      @parent[x]
-    end
+  # Finds the root of the set containing element x, with path compression.
+  #
+  # @param x [Integer] the element to find
+  # @return [Integer] the root of the set containing x
+  # @raise [IndexError] if x is out of bounds
+  # @example
+  #   uf.union(1, 2)
+  #   uf.find(2)  # => root of the set containing 1 and 2
+  def find(x)
+    raise IndexError, "index out of bounds" if x < 0 || x >= @parent.size
 
-    def union(x, y)
-      raise IndexError, "index out of bounds" if x < 0 || x >= @parent.size
-      raise IndexError, "index out of bounds" if y < 0 || y >= @parent.size
+    @parent[x] = find(@parent[x]) if @parent[x] != x
+    @parent[x]
+  end
 
-      root_x = find(x)
-      root_y = find(y)
+  # Merges the sets containing elements x and y.
+  #
+  # @param x [Integer] the first element
+  # @param y [Integer] the second element
+  # @return [Boolean] true if the sets were merged, false if already connected
+  # @raise [IndexError] if x or y is out of bounds
+  # @example
+  #   uf.union(1, 2)  # => true
+  #   uf.union(2, 3)  # => true
+  #   uf.union(1, 3)  # => false (already connected)
+  def union(x, y)
+    raise IndexError, "index out of bounds" if x < 0 || x >= @parent.size
+    raise IndexError, "index out of bounds" if y < 0 || y >= @parent.size
 
-      return false if root_x == root_y
+    root_x = find(x)
+    root_y = find(y)
 
-      if @rank[root_x] < @rank[root_y]
-        @parent[root_x] = root_y
-      elsif @rank[root_x] > @rank[root_y]
-        @parent[root_y] = root_x
-      else
-        @parent[root_y] = root_x
-        @rank[root_x] += 1
-      end
+    return false if root_x == root_y
 
-      @count -= 1
-      true
+    if @rank[root_x] < @rank[root_y]
+      @parent[root_x] = root_y
+    elsif @rank[root_x] > @rank[root_y]
+      @parent[root_y] = root_x
+    else
+      @parent[root_y] = root_x
+      @rank[root_x] += 1
     end
 
-    def connected?(x, y)
-      find(x) == find(y)
-    end
+    @count -= 1
+    true
+  end
 
-    def count
-      @count
-    end
+  # Checks if two elements are in the same set.
+  #
+  # @param x [Integer] the first element
+  # @param y [Integer] the second element
+  # @return [Boolean] true if x and y are in the same set
+  # @example
+  #   uf.union(1, 2)
+  #   uf.connected?(1, 2)  # => true
+  #   uf.connected?(1, 3)  # => false
+  def connected?(x, y)
+    find(x) == find(y)
+  end
 
-    def size
-      @parent.size
-    end
+  # Returns the number of disjoint sets.
+  #
+  # @return [Integer] the number of disjoint sets
+  # @example
+  #   uf = DSA::UnionFind.new(10)
+  #   uf.union(1, 2)
+  #   uf.count  # => 9
+  def count
+    @count
+  end
+
+  # Returns the total number of elements.
+  #
+  # @return [Integer] the number of elements (0 to n-1)
+  # @example
+  #   uf = DSA::UnionFind.new(10)
+  #   uf.size  # => 10
+  def size
+    @parent.size
   end
 end

data/lib/dsa-ruby/version.rb

@@ -1,3 +1,10 @@
+# DSA module - Data Structures for Algorithms in Ruby
+#
+# Provides common data structures needed for coding interviews and algorithm
+# problems that are missing from Ruby's standard library.
 module DSA
-  VERSION = "1.0.0"
+  # Current version of the dsa-ruby gem.
+  #
+  # @return [String] the version string (semantic versioning)
+  VERSION = "1.0.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dsa-ruby
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
 platform: ruby
 authors:
 - You
@@ -23,6 +23,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 description: Provides MinHeap, MaxHeap, PriorityQueue, Deque, Trie, UnionFind, and
   LinkedList — data structures commonly needed for coding interviews but missing from
   Ruby's stdlib.