dlinked 0.1.8 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de491a4898093da5aac0b68079ebc40d001a60234ae752ec39250fa3d56d09d2
-  data.tar.gz: cdaf5870bba85269d949a0471a8f4481ad1786a18cf1e1f14159439b5d6235f4
+  metadata.gz: 8215705b10ca404e892cc7b1d6571d96ee66aa8521941f42d6e7051582d2372a
+  data.tar.gz: bff1d797d11300cdae48d6f7a3623e17bb7e996db7457b270884e5e9312192b6
 SHA512:
-  metadata.gz: 57666858cfbccc763cc732022f017fe3739292ec72b58c4c87d699bb65ea25154c5ba04458346fed4fdf53c7fa522801e2ba1c29e8bc53ea880d6d4f31109cea
-  data.tar.gz: 2ba4f2c83fff58be2e103968482f402ac8d6c6ce1f60ca5b4256e2e9337b30248afb1de181227b2a102872307d6ea60e4faaa3d30254942b65b9bf9bb6cb92da
+  metadata.gz: 69e363bbc4d74898aa65673c0f46250633f9448d7c406ecfe089860a2005142905a170f0da5724d3a1766fe4ff70ddbbd2a77653be86b9fab08efd8b23a538a9
+  data.tar.gz: 129ab2caf81b5d8fb6d24c67ccad979fff1ce928811341f28104f5b0f851f1d05106783935d2e17bddd1bc9edf953f539332d4cc01131286495bd529a90dc65d

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+*   Using welcoming and inclusive language
+*   Being respectful of differing viewpoints and experiences
+*   Gracefully accepting constructive criticism
+*   Focusing on what is best for the community
+*   Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+*   The use of sexualized language or imagery and unwelcome sexual attention or
+    advances
+*   Trolling, insulting/derogatory comments, and personal or political attacks
+*   Public or private harassment
+*   Publishing others' private information, such as a physical or electronic
+    address, without explicit permission
+*   Other conduct which could reasonably be considered inappropriate in a
+    professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0,
+available at [https://www.contributor-covenant.org/version/2/0/code_of_conduct.html][v2.0].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.0]: https://www.contributor-covenant.org/version/2/0/code_of_conduct.html

data/CONTRIBUTING.md

@@ -0,0 +1,88 @@
+# Contributing to DLinked
+
+First off, thank you for considering contributing to DLinked! It's people like you that make open source such a great community.
+
+We welcome any type of contribution, not just code. You can help with:
+*   **Reporting a bug**
+*   **Discussing the current state of the code**
+*   **Submitting a fix**
+*   **Proposing new features**
+*   **Becoming a maintainer**
+
+## Getting Started
+
+### Development Environment
+
+To get started with the development environment, you'll need:
+*   Ruby (see `.ruby-version` for the required version)
+*   Bundler
+
+1.  **Fork the repository** on GitHub.
+2.  **Clone your fork** locally:
+    ```bash
+    git clone https://github.com/your-username/dlinked.git
+    cd dlinked
+    ```
+3.  **Install dependencies** using Bundler:
+    ```bash
+    bundle install
+    ```
+
+### Running Tests
+
+This project uses Minitest for testing. To run the full test suite, use the following command:
+
+```bash
+bundle exec rake test
+```
+
+This will also run SimpleCov to generate a code coverage report in the `coverage/` directory. When submitting a pull request, please ensure that your changes are covered by tests and that you maintain or increase the test coverage.
+
+### Code Style
+
+This project uses RuboCop to enforce a consistent code style. To check your code for style violations, run:
+
+```bash
+bundle exec rubocop
+```
+
+Many style violations can be automatically fixed by running:
+
+```bash
+bundle exec rubocop -A
+```
+
+Please ensure your code follows the project's style guidelines before submitting a pull request.
+
+## How to Contribute
+
+### Reporting Bugs
+
+If you find a bug, please open an issue on GitHub. Please include:
+*   A clear and descriptive title.
+*   A detailed description of the problem, including steps to reproduce it.
+*   The expected behavior and what actually happened.
+*   The version of DLinked and Ruby you are using.
+
+### Submitting Changes (Pull Requests)
+
+1.  Create a new branch for your changes:
+    ```bash
+    git checkout -b your-feature-branch-name
+    ```
+2.  Make your changes, and add or update tests as needed.
+3.  Ensure the test suite passes (`bundle exec rake test`).
+4.  Ensure your code passes the RuboCop checks (`bundle exec rubocop`).
+5.  Commit your changes with a clear and descriptive commit message.
+6.  Push your branch to your fork on GitHub:
+    ```bash
+    git push origin your-feature-branch-name
+    ```
+7.  Open a pull request from your fork to the main DLinked repository.
+8.  In the pull request description, please explain the problem you are solving and the changes you have made.
+
+## Code of Conduct
+
+By participating in this project, you are expected to uphold our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+Thank you for your contribution!

data/README.md

@@ -28,9 +28,18 @@ gem install dlinked
 
 ```bash
 bundle exec rake test
+```
+
+## Documentation
+
+To generate the YARD documentation for this project, run:
 
+```bash
+bundle exec yard doc
 ```
 
+This will create a `doc/` directory containing the full HTML documentation. You can view it by opening `doc/index.html` in your browser.
+
 ## Usage
 ### 1. Basic Initialization and O(1) Operations
 Demonstrate creating the list, adding elements to both ends, and removing them quickly.
@@ -241,6 +250,57 @@ lru_list.clear
 lru_list.size # => 0
 
 ```
+
+### Real-World Example: A Complete LRU Cache
+While `DLinked::CacheList` provides the low-level, high-performance key tracking, you can easily build a complete, practical `LRUCache` class around it.
+
+The following example demonstrates how to combine `DLinked::CacheList` with a `Hash` for data storage to create a fully functional LRU cache.
+
+```ruby
+# A complete, working implementation of a Least Recently Used (LRU) Cache
+# built on top of DLinked::CacheList.
+class LRUCache
+  attr_reader :capacity, :size
+
+  def initialize(capacity)
+    raise ArgumentError, 'Capacity must be a positive integer' unless capacity.is_a?(Integer) && capacity > 0
+
+    @capacity = capacity
+    @size = 0
+    @list = DLinked::CacheList.new
+    @data = {}
+  end
+
+  def get(key)
+    return nil unless @data.key?(key)
+    @list.move_to_head_by_key(key)
+    @data[key]
+  end
+
+  def set(key, value)
+    if @data.key?(key)
+      @list.move_to_head_by_key(key)
+    else
+      @list.prepend_key(key, value)
+      @size += 1
+      evict if @size > @capacity
+    end
+    @data[key] = value
+  end
+
+  private
+
+  def evict
+    lru_key = @list.pop_key
+    return unless lru_key
+    @data.delete(lru_key)
+    @size -= 1
+  end
+end
+```
+
+For a complete, runnable demonstration of this `LRUCache` class in action, see the [lru_cache_example.rb](./lru_cache_example.rb) file.
+
 ## ⚡ 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.
 
@@ -254,6 +314,34 @@ This library is designed to offer the guaranteed performance benefits of a Doubl
 
 
 
+## ⚡ Performance Benchmarks
+
+To quantify the performance benefits of `DLinked::List` over Ruby's `Array`, a benchmark suite is available in `benchmark.rb`. It uses the `benchmark-ips` gem to compare the performance of single operations on a pre-filled data structure of 10,000 items.
+
+The benchmark measures a single operation (e.g., `shift`) and immediately performs the inverse operation (e.g., `push`) to ensure the list size remains constant for every measurement. This provides a more accurate comparison of how each data structure handles these calls on a large collection.
+
+You can run the benchmark yourself:
+
+```bash
+bundle install
+bundle exec ruby benchmark.rb
+```
+
+**Results:**
+
+The results below were generated on Ruby 3.1.4. They demonstrate that for a list of 10,000 items, the performance of Ruby's native, C-implemented `Array` is significantly faster than `DLinked::List`'s pure Ruby implementation, even for operations where the linked list has a better theoretical time complexity.
+
+| Operation | Comparison | Analysis |
+| :--- | :--- | :--- |
+| `append` / `push` | `Array` is ~5.2x faster | `Array` is faster. This is expected as it's a highly optimized C implementation, while `DLinked::List` has the overhead of Ruby method calls and `Node` object allocation. |
+| `prepend` / `unshift`| `Array` is ~5.1x faster | Surprisingly, `Array#unshift` is still faster at this scale. The cost of memory shifting in C for 10,000 items is lower than the overhead of `DLinked::List`'s Ruby implementation. |
+| `pop` | `Array` is ~5.3x faster | Similar to `push`, the native `Array` implementation is faster for this O(1) operation. |
+| `shift` | `Array` is ~5.4x faster | Like `unshift`, `Array#shift`'s O(n) operation in C is faster than `DLinked::List`'s O(1) operation in Ruby at this list size, due to the overhead of the Ruby implementation. |
+
+**Conclusion:**
+
+These benchmarks show that the raw speed of the underlying C implementation of `Array` outweighs the Big-O algorithmic advantages of a pure Ruby linked list for collections of this size. `DLinked::List` is better suited for educational purposes or for algorithms where the explicit node structure and pointer manipulation are more important than raw wall-clock performance against `Array`.
+
 ## 💾 Memory Usage
 
 While memory usage is highly dependent on the objects stored, the overhead of the list structure itself is minimal and highly efficient:

data/benchmark.rb

@@ -1,54 +1,78 @@
 # frozen_string_literal: true
 
-# benchmark.rb - Compare Struct vs Class performance
-# Run with: ruby benchmark.rb
-require 'benchmark'
+require 'benchmark/ips'
+require 'dlinked'
 
-# Struct version
-NodeStruct = Struct.new(:value, :prev, :next)
+puts "Ruby version: #{RUBY_VERSION}"
+puts "DLinked version: #{DLinked::VERSION}"
 
-# Class version
-class NodeClass
-  attr_accessor :value, :prev, :next
+LIST_SIZE = 10_000
+puts "\n--- Benchmarking single operations on a list of #{LIST_SIZE} items ---"
+puts "A single operation is performed, and then undone to maintain list size."
 
-  def initialize(value, prev_node, next_node)
-    @value = value
-    @prev = prev_node
-    @next = next_node
+# --- Setup ---
+array = (0...LIST_SIZE).to_a
+list = DLinked::List.new
+array.each { |i| list.append(i) }
+
+# --- Benchmark Suite ---
+
+puts "\nAppend/Push at the end:"
+Benchmark.ips do |x|
+  x.report("Array#push") do
+    array.push(0)
+    array.pop
   end
-end
 
-N = 2_000_000
+  x.report("DLinked::List#append") do
+    list.append(0)
+    list.pop
+  end
 
-puts "Creating and accessing #{N} nodes:\n\n"
+  x.compare!
+end
 
-Benchmark.bm(20) do |x|
-  x.report('Class creation:') do
-    N.times { |i| NodeClass.new(i, nil, nil) }
+puts "\nPrepend/Unshift at the beginning:"
+Benchmark.ips do |x|
+  x.report("Array#unshift") do
+    array.unshift(0)
+    array.shift
   end
 
-  x.report('Struct creation:') do
-    N.times { |i| NodeStruct.new(i, nil, nil) }
+  x.report("DLinked::List#prepend") do
+    list.prepend(0)
+    list.shift
   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.compare! 
+end
 
-  x.report('Class access:') do
-    N.times do
-      node = class_nodes[rand(1000)]
-      v = node.value
-      node.value = v + 1
-    end
+puts "\nPop from the end:"
+Benchmark.ips do |x|
+  x.report("Array#pop") do
+    el = array.pop
+    array.push(el)
   end
-  x.report('Struct access:') do
-    N.times do
-      node = struct_nodes[rand(1000)]
-      v = node.value
-      node.value = v + 1
-    end
+
+  x.report("DLinked::List#pop") do
+    el = list.pop
+    list.append(el)
   end
+
+  x.compare!
 end
 
-puts "\nConclusion: Run this benchmark on your target Ruby version to decide!"
+puts "\nShift from the beginning:"
+Benchmark.ips do |x|
+  x.report("Array#shift") do
+    el = array.shift
+    array.push(el)
+  end
+
+  x.report("DLinked::List#shift") do
+    el = list.shift
+    list.append(el)
+  end
+
+  x.compare!
+end

data/dlinked.gemspec

@@ -38,4 +38,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rubocop-minitest", "~> 0.16.0"
   spec.add_development_dependency "simplecov", "~> 0.22"
   spec.add_development_dependency "yard", "~> 0.9"
+  spec.add_development_dependency "benchmark-ips", "~> 2.8"
 end