sorted_containers 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7421a03c3463e6e190af04238230eca2120c195bcd711a8fc00eb0ed03ee662
-  data.tar.gz: 608647f3204d54ee2a0aeec7a77d3bd8050d8c14e78638b0f4edd604d61618f7
+  metadata.gz: 3402cc1b71fc79ef75e11c571123f82a2e79063688413922f8635dffaed9e179
+  data.tar.gz: 7a07b07ca3062d60cf0a92a60e1b3299629aa3d2ae3aaac46d81e8f9f8118d18
 SHA512:
-  metadata.gz: 45fdc56cd4e5593b218376240935d4ff31e3b3f010ece456e72a6334752a28a5f336852a367f8428f1967bbfee49f855ff2d7c14fb5f76af187f6bdf11ffc1ca
-  data.tar.gz: 405354a1b5125f4116348906a5694e66aab47d94e9aa3524335683a04c4cb96e0a0ae181ec164114a00f4fc9ccc8264c68ebf460074b45c0f8f74d2891246ef2
+  metadata.gz: 441f144945782fa0100b2814ad0282efce28d948058b1e5219a24674b1c05591e8adf93642f3ad1fa4c5d31d12e7961102219c52943507b37aae2c827d8488fd
+  data.tar.gz: 97021f40b0c465854c087772739d731d32dc22029f2387532c8878f681327f7403c61505a844bab3b6acc2a698947dca3cb3bc185116a611341375a4154d8f8b

data/.rubocop.yml

@@ -1,6 +1,9 @@
 AllCops:
   TargetRubyVersion: 3.0
   NewCops: enable
+  Exclude:
+    - "benchmark/**/*"
+    - "vendor/**/*"
 
 Metrics/BlockLength:
   Exclude:

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
-## [0.1.0] - 2024-04-16
+## [0.1.1] - 2024-04-25
+
+- Update README.md so rubydoc.info formats correctly
+
+## [0.1.0] - 2024-04-25
 
 - Initial release

data/README.md

@@ -1,42 +1,56 @@
 # SortedContainers
 
-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.
+[Documentation](https://www.rubydoc.info/gems/sorted_containers/0.1.1)
+
+[![Gem Version](https://badge.fury.io/rb/sorted_containers.svg)](https://badge.fury.io/rb/sorted_containers)
+
+SortedContainers is a fast implementation of sorted arrays, sets, and hashes in pure Ruby. It is based on the [sortedcontainers](https://grantjenks.com/docs/sortedcontainers/) Python library by Grant Jenks.
 
 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.
+SortedContainers exploits the fact that modern computers are good at shifting arrays in memory. We sacrifice theoretical 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.
+Modern 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.
 
-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.
+You also save memory by not having to store pointers to children nodes, and you benefit from the cache locality of arrays. When you iterate over a sorted array, you are more likely to access elements that are close together in memory.
 
-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.
+But we can do better if we have a lot of elements. We can break up the array so fewer elements have to be moved when a new element is inserted. 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.
+This often outperforms the more common tree-based data structures like red-black trees with `O(log n)` insertions, deletions, and lookups. We sacrifice theoretical time complexity for practical performance.
 
-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.
+The size of the subarrays 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.
+
+SortedSet and SortedHash are implemented using a SortedArray to keep track of the order, and then also use a standard Set and Hash for quick lookups.
 
 ## 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.
+[SortedSet](https://github.com/knu/sorted_set) is a C extension red-black tree implementation. It is the fastest Ruby implementation of a sorted set that I could find. I used it as a benchmark to compare the performance of SortedContainers.
+
+Every test was run 5 times and the average was taken.
 
-Note: I do not know why initialization is faster for 4 million than 3 million elements. This was consistant across multiple runs.
+You can see that SortedContainers has comparable performance for add and delete, and much better performance for iteration, initialization, and include.
 
 - 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%">
+
+<img src="https://github.com/GarrisonJ/sorted_containers/blob/main/benchmark/initialize_performance_comparison.png?raw=true" width="50%">
+
+<img src="https://github.com/GarrisonJ/sorted_containers/blob/main/benchmark/add_performance_comparison.png?raw=true" width="50%">
+
+<img src="https://github.com/GarrisonJ/sorted_containers/blob/main/benchmark/delete_performance_comparison.png?raw=true" width="50%">
+
+<img src="https://github.com/GarrisonJ/sorted_containers/blob/main/benchmark/iteration_performance_comparison.png?raw=true" width="50%">
+
+<img src="https://github.com/GarrisonJ/sorted_containers/blob/main/benchmark/include_performance_comparison.png?raw=true" width="50%">
 
 ## Installation
 
@@ -53,7 +67,7 @@ bundle install
 ```
 
 Or install it yourself as:
-    
+
 ```bash
 gem install sorted_containers
 ```

data/lib/sorted_containers/core_extensions.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# Array class is being extended to include methods for converting
+# an Array to a SortedSet, SortedHash, and SortedArray.
+class Array
+  # Converts the array to a SortedSet.
+  #
+  # @param load_factor [Integer] The load factor for the SortedSet.
+  # @return [SortedContainers::SortedSet] The new SortedSet.
+  def to_sorted_set(load_factor: SortedContainers::SortedArray::DEFAULT_LOAD_FACTOR)
+    SortedContainers::SortedSet.new(self, load_factor: load_factor)
+  end
+
+  # Converts the array to a SortedHash.
+  #
+  # @param load_factor [Integer] The load factor for the SortedHash.
+  # @return [SortedContainers::SortedHash] The new SortedHash.
+  def to_sorted_h(load_factor: SortedContainers::SortedArray::DEFAULT_LOAD_FACTOR)
+    hash = SortedContainers::SortedHash.new(load_factor: load_factor)
+    hash.merge!(self)
+  end
+
+  # Converts the array to a SortedArray.
+  #
+  # @param load_factor [Integer] The load factor for the SortedArray.
+  # @return [SortedContainers::SortedArray] The new SortedArray.
+  def to_sorted_a(load_factor: SortedContainers::SortedArray::DEFAULT_LOAD_FACTOR)
+    SortedContainers::SortedArray.new(self, load_factor: load_factor)
+  end
+end
+
+# Hash class is being extended to include a method for converting
+# a Hash to a SortedHash.
+class Hash
+  # Converts the hash to a SortedHash.
+  #
+  # @param load_factor [Integer] The load factor for the SortedHash.
+  # @return [SortedContainers::SortedHash] The new SortedHash.
+  def to_sorted_h(load_factor: SortedContainers::SortedArray::DEFAULT_LOAD_FACTOR)
+    hash = SortedContainers::SortedHash.new(load_factor: load_factor)
+    hash.merge!(self)
+    hash
+  end
+end
+
+# Set class is being extended to include a method for converting
+# a Set to a SortedSet.
+class Set
+  # Converts the set to a SortedSet.
+  #
+  # @param load_factor [Integer] The load factor for the SortedSet.
+  # @return [SortedContainers::SortedSet] The new SortedSet.
+  def to_sorted_set(load_factor: SortedContainers::SortedArray::DEFAULT_LOAD_FACTOR)
+    SortedContainers::SortedSet.new(self, load_factor: load_factor)
+  end
+end