{"id":31906603,"url":"https://github.com/garrisonj/sorted_containers","last_synced_at":"2025-10-13T14:53:15.204Z","repository":{"id":233624530,"uuid":"787565592","full_name":"GarrisonJ/sorted_containers","owner":"GarrisonJ","description":"Ruby Sorted Containers: Sorted Array, Sorted Hash, and Sorted Set","archived":false,"fork":false,"pushed_at":"2024-10-16T03:32:17.000Z","size":1689,"stargazers_count":28,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-08T07:00:14.413Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.rubydoc.info/gems/sorted_containers","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GarrisonJ.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-04-16T19:06:22.000Z","updated_at":"2025-05-01T19:02:39.000Z","dependencies_parsed_at":"2024-05-02T01:33:54.950Z","dependency_job_id":"a95cbef0-16d8-4879-94f1-fa729e6d763d","html_url":"https://github.com/GarrisonJ/sorted_containers","commit_stats":null,"previous_names":["garrisonj/sorted_containers"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/GarrisonJ/sorted_containers","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GarrisonJ%2Fsorted_containers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GarrisonJ%2Fsorted_containers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GarrisonJ%2Fsorted_containers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GarrisonJ%2Fsorted_containers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GarrisonJ","download_url":"https://codeload.github.com/GarrisonJ/sorted_containers/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GarrisonJ%2Fsorted_containers/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279015770,"owners_count":26085749,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-13T14:52:55.144Z","updated_at":"2025-10-13T14:53:15.200Z","avatar_url":"https://github.com/GarrisonJ.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SortedContainers\n\n[Documentation](https://www.rubydoc.info/gems/sorted_containers/0.1.1)\n\n[![Gem Version](https://badge.fury.io/rb/sorted_containers.svg)](https://badge.fury.io/rb/sorted_containers)\n\nSortedContainers is a fast implementation of sorted arrays, sets, and hashes in pure Ruby. \n\n- SortedArray, SortedSet, and SortedHash\n- Pure Ruby\n- Fast Performance\n- (almost) Identical API to Array, Set, and Hash\n- No dependencies\n- Benchmarks\n- Unit Tested\n\nThis library is based on the [sortedcontainers](https://grantjenks.com/docs/sortedcontainers/) Python library by Grant Jenks.\n\nSortedContainers 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.\n\nSortedContainers 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.\n\n## How it works\n\nModern 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.\n\nFor 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.\n\nYou 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.\n\nBut 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.\n\nThis 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.\n\nThe 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.\n\nSortedSet 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.\n\n## Benchmarks\n\n[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.\n\nEvery test was run 5 times and the average was taken.\n\nYou can see that SortedContainers has comparable performance for add and delete, and much better performance for iteration, initialization, and include.\n\n- MacBook Pro (16-inch, 2019)\n- 2.6 GHz 6-Core Intel Core i7, 16 GB 2667 MHz DDR4\n- Ruby 3.2.2\n- SortedContainers 0.1.0\n- SortedSet 1.0.3\n\n### Results (Lower is better)\n\n\u003cimg src=\"https://github.com/GarrisonJ/sorted_containers/blob/main/benchmark/initialize_performance_comparison.png?raw=true\" width=\"50%\"\u003e\n\n\u003cimg src=\"https://github.com/GarrisonJ/sorted_containers/blob/main/benchmark/add_performance_comparison.png?raw=true\" width=\"50%\"\u003e\n\n\u003cimg src=\"https://github.com/GarrisonJ/sorted_containers/blob/main/benchmark/delete_performance_comparison.png?raw=true\" width=\"50%\"\u003e\n\n\u003cimg src=\"https://github.com/GarrisonJ/sorted_containers/blob/main/benchmark/iteration_performance_comparison.png?raw=true\" width=\"50%\"\u003e\n\n\u003cimg src=\"https://github.com/GarrisonJ/sorted_containers/blob/main/benchmark/include_performance_comparison.png?raw=true\" width=\"50%\"\u003e\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'sorted_containers'\n```\n\nAnd then execute:\n\n```bash\nbundle install\n```\n\nOr install it yourself as:\n\n```bash\ngem install sorted_containers\n```\n\n## Usage\n\n    require 'sorted_containers'\n\n    # Create a new SortedArray\n    list = SortedContainers::SortedArray.new\n\n    # Add elements to the list\n    list \u003c\u003c 3\n    list \u003c\u003c 1\n    list \u003c\u003c 2\n\n    # Access elements by index\n    puts list[0] # =\u003e 1\n    puts list[1] # =\u003e 2\n    puts list[2] # =\u003e 3\n\n    # Access elements by index\n    puts list.first # =\u003e 1\n    puts list.last # =\u003e 3\n\n    # Remove elements from the list\n    list.delete(2)\n\n    # Iterate over the list\n    list.each do |element|\n      puts element\n    end\n\n    # Create a new SortedSet\n    set = SortedContainers::SortedSet.new\n\n    # Add elements to the set\n    set \u003c\u003c 3\n    set \u003c\u003c 1\n    set \u003c\u003c 2\n\n    # Access elements by index\n    puts set[0] # =\u003e 1\n    puts set[1] # =\u003e 2\n    puts set[2] # =\u003e 3\n\n    # Access elements by index\n    puts set.first # =\u003e 1\n    puts set.last # =\u003e 3\n\n    # Remove elements from the set\n    set.delete(2)\n\n    # Iterate over the set\n    set.each do |element|\n      puts element\n    end\n\n    # Create a new SortedHash\n    dict = SortedContainers::SortedHash.new\n\n    # Add elements to the dict\n    dict[3] = 'three'\n    dict[1] = 'one'\n    dict[2] = 'two'\n\n    # Access elements by key\n    puts dict[1] # =\u003e 'one'\n    puts dict[2] # =\u003e 'two'\n    puts dict[3] # =\u003e 'three'\n\n    # Access elements by index\n    puts dict.first # =\u003e [1, 'one']\n    puts dict.last # =\u003e [3, 'three']\n\n    # Remove elements from the dict\n    dict.delete(2)\n\n    # Iterate over the dict\n    dict.each do |key, value|\n      puts \"#{key}: #{value}\"\n    end\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug 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).\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n\n## Code of Conduct\n\nEveryone 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).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgarrisonj%2Fsorted_containers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgarrisonj%2Fsorted_containers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgarrisonj%2Fsorted_containers/lists"}