dlinked 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 724380c942032cdc4308e6457a68996d0cffd35681a8a2f869e4f7e9f4938d59
+  data.tar.gz: 073d48b50858323574657b66386f14c3ec7137857a9dc16f3879579bcc09b002
+SHA512:
+  metadata.gz: 260d3fefb326f3e41243b16875b38880d599706a3bcc497dd18583ddacf232700aa1e14e06033ad2bc21f01869c4c67df6fb29c5d5395a0e1fef4c26b591ab26
+  data.tar.gz: 79c0f06249f6c3df620248d4114ab3b18bdb3110c8c9e0284eee945362b5cc698c8848b5464e505ba4590ae64c93885086d6f350799f90f3ef27cd9a4d9f9ba6

data/.github/workflows/release.yml

@@ -0,0 +1,122 @@
+# .github/workflows/release.yml
+
+name: Publish Ruby Gem
+
+# This workflow runs when:
+on:
+  push:
+    branches:
+      - main # Run tests and build on every push to main
+  # Run the build and release steps ONLY when a new tag is pushed (e.g., v0.1.0)
+  release:
+    types: [published]
+
+jobs:
+  test:
+    name: Run Tests & Build Gem
+    runs-on: ubuntu-latest
+    
+    # Use a matrix to test across common Ruby versions (e.g., 3.0, 3.1, 3.2, 3.3)
+    strategy:
+      matrix:
+        ruby: ['3.1', '3.2', '3.3']
+
+    steps:
+    - name: Checkout Code
+      uses: actions/checkout@v4
+
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true # Installs dependencies from Gemfile.lock
+
+    - name: Run Tests with SimpleCov
+      run: bundle exec rake test
+
+    - name: Upload Test Coverage Report (Artifact)
+      uses: actions/upload-artifact@v4
+      with:
+        name: coverage-report-${{ matrix.ruby }}
+        path: coverage/
+
+    # Only build the .gem file on the latest stable Ruby version
+    - name: Build Gem
+      if: matrix.ruby == '3.3'
+      run: bundle exec rake build
+
+    - name: Upload Gem Artifact
+      if: matrix.ruby == '3.3'
+      uses: actions/upload-artifact@v4
+      with:
+        name: dlinked-gem
+        path: pkg/
+  deploy_docs:
+    name: Deploy Documentation to GitHub Pages
+    runs-on: ubuntu-latest
+    needs: test # Ensure tests pass before deploying docs
+    
+    # Run only when pushing to the main branch
+    if: github.ref == 'refs/heads/main'
+    
+    permissions:
+      contents: write # Needed to push generated documentation to gh-pages branch
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+      
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.3
+          bundler-cache: true
+          
+      - name: Install YARD (if not in Gemfile)
+        run: gem install yard
+        
+      - name: Generate YARD Documentation
+        run: yard doc
+        
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          # This is the authentication token provided by GitHub
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          # The branch where YARD documentation will be pushed
+          publish_branch: gh-pages 
+          # The directory to publish (generated by yard doc)
+          publish_dir: ./doc
+  publish:
+    name: Publish to RubyGems
+    runs-on: ubuntu-latest
+    needs: test 
+    
+    # This step only executes when a release is published (a tag is pushed)
+    if: github.event_name == 'release' && github.event.action == 'published'
+    
+    steps:
+    - name: Checkout Code (Needed to access config)
+      uses: actions/checkout@v4
+
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: 3.3 # Use the latest version for publishing
+        bundler-cache: false # We only need the runtime
+
+    - name: Download Gem Artifact
+      uses: actions/download-artifact@v4
+      with:
+        name: dlinked-gem
+        path: pkg/
+        
+    - name: Set up RubyGems credentials
+      run: |
+        mkdir -p ~/.gem
+        echo ":rubygems_api_key: ${{ secrets.RUBYGEMS_API_KEY }}" > ~/.gem/credentials
+        chmod 0600 ~/.gem/credentials
+
+    - name: Push Gem to RubyGems.org
+      # The gem file is expected to be in the 'pkg/' directory
+      run: gem push pkg/*.gem

data/.gitignore

@@ -0,0 +1,83 @@
+
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+.env
+
+# Ignore Byebug command history file.
+.byebug_history
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+Gemfile.lock
+.ruby-version
+.ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# Used by RuboCop. Remote config files pulled in from inherit_from directive.
+.rubocop-https?--*
+
+# IDE files
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS files
+.DS_Store
+Thumbs.db
+# --- Ruby Gem/Bundler Artifacts ---
+# Ignores the compiled .gem file (which should be built on CI/release)
+*.gem
+# Ignores the cached extension files
+/ext/**/tmp
+/ext/**/objects
+/ext/**/gems
+
+# --- Test/Coverage Reports ---
+# SimpleCov coverage output directory
+/coverage
+
+# --- Documentation Artifacts (YARD/RDoc) ---
+# When you generate API documentation, it creates this folder
+/doc

data/.rubocop.yml

@@ -0,0 +1,45 @@
+# .rubocop.yml
+
+# We'll use the default Rubocop configuration as a starting point.
+inherit_gem:
+  rubocop-minitest:
+    - config/default.yml
+
+require:
+  - rubocop-minitest # Good practice since you are using Minitest
+
+AllCops:
+  # Exclude the gem build artifacts, configuration files, etc.
+  Exclude:
+    - 'dlinked-*.gem'
+    - 'vendor/**/*'
+    - 'bin/**/*'
+    - 'node_modules/**/*'
+    - 'pkg/**/*'
+    - 'Rakefile' # Often contains unique logic
+    - 'dlinked.gemspec'
+
+  # Target Ruby version is often set here
+  TargetRubyVersion: 3.1 # Set this to the version you are primarily developing on
+
+# --- Specific Cops Configuration ---
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+
+Metrics/BlockLength:
+  # Allows longer blocks, often needed for test files
+  Exclude:
+    - 'test/**/*.rb'
+    - 'benchmark.rb'
+  Max: 100
+
+Metrics/MethodLength:
+  # Your list.rb methods are complex due to assignment/slice logic
+  Exclude:
+    - 'lib/d_linked/list.rb'
+  Max: 20
+
+# Allow documentation for public methods to be required
+Documentation:
+  Enabled: false

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+
+MIT License
+
+Copyright (c) 2025 [Your Name]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,221 @@
+# DLinked
+
+A fast, lightweight doubly linked list implementation for Ruby.
+
+## Features
+
+- **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
+- **Bidirectional**: Iterate forward or backward efficiently
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'dlinked'
+```
+
+Or install it yourself:
+
+```bash
+gem install dlinked
+```
+
+## Test
+
+```bash
+bundle exec ruby test/test_d_linked_list.rb
+
+```
+
+## Usage
+### 1. Basic Initialization and O(1) Operations
+Demonstrate creating the list, adding elements to both ends, and removing them quickly.
+
+
+```ruby
+require 'dlinked'
+
+# 1. Initialization
+list = DLinked::List.new
+list.size # => 0
+
+# 2. O(1) Prepend (Add to Head)
+list.prepend(20).prepend(10) # Using method chaining
+# The list now looks like: [10, 20]
+
+# 3. O(1) Append (Add to Tail)
+list << 30
+list.append(40)
+# The list now looks like: [10, 20, 30, 40]
+
+# 4. O(1) Removal
+list.shift # => 10 (Removes from head)
+list.pop   # => 40 (Removes from tail)
+# The list now looks like: [20, 30]
+
+list.to_a # => [20, 30]
+```
+### 2. Array-Like Access and Assignment
+Show users how the list behaves like a Ruby Array, utilizing the [] and []= methods you implemented.
+
+
+```ruby
+list = DLinked::List.new
+list << 'A' << 'B' << 'C' << 'D'
+
+# 1. Access by Index
+list[2]   # => 'C'
+list[-1]  # => 'D' (Accessing from the tail)
+
+# 2. Element Assignment (O(n) but familiar)
+list[1] = 'B_NEW'
+list.to_a # => ["A", "B_NEW", "C", "D"]
+
+# 3. Slice/Range Access
+list[1, 2].to_a # => ["B_NEW", "C"] (start at 1, length 2)
+list[0..2].to_a # => ["A", "B_NEW", "C"] (using a Range)
+
+# 4. Slice Replacement (Deletion and Insertion)
+list[1, 2] = ['X', 'Y', 'Z'] # Replace two elements with three new elements
+list.to_a # => ["A", "X", "Y", "Z", "D"]
+list.size # => 5
+```
+### 3. Enumerable and Iteration
+Demonstrate how it works seamlessly with standard Ruby collection methods.
+
+
+```ruby
+list = DLinked::List.new
+list << 10 << 20 << 30 << 40
+
+# Standard Enumerable methods work out of the box
+list.map { |n| n * 2 }     # => [20, 40, 60, 80]
+list.select(&:even?)        # => [10, 20, 30, 40]
+
+# O(n) Insertion in the middle
+list.insert(2, 25)
+list.to_a                  # => [10, 20, 25, 30, 40]
+
+# O(n) Deletion by value
+list.delete(20)
+list.to_a                  # => [10, 25, 30, 40]
+```
+
+
+### 4. Utility, Inspection, and Conversion Methods
+This section covers the basic checks, conversions, and advanced destructive operations.
+
+```ruby
+
+list = DLinked::List.new
+list << 10 << 20 << 30
+
+# --- Basic Inspection ---
+
+list.size     # => 3
+list.length   # => 3 (alias for size)
+list.empty?   # => false
+DLinked::List.new.empty? # => true
+
+list.first    # => 10 (O(1))
+list.last     # => 30 (O(1))
+
+list.to_a     # => [10, 20, 30]
+list.to_s     # => "[10, 20, 30]"
+list.inspect  # => "[10, 20, 30]"
+
+# --- Lookup ---
+
+list.index(20) # => 1
+list.index(99) # => nil (Value not found)
+```
+
+### 5. Advanced Insertion, Deletion, and Slicing
+Demonstrate non-O(1) operations that are useful for list manipulation, including the destructive slice! method.
+
+```ruby
+
+
+list = DLinked::List.new
+list << 'A' << 'B' << 'C' << 'D' << 'E'
+
+# --- O(n) Insertion ---
+
+# Insert at the middle (index 2)
+list.insert(2, 'Z')
+list.to_a # => ["A", "B", "Z", "C", "D", "E"]
+list.insert(0, 'Start') # Same as prepend (O(1))
+list.to_a # => ["Start", "A", "B", "Z", "C", "D", "E"]
+
+# --- Deletion by Value ---
+
+list.delete('Z') # => "Z" (Returns the deleted value)
+list.to_a        # => ["Start", "A", "B", "C", "D", "E"]
+
+# --- Destructive Slicing (slice!) ---
+
+# Extract and remove a slice of 2 elements, starting at index 1
+removed_slice = list.slice!(1, 2)
+list.to_a        # => ["Start", "C", "D", "E"]
+removed_slice.to_a # => ["A", "B"]
+
+# Remove one element using a range (index 2)
+list.slice!(2..2)
+list.to_a        # => ["Start", "C", "E"]
+
+list.size        # => 3
+```
+
+### 6. Concatenation and Arithmetic
+Demonstrate how lists can be combined.
+
+```ruby
+
+
+list1 = DLinked::List.new << 1 << 2
+list2 = DLinked::List.new << 3 << 4
+
+# Non-destructive concatenation (returns a new list)
+new_list = list1 + list2
+new_list.to_a # => [1, 2, 3, 4]
+list1.to_a    # => [1, 2] (list1 is unchanged)
+
+# Destructive concatenation (modifies list1)
+list1.concat(list2)
+list1.to_a # => [1, 2, 3, 4]
+```
+
+## ⚡ 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.
+
+ | Operation | Method(s) | Complexity | Notes | 
+  | - | - | - | - | 
+  | End Insertion | append, prepend, push, unshift, << | $O(1)$ | Constant time, regardless of list size. | 
+  | End Deletion | pop, shift | $O(1)$ | Constant time. | 
+  | End Access | first, last | $O(1)$ | Constant time access to boundary values. | 
+  | Middle Insertion/Deletion | insert, delete (by value), slice!, []= (slice) | $O(n)$ | Requires traversal to find the node. | 
+  | Random Access/Search | [] (getter), index | $O(n)$ | Requires traversal; average time is $O(n/2)$. | 
+
+
+
+## 💾 Memory Usage
+
+While memory usage is highly dependent on the objects stored, the overhead of the list structure itself is minimal and highly efficient:
+
+*   **Node Overhead:** Each node in the list uses approximately 40 bytes. This includes the object header, and three necessary pointers:
+    
+    1.  Pointer to the stored **value**
+        
+    2.  Pointer to the **next** node
+        
+    3.  Pointer to the **previous** node
+        
+*   **Efficiency Advantage:** This structured overhead is often more memory-efficient than a large Ruby `Array` that requires constant reallocation and copying when its capacity is exceeded, especially if the `Array` is being modified frequently at the head.
+
+## License
+
+MIT License. See LICENSE.txt for details.

data/Rakefile

@@ -0,0 +1,10 @@
+# Rakefile
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.libs << "lib"
+  t.test_files = FileList["test/test_*.rb"]
+end
+
+task default: :test

data/benchmark.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# benchmark.rb - Compare Struct vs Class performance
+# Run with: ruby benchmark.rb
+require 'benchmark'
+
+# Struct version
+NodeStruct = Struct.new(:value, :prev, :next)
+
+# Class version
+class NodeClass
+  attr_accessor :value, :prev, :next
+
+  def initialize(value, prev_node, next_node)
+    @value = value
+    @prev = prev_node
+    @next = next_node
+  end
+end
+
+N = 2_000_000
+
+puts "Creating and accessing #{N} nodes:\n\n"
+
+Benchmark.bm(20) do |x|
+  x.report('Class creation:') do
+    N.times { |i| NodeClass.new(i, nil, nil) }
+  end
+
+  x.report('Struct creation:') do
+    N.times { |i| NodeStruct.new(i, nil, nil) }
+  end
+
+  # Test access speed (the important part!)
+  struct_nodes = Array.new(1000) { |i| NodeStruct.new(i, nil, nil) }
+  class_nodes = Array.new(1000) { |i| NodeClass.new(i, nil, nil) }
+
+  x.report('Class access:') do
+    N.times do
+      node = class_nodes[rand(1000)]
+      v = node.value
+      node.value = v + 1
+    end
+  end
+  x.report('Struct access:') do
+    N.times do
+      node = struct_nodes[rand(1000)]
+      v = node.value
+      node.value = v + 1
+    end
+  end
+end
+
+puts "\nConclusion: Run this benchmark on your target Ruby version to decide!"

data/dlinked.gemspec

@@ -0,0 +1,37 @@
+
+# frozen_string_literal: true
+require_relative "lib/d_linked/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "dlinked"
+  spec.version       = DLinked::VERSION
+  # spec.version       = File.read(File.expand_path("lib/d_linked/version.rb")).scan(/VERSION = "([^"]+)"/).flatten.first
+  spec.authors       = ["Daniele Frisanco"]
+  spec.email         = ["daniele.frisanco@gmail.com"]
+  
+  spec.summary       = "A highly performant Doubly Linked List implementation for Ruby."
+  spec.description   = "Provides a native Doubly Linked List data structure in Ruby, focusing on O(1) performance for head/tail operations and standard Enumerable compatibility."
+  spec.homepage      = "https://github.com/danielefrisanco/dlinked"
+  spec.license       = "MIT"
+
+  spec.required_ruby_version = ">= 2.7.0"
+  
+  # --- Files to Include in the Gem ---
+  
+  # Ensure all necessary files are included in the built gem
+  spec.files         = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features|benchmark)/}) }
+  end
+  
+  # Pin the main file that gets loaded when someone 'require's the gem
+  spec.require_paths = ["lib"]
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake",    "~> 13.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "rubocop", "~> 1.0"
+  spec.add_development_dependency "rubocop-minitest", "~> 0.16.0"
+  spec.add_development_dependency "simplecov", "~> 0.22"
+  spec.add_development_dependency "yard", "~> 0.9"
+end

data/example.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'dlinked' # Add this line!
+
+list = DLinked::List.new
+list.append(2).append(3).prepend(1)
+puts "After operations: #{list}"
+puts "Size: #{list.size}"
+
+# More examples...
+list << 10 << 20 << 30
+puts "List: #{list}"
+puts "First: #{list.first}, Last: #{list.last}"
+
+list.each { |v| puts "  Value: #{v}" }
+if __FILE__ == $PROGRAM_NAME
+  list = DLinked::List.new
+
+  # Test append and prepend
+  list.append(2).append(3).prepend(1)
+  puts "After operations: #{list}" # [1, 2, 3]
+  puts "Size: #{list.size}" # 3
+
+  # Test pop and shift
+  puts "Pop: #{list.pop}"            # 3
+  puts "Shift: #{list.shift}"        # 1
+  puts "After pop/shift: #{list}"    # [2]
+
+  # Test iteration
+  list.append(4).append(6).prepend(0)
+  puts "\nForward iteration:"
+  list.each { |v| puts "  #{v}" }
+
+  puts "\nReverse iteration:"
+  list.reverse_each { |v| puts "  #{v}" }
+
+  # Test enumerable methods
+  puts "\nSquared values: #{list.map { |v| v * v }}"
+  puts "Sum: #{list.sum}"
+
+  # Test delete
+  list.delete(2)
+  puts "After deleting 2: #{list}"
+end

data/lib/d_linked/list/node.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module DLinked
+  class List
+    # The Node class represents a single element in the Doubly Linked List.
+    # It holds the element's value and pointers to the next and previous nodes.
+    # Note: If this class is defined outside of DLinked::List, adjust the scope accordingly.
+    
+    # Represents a single element within the Doubly Linked List.
+    #
+    # Each node maintains three critical pieces of data:
+    # 1. The actual value stored by the user.
+    # 2. A pointer to the next node in the list.
+    # 3. A pointer to the previous node in the list.
+    #
+    # This structure is the foundation of the list's O(1) performance for boundary operations.
+    class Node
+      # @!attribute [rw] value
+      #   @return [Object] The actual data stored by the user in this node.
+      attr_accessor :value
+
+      # @!attribute [rw] next
+      #   @return [DLinked::List::Node, nil] A pointer to the subsequent node in the list, or nil if this is the tail.
+      attr_accessor :next
+
+      # @!attribute [rw] prev
+      #   @return [DLinked::List::Node, nil] A pointer to the preceding node in the list, or nil if this is the head.
+      attr_accessor :prev
+
+      # Initializes a new Node instance.
+      #
+      # @param value [Object, nil] The value to store in the node.
+      # @param prev [DLinked::List::Node, nil] The node preceding this one.
+      # @param next_node [DLinked::List::Node, nil] The node succeeding this one.
+      def initialize(value = nil, prev = nil, next_node = nil)
+        @value = value
+        @prev = prev
+        @next = next_node
+      end
+    end
+  end
+end