dlinked 0.1.7 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91b4fd6c724736c40143c48dcc7c10a0335926cf8cbafc4e36020d7fd0ca97ed
-  data.tar.gz: db2963f5328e509eead6dd403ad4cde8cf820115db33861e8ec019c1bc56d1f5
+  metadata.gz: de491a4898093da5aac0b68079ebc40d001a60234ae752ec39250fa3d56d09d2
+  data.tar.gz: cdaf5870bba85269d949a0471a8f4481ad1786a18cf1e1f14159439b5d6235f4
 SHA512:
-  metadata.gz: 5674461e19a17fa60a0d3f3022899be02824bade1390f2b5dc7506c787b6cd4c6abee66269e3af34f0c1cbe7949874ebc56c8101e14d3b32bd3ed0e7bbb931a5
-  data.tar.gz: 38a9b833f855d57ab85a8ec3a1f74a56a090dab041a00d3618ea789b5b834ecff1a84e2eb6a30facc8d7eee5256f33c88a70df6dbc169ddaf9590d65ee30385b
+  metadata.gz: 57666858cfbccc763cc732022f017fe3739292ec72b58c4c87d699bb65ea25154c5ba04458346fed4fdf53c7fa522801e2ba1c29e8bc53ea880d6d4f31109cea
+  data.tar.gz: 2ba4f2c83fff58be2e103968482f402ac8d6c6ce1f60ca5b4256e2e9337b30248afb1de181227b2a102872307d6ea60e4faaa3d30254942b65b9bf9bb6cb92da

data/LICENSE.txt

@@ -1,7 +1,7 @@
 
 MIT License
 
-Copyright (c) 2025 [Your Name]
+Copyright (c) 2025 [DANIELE FRISANCO]
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -6,9 +6,9 @@ A fast, lightweight doubly linked list implementation for Ruby.
 
 - **Lightweight**: Minimal memory footprint using optimized node class
 - **Fast**: O(1) operations for insertion/deletion at both ends
-- **Ruby-native**: Includes Enumerable for full integration with Ruby
+- **Ruby-native**: Includes `Enumerable` for full integration with Ruby
 - **Bidirectional**: Iterate forward or backward efficiently
-
+- **LRU-Ready**: Includes the specialized `DLinked::CacheList` subclass, which integrates a hash map for O(1) LRU cache management (access, insertion, eviction).
 
 ## Installation
 
@@ -27,7 +27,7 @@ gem install dlinked
 ## Test
 
 ```bash
-bundle exec ruby test/test_d_linked_list.rb
+bundle exec rake test
 
 ```
 
@@ -189,6 +189,58 @@ list1.concat(list2)
 list1.to_a # => [1, 2, 3, 4]
 ```
 
+
+### 7. DLinked::CacheList (LRU Cache Utility)
+`DLinked::CacheList` is a specialized subclass of `DLinked::List` designed to be the backbone of a **Least Recently Used (LRU) cache**. It combines a doubly linked list with a hash map to provide **O(1)**time complexity for all critical LRU cache operations. All core key management methods have **O(1)** complexity:
+- #prepend_key(key, value) (Add as MRU)
+- #move_to_head_by_key(key) (Touch/Access)
+- #pop_key (Evict LRU)
+- #remove_by_key(key) (Remove)
+
+- **Most Recently Used (MRU)** items are at the **head** of the list.
+- **Least Recently Used (LRU)** items are at the **tail** of the list.
+
+This makes it highly efficient for tracking key access order in a memory-limited cache.
+
+```ruby
+require 'dlinked'
+
+# 1. Initialization
+lru_list = DLinked::CacheList.new
+lru_list.size # => 0
+
+# 2. Add keys to the cache (as MRU)
+# In a real cache, the value might be the cached data itself.
+# For key tracking, value can be the same as the key.
+lru_list.prepend_key(:key1, :key1)
+lru_list.prepend_key(:key2, :key2)
+lru_list.prepend_key(:key3, :key3)
+
+# List order (MRU to LRU): [:key3, :key2, :key1]
+lru_list.to_a # => [:key3, :key2, :key1]
+
+# 3. "Touch" an existing key, moving it to the head (MRU)
+lru_list.move_to_head_by_key(:key1)
+
+# List order is now: [:key1, :key3, :key2]
+lru_list.to_a # => [:key1, :key3, :key2]
+
+# 4. Evict the least recently used key (from the tail)
+evicted_key = lru_list.pop_key
+evicted_key # => :key2
+
+# List order is now: [:key1, :key3]
+lru_list.to_a # => [:key1, :key3]
+
+# 5. Remove a specific key (O(1) operation)
+lru_list.remove_by_key(:key3)
+lru_list.to_a # => [:key1]
+
+# 6. Clear the list and the key map (O(1) operation)
+lru_list.clear
+lru_list.size # => 0
+
+```
 ## ⚡ Performance Characteristics
 This library is designed to offer the guaranteed performance benefits of a Doubly Linked List over a standard Ruby `Array` for certain operations.
 

data/lib/d_linked/cache_list.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module DLinked
+  # DLinked::CacheList
+  #
+  # A specialized doubly linked list subclass used as the central key management
+  # component for an in-memory LRU cache.
+  #
+  # It integrates a hash map (`@lru_nodes`) to provide **O(1)** operations for:
+  # - Prepending/Adding a new key (MRU).
+  # - Touching/Moving an existing key to the head (MRU).
+  # - Evicting the least recently used key (LRU).
+  # - Removing an item by key.
+  #
+  # It maintains the standard list behavior of the superclass {DLinked::List}
+  # but focuses on key-based operations rather than simple value manipulation.
+  class CacheList < DLinked::List
+     class Node < DLinked::List::Node
+      # Add an attribute to hold the cache key
+      attr_accessor :key
+
+      # IMPORTANT: Accept the required three arguments from the base List#prepend,
+      # but only initialize the base class with value, prev, and next.
+      def initialize(value, prev = nil, next_node = nil, key = nil)
+        # Call the parent Node initializer using the first three arguments
+        super(value, prev, next_node) 
+        
+        # Initialize the new, specialized attribute
+        @key = key
+      end
+    end
+    # @!attribute [r] lru_nodes
+    #   @return [Hash] The internal hash map storing {key => DLinked::CacheList::Node} references.
+    attr_reader :lru_nodes
+    # # --- 1. OVERRIDE THE CONSTANT ---
+    Node = DLinked::CacheList::Node
+
+
+    # Initializes a new CacheList instance.
+    # @return [void]
+    def initialize
+      super
+      @lru_nodes = {}
+    end
+
+    # --- LRU Management Methods (O(1)) ---
+
+    # 2. Expose a key-based prepend method
+    #
+    # Adds a new key-value pair to the head of the list (Most Recently Used / MRU).
+    # This operation is atomic, adding the node to the list and storing the
+    # node reference in the internal hash map.
+    #
+    # @param key [Object] The cache key to be managed by the LRU list.
+    # @param value [Object] The value to store inside the list node (usually the same as the key in an LRU list).
+    # @raise [RuntimeError] If the key already exists in the LRU map.
+    # @return [true] Returns true on successful insertion.
+    def prepend_key(key, value)
+      if @lru_nodes.key?(key)
+        raise "Key #{key} already exists in the LRU list."
+      end
+
+      # The specialized Node creation must happen here
+      node = Node.new(value, nil, @head, key) 
+
+      # Use the base class's list logic
+      list_prepend_logic(node)
+
+      # Store the node reference in the map (O(1))
+      @lru_nodes[key] = node 
+
+      true 
+    end
+
+    # 3. Expose a key-based pop method (for eviction)
+    #
+    # Removes the Least Recently Used (LRU) item from the tail of the list.
+    # This performs an O(1) removal and updates the internal hash map.
+    #
+    # @return [Object, nil] Returns the key of the removed LRU item, or nil if the list is empty.
+    def pop_key
+      # O(1) - Base class's pop operation on the tail node
+      node = list_pop_logic 
+      return nil unless node
+      
+      @lru_nodes.delete(node.key)
+      return node.key
+    end
+    
+    # 4. Expose the O(1) touch operation
+    #
+    # Moves an existing key from its current position to the head (MRU).
+    # This is a core O(1) LRU "touch" operation.
+    #
+    # @param key [Object] The key of the item to move.
+    # @return [true, false] Returns true if the move was successful, false if the key was not found.
+    def move_to_head_by_key(key)
+      node = @lru_nodes[key]
+      return false unless node
+
+      # Calls the internal O(1) relocation method
+      _move_to_head(node) 
+      true
+    end
+
+    # 5. Expose O(1) removal
+    #
+    # Removes an item from the list by its key.
+    # This is an O(1) operation using the stored node reference.
+    #
+    # @param key [Object] The key of the item to remove.
+    # @return [true, false] Returns true if the key was removed, false if the key was not found.
+    def remove_by_key(key)
+      node = @lru_nodes.delete(key)
+      return false unless node
+      
+      # Calls the internal O(1) node deletion method
+      _remove_node(node)
+      true
+    end
+
+    # Clears both the doubly linked list and the internal LRU map.
+    # @return [void]
+    def clear
+      @lru_nodes.clear
+      super
+    end
+    
+    # --- PROTECTED / INTERNAL O(1) NODE METHODS ---
+
+    protected
+
+    # New helper: Returns the node that was popped/shifted
+    # This bypasses the base list's public #pop to allow access to the Node object.
+    # @return [DLinked::CacheList::Node, nil] The node object from the tail.
+    def list_pop_logic
+      return nil if empty?
+
+      node = @tail
+      @tail = @tail.prev
+      @tail ? @tail.next = nil : @head = nil
+      @size -= 1
+      return node
+    end
+
+    # O(1) Deletion from a known node reference.
+    # Used internally by {#remove_by_key} and {#_move_to_head}.
+    # @param node [DLinked::CacheList::Node] The node object to remove.
+    # @return [Object] The value of the removed node.
+    def _remove_node(node)
+      # 1. Update the pointers of the surrounding nodes
+      node.prev.next = node.next if node.prev
+      node.next.prev = node.prev if node.next
+      
+      # 2. Update list head/tail if necessary
+      @head = node.next if node == @head
+      @tail = node.prev if node == @tail
+      
+      @size -= 1
+      node.value
+    end
+    
+    # O(1) Move to Head using O(1) removal and base class prepend logic.
+    # @param node [DLinked::CacheList::Node] The node object to move to the head.
+    # @return [void]
+    def _move_to_head(node)
+      return if node == @head
+      
+      # 1. Remove from current spot (O(1))
+      _remove_node(node) 
+      
+      # 2. Re-establish forward link and clear backward link for clean insertion
+      node.next = @head 
+      node.prev = nil
+
+      # 3. Use the base class logic to insert at head. Size counter is correct 
+      #    since _remove_node decremented and list_prepend_logic increments.
+      list_prepend_logic(node)
+    end
+
+  end
+end

data/lib/d_linked/list.rb

@@ -1,14 +1,14 @@
 # frozen_string_literal: true
 
 require_relative 'list/node'
+
 module DLinked
   # A fast, lightweight doubly linked list implementation
   class List
     include Enumerable
 
     # PURE PERFORMANCE: We now use the dedicated Class for Node,
-    Node = DLinked::List::Node
-    private_constant :Node
+    # Node = DLinked::List::Node
 
     attr_reader :size
     alias length size
@@ -29,11 +29,7 @@ module DLinked
     # @return [self] Returns the list instance, allowing for method chaining (e.g., list.prepend(1).prepend(2)).
     def prepend(value)
       node = Node.new(value, nil, @head)
-      @head.prev = node if @head
-      @head = node
-      @tail ||= node
-      @size += 1
-      self
+      list_prepend_logic(node)
     end
     alias unshift prepend
       
@@ -45,11 +41,7 @@ module DLinked
     # @return [DLinked::List] Returns the list instance for method chaining.
     def append(value)
       node = Node.new(value, @tail, nil)
-      @tail.next = node if @tail
-      @tail = node
-      @head ||= node
-      @size += 1
-      self
+      list_append_logic(node)
     end
     alias push append
     alias << append
@@ -366,10 +358,12 @@ module DLinked
       return prepend(value) if index <= 0
       return append(value) if index >= @size
 
+      # Find the node to insert BEFORE
       current = find_node_at_index(index)
 
-      # Insert before current node (O(1) linking)
       new_node = Node.new(value, current.prev, current)
+
+      # Insert before current node (O(1) linking)
       current.prev.next = new_node
       current.prev = new_node
 
@@ -543,6 +537,24 @@ module DLinked
       @size -= removed_count
       result.empty? ? nil : result
     end
+    protected
+
+    # This method handles the actual pointer manipulation, which is constant across all subclasses
+    def list_prepend_logic(node)
+      @head.prev = node if @head
+      @head = node
+      @tail ||= node
+      @size += 1
+      self
+    end
+
+    def list_append_logic(node)
+      @tail.next = node if @tail
+      @tail = node
+      @head ||= node
+      @size += 1
+      self
+    end
 
     private
 

data/lib/d_linked/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DLinked
-  VERSION = '0.1.7'
+  VERSION = '0.1.8'
 end

data/lib/dlinked.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
 require_relative 'd_linked/version'
-require_relative 'd_linked/list'
+
+require_relative 'd_linked/list' 
+
+require_relative 'd_linked/cache_list' 
 
 module DLinked
-  # The DLinked module serves as the namespace for the gem.
-end
+  # Namespace definition is fine here, it just re-opens the module.
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dlinked
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.8
 platform: ruby
 authors:
 - Daniele Frisanco
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-12-13 00:00:00.000000000 Z
+date: 2025-12-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -127,6 +127,7 @@ files:
 - benchmark.rb
 - dlinked.gemspec
 - example.rb
+- lib/d_linked/cache_list.rb
 - lib/d_linked/list.rb
 - lib/d_linked/list/node.rb
 - lib/d_linked/version.rb