diff --git a/README.md b/README.md index f66fadd..0e48f2f 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,15 @@ [![Pypi](https://img.shields.io/pypi/v/ordered-set.svg)](https://pypi.python.org/pypi/ordered-set) +A StableSet is a mutable set that remembers its insertion order. +Featuring: Fast O(1) insertion, deletion, iteration and membership testing. +But slow O(N) Index Lookup. + An OrderedSet is a mutable data structure that is a hybrid of a list and a set. -It remembers the order of its entries, and every entry has an index number that -can be looked up. +It remembers its insertion order so that every entry has an index that can be looked up. +Featuring: O(1) Index lookup, insertion, iteration and membership testing. +But slow O(N) Deletion. + +Both have similar interfaces but differ in respect of their implementation and performance. ## Installation @@ -105,12 +112,23 @@ in OrderedSet). ## Authors OrderedSet was implemented by Elia Robyn Lake (maiden name: Robyn Speer). +StableSet was implemented by Idan Miara, built upon the foundations of OrderedSet. Jon Crall contributed changes and tests to make it fit the Python set API. Roman Inflianskas added the original type annotations. - ## Comparisons +A StableSet is a mutable set that remembers its insertion order. +Featuring: Fast O(1) insertion, deletion, iteration and membership testing. +But slow O(N) Index Lookup. + +An OrderedSet is a mutable data structure that is a hybrid of a list and a set. +It remembers its insertion order so that every entry has an index that can be looked up. +Featuring: O(1) Index lookup, insertion, iteration and membership testing. +But slow O(N) Deletion. + +Both have similar interfaces but differ in respect of their implementation and performance. + The original implementation of OrderedSet was a [recipe posted to ActiveState Recipes][recipe] by Raymond Hettiger, released under the MIT license. @@ -120,14 +138,15 @@ Hettiger's implementation kept its content in a doubly-linked list referenced by dict. As a result, looking up an item by its index was an O(N) operation, while deletion was O(1). -This version makes different trade-offs for the sake of efficient lookups. Its -content is a standard Python list instead of a doubly-linked list. This +This version of OrderedSet makes different trade-offs for the sake of efficient lookups. +Its content is a standard Python list instead of a doubly-linked list. This provides O(1) lookups by index at the expense of O(N) deletion, as well as slightly faster iteration. -In Python 3.6 and later, the built-in `dict` type is inherently ordered. If you -ignore the dictionary values, that also gives you a simple ordered set, with -fast O(1) insertion, deletion, iteration and membership testing. However, `dict` -does not provide the list-like random access features of OrderedSet. You -would have to convert it to a list in O(N) to look up the index of an entry or -look up an entry by its index. +## Other implementations + +The included implementation of OrderedSet is fully compatible with the following implementation: +* https://pypi.org/project/orderedset/ - by Simon Percivall (faster implementation of `OrderedSet` using Cython, which currently only works for Python<3.9) + +The included implementation of StableSet is fully compatible with the following implementation: +* https://pypi.org/project/Ordered-set-37/ - by Xavier Bustamante Talavera (Similar basic implementation for `StableSet`, but named `OrderedSet`)