sorted_containers 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd886e24f8bbfd92da63127cbd797e35b6df9b0329544c124bcf905cb982c571
-  data.tar.gz: d2dd2c22556f3c68574a98b3d2d48d1e1737631f366ae402f46ac209ed15803b
+  metadata.gz: e7421a03c3463e6e190af04238230eca2120c195bcd711a8fc00eb0ed03ee662
+  data.tar.gz: 608647f3204d54ee2a0aeec7a77d3bd8050d8c14e78638b0f4edd604d61618f7
 SHA512:
-  metadata.gz: 797036401292e34536feef71b1f16b120f6e06554d64f0a979e738a28c911cc45f819449cb9e87ac6751c92eab3fbfce662a97bb24c8ce45129188b346b6bd96
-  data.tar.gz: 36a7f3a4ebf748e04b33923013b079e21f1b4bdeee41ca57930202f8361cc8a195be8c4f1b4b3580d3ac345a7819e520b92aee57a85bacab239e461e79bd4a49
+  metadata.gz: 45fdc56cd4e5593b218376240935d4ff31e3b3f010ece456e72a6334752a28a5f336852a367f8428f1967bbfee49f855ff2d7c14fb5f76af187f6bdf11ffc1ca
+  data.tar.gz: 405354a1b5125f4116348906a5694e66aab47d94e9aa3524335683a04c4cb96e0a0ae181ec164114a00f4fc9ccc8264c68ebf460074b45c0f8f74d2891246ef2

data/.rubocop.yml

@@ -2,9 +2,6 @@ AllCops:
   TargetRubyVersion: 3.0
   NewCops: enable
 
-Metrics/MethodLength:
-  Max: 15
-
 Metrics/BlockLength:
   Exclude:
     - "**/*_spec.rb"

data/README.md

@@ -1,24 +1,141 @@
 # SortedContainers
 
-TODO: Delete this and the text below, and describe your gem
+SortedContainers is a fast implementation of sorted lists, sets, and dictionaries in pure Ruby. It is based on the [sortedcontainers](https://grantjenks.com/docs/sortedcontainers/) Python library by Grant Jenks.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/sorted_containers`. To experiment with that code, run `bin/console` for an interactive prompt.
+SortedContainers provides three main classes: `SortedArray`, `SortedSet`, and `SortedHash`. Each class is a drop-in replacement for the corresponding Ruby class, but with the added benefit of maintaining the elements in sorted order.
+
+SortedContainers exploits the fact that modern computers are really good at shifting arrays in memory. We sacrifice theroetical time complexity for practical performance. In practice, SortedContainers is fast.
+
+## How it works
+
+Computers are good at shifting arrays. For that reason, it's often faster to keep an array sorted than to use the usual tree-based data structures.
+
+For example, if you have the array `[1, 2, 4, 5]` and want to insert the element `3`, you can shift `4, 5` to the right and insert `3` in the correct position. This is a `O(n)` operation, but in practice it's fast.
+
+But we can do better if we have a lot of elements. We can break up the array into smaller arrays so the shifts don't have to move so many elements. For example, if you have the array `[[1,2,4], [5,6,7]]` and you want to insert the element `3`, you can insert `3` into the first array to get `[[1,2,3,4], [5,6,7]]` and only the element `4` has to be shifted.
+
+This often outperforms the more common tree-based data structures like red-black trees with `O(log n)` insertions and deletions. In practice, the `O(n)` insertions and deletions of SortedContainers are faster.
+
+How big the subarrays are is a trade-off. You can modify how big you want to subarrays by setting the `load_factor`. The default is set to DEFAULT_LOAD_FACTOR = 1000. The subarray is split when its size is `2*load_factor`. There is no perfect value. The ideal value will depend on your use case and may require some experimentation.
+
+## Benchmarks
+ 
+Performance comparison against [SortedSet](https://github.com/knu/sorted_set) a C extension red-black tree implementation. Every test was run 5 times and the average was taken.
+
+You can see that SortedContainers has compariable performance for add and delete, and much better performance for iteration, initialization, and include.
+
+Note: I do not know why initialization is faster for 4 million than 3 million elements. This was consistant across multiple runs.
+
+- MacBook Pro (16-inch, 2019)
+- 2.6 GHz 6-Core Intel Core i7, 16 GB 2667 MHz DDR4
+- Ruby 3.2.2
+- SortedContainers 0.1.0
+- SortedSet 1.0.3
+### Results (Lower is better)
+<img src="benchmark/initialize_performance_comparison.png" width="50%">
+<img src="benchmark/add_performance_comparison.png" width="50%">
+<img src="benchmark/delete_performance_comparison.png" width="50%">
+<img src="benchmark/iteration_performance_comparison.png" width="50%">
+<img src="benchmark/include_performance_comparison.png" width="50%">
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+Add this line to your application's Gemfile:
 
-Install the gem and add to the application's Gemfile by executing:
+```ruby
+gem 'sorted_containers'
+```
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+And then execute:
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+```bash
+bundle install
+```
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+Or install it yourself as:
+    
+```bash
+gem install sorted_containers
+```
 
 ## Usage
 
-TODO: Write usage instructions here
+    require 'sorted_containers'
+
+    # Create a new SortedArray
+    list = SortedContainers::SortedArray.new
+
+    # Add elements to the list
+    list << 3
+    list << 1
+    list << 2
+
+    # Access elements by index
+    puts list[0] # => 1
+    puts list[1] # => 2
+    puts list[2] # => 3
+
+    # Access elements by index
+    puts list.first # => 1
+    puts list.last # => 3
+
+    # Remove elements from the list
+    list.delete(2)
+
+    # Iterate over the list
+    list.each do |element|
+      puts element
+    end
+
+    # Create a new SortedSet
+    set = SortedContainers::SortedSet.new
+
+    # Add elements to the set
+    set << 3
+    set << 1
+    set << 2
+
+    # Access elements by index
+    puts set[0] # => 1
+    puts set[1] # => 2
+    puts set[2] # => 3
+
+    # Access elements by index
+    puts set.first # => 1
+    puts set.last # => 3
+
+    # Remove elements from the set
+    set.delete(2)
+
+    # Iterate over the set
+    set.each do |element|
+      puts element
+    end
+
+    # Create a new SortedHash
+    dict = SortedContainers::SortedHash.new
+
+    # Add elements to the dict
+    dict[3] = 'three'
+    dict[1] = 'one'
+    dict[2] = 'two'
+
+    # Access elements by key
+    puts dict[1] # => 'one'
+    puts dict[2] # => 'two'
+    puts dict[3] # => 'three'
+
+    # Access elements by index
+    puts dict.first # => [1, 'one']
+    puts dict.last # => [3, 'three']
+
+    # Remove elements from the dict
+    dict.delete(2)
+
+    # Iterate over the dict
+    dict.each do |key, value|
+      puts "#{key}: #{value}"
+    end
 
 ## Development
 
@@ -28,7 +145,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/sorted_containers. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/sorted_containers/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/GarrisonJ/sorted_containers. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/GarrisonJ/sorted_containers/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -36,4 +153,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the SortedContainers project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/sorted_containers/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the SortedContainers project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/GarrisonJ/sorted_containers/blob/main/CODE_OF_CONDUCT.md).