sorted_containers 0.1.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bfda36be3b51c7acd9fc3083b948af1e18db3031949849ead8d6d4c7bb387411
-  data.tar.gz: 54463856fd55d0c10233a43fbbe7c1e4f6f38b28e621c805b02fe5d57d0719a7
+  metadata.gz: 3402cc1b71fc79ef75e11c571123f82a2e79063688413922f8635dffaed9e179
+  data.tar.gz: 7a07b07ca3062d60cf0a92a60e1b3299629aa3d2ae3aaac46d81e8f9f8118d18
 SHA512:
-  metadata.gz: 3b5972feccf4fa6cd42e17f47cfbd2ba6d5b61350122428c0c4b26b70e2ca544dcb35e7eaea62aca1583fa1887da29b222239f16d0c139204cf2fafed77eb335
-  data.tar.gz: a67960920d793c0c968cfa0efa95b0806832d5d5684949cc9f20bac4d3595d269e00b27ac2d206b6522de1a6ba5a099a80029580a4b5933915b0e75dd99016bc
+  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/README.md

@@ -1,30 +1,38 @@
 # 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
@@ -59,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