# ubelt.orderedset module

This module exposes the `OrderedSet` class, which is a collection of unique items that maintains the order in which the items were added. An `OrderedSet` (or its alias `oset`) behaves very similarly to Python’s builtin `set` object, the main difference being that an `OrderedSet` can efficiently lookup its items by index.

Example

    >>> import ubelt as ub
    >>> ub.oset([1, 2, 3])
    OrderedSet([1, 2, 3])
    >>> (ub.oset([1, 2, 3]) - {2}) | {2}
    OrderedSet([1, 3, 2])
    >>> [ub.oset([1, 2, 3])[i] for i in [1, 0, 2]]
    [2, 1, 3]

As of version (0.8.5), ubelt contains its own internal copy of `OrderedSet` in order to reduce external dependencies. The original standalone implementation lives in https://github.com/LuminosoInsight/ordered-set.

The original documentation is as follows:

An OrderedSet is a custom MutableSet that remembers its order, so that every entry has an index that can be looked up.

Based on a recipe originally posted to ActiveState Recipes by Raymond Hettiger, and released under the MIT license.

class ubelt.orderedset.OrderedSet(iterable=None)

  Bases: `MutableSet`, `Sequence`

  An OrderedSet is a custom MutableSet that remembers its order, so that every entry has an index that can be looked up.

  Variables:

    - items (List[Any]) – internal ordered representation.

    - map (Dict[Any, int]) – internal mapping from items to indices.

  Example

      >>> OrderedSet([1, 1, 2, 3, 2])
      OrderedSet([1, 2, 3])

  Parameters:

    iterable (None | Iterable) – input data

  copy()

    Return a shallow copy of this object.

    Returns:

      OrderedSet

    Example

        >>> this = OrderedSet([1, 2, 3])
        >>> other = this.copy()
        >>> this == other
        True
        >>> this is other
        False

  add(key)

    Add `key` as an item to this OrderedSet, then return its index.

    If `key` is already in the OrderedSet, return the index it already had.

    Parameters:

      key (Any) – the item to add

    Returns:

      the index of the items. Note, violates the Liskov Substitution Principle and might be changed.

    Return type:

      int

    Example

        >>> oset = OrderedSet()
        >>> oset.append(3)
        0
        >>> print(oset)
        OrderedSet([3])

  append(key)

    Add `key` as an item to this OrderedSet, then return its index.

    If `key` is already in the OrderedSet, return the index it already had.

    Parameters:

      key (Any) – the item to add

    Returns:

      the index of the items. Note, violates the Liskov Substitution Principle and might be changed.

    Return type:

      int

    Example

        >>> oset = OrderedSet()
        >>> oset.append(3)
        0
        >>> print(oset)
        OrderedSet([3])

  update(sequence)

    Update the set with the given iterable sequence, then return the index of the last element inserted.

    Parameters:

      sequence (Iterable) – items to add to this set

    Example

        >>> oset = OrderedSet([1, 2, 3])
        >>> oset.update([3, 1, 5, 1, 4])
        4
        >>> print(oset)
        OrderedSet([1, 2, 3, 5, 4])

  index(key, start=0, stop=None)

    Get the index of a given entry, raising an IndexError if it’s not present.

    key can be a non-string iterable of entries, in which case this returns a list of indices.

    Parameters:

      - key (Any) – item to find the position of

      - start (int) – not supported yet

      - stop (int | None) – not supported yet

    Returns:

      int

    Example

        >>> oset = OrderedSet([1, 2, 3])
        >>> oset.index(2)
        1

  get_loc(key, start=0, stop=None)

    Get the index of a given entry, raising an IndexError if it’s not present.

    key can be a non-string iterable of entries, in which case this returns a list of indices.

    Parameters:

      - key (Any) – item to find the position of

      - start (int) – not supported yet

      - stop (int | None) – not supported yet

    Returns:

      int

    Example

        >>> oset = OrderedSet([1, 2, 3])
        >>> oset.index(2)
        1

  get_indexer(key, start=0, stop=None)

    Get the index of a given entry, raising an IndexError if it’s not present.

    key can be a non-string iterable of entries, in which case this returns a list of indices.

    Parameters:

      - key (Any) – item to find the position of

      - start (int) – not supported yet

      - stop (int | None) – not supported yet

    Returns:

      int

    Example

        >>> oset = OrderedSet([1, 2, 3])
        >>> oset.index(2)
        1

  pop()

    Remove and return the last element from the set.

    Raises KeyError if the set is empty.

    Returns:

      Any

    Example

        >>> oset = OrderedSet([1, 2, 3])
        >>> oset.pop()
        3

  discard(key)

    Remove an element. Do not raise an exception if absent.

    The MutableSet mixin uses this to implement the .remove() method, which does raise an error when asked to remove a non-existent item.

    Parameters:

      key (Any) – item to remove.

    Example

        >>> oset = OrderedSet([1, 2, 3])
        >>> oset.discard(2)
        >>> print(oset)
        OrderedSet([1, 3])
        >>> oset.discard(2)
        >>> print(oset)
        OrderedSet([1, 3])

  clear()

    Remove all items from this OrderedSet.

  union(*sets)

    Combines all unique items. Each items order is defined by its first appearance.

    Parameters:

      *sets – zero or more other iterables to operate on

    Returns:

      OrderedSet

    Example

        >>> oset = OrderedSet.union(OrderedSet([3, 1, 4, 1, 5]), [1, 3], [2, 0])
        >>> print(oset)
        OrderedSet([3, 1, 4, 5, 2, 0])
        >>> oset.union([8, 9])
        OrderedSet([3, 1, 4, 5, 2, 0, 8, 9])
        >>> oset | {10}
        OrderedSet([3, 1, 4, 5, 2, 0, 10])

  intersection(*sets)

    Returns elements in common between all sets. Order is defined only by the first set.

    Parameters:

      *sets – zero or more other iterables to operate on

    Returns:

      OrderedSet

    Example

        >>> from ubelt.orderedset import *  # NOQA
        >>> oset = OrderedSet.intersection(OrderedSet([0, 1, 2, 3]), [1, 2, 3])
        >>> print(oset)
        OrderedSet([1, 2, 3])
        >>> oset.intersection([2, 4, 5], [1, 2, 3, 4])
        OrderedSet([2])
        >>> oset.intersection()
        OrderedSet([1, 2, 3])

  difference(*sets)

    Returns all elements that are in this set but not the others.

    Parameters:

      *sets – zero or more other iterables to operate on

    Returns:

      OrderedSet

    Example

        >>> OrderedSet([1, 2, 3]).difference(OrderedSet([2]))
        OrderedSet([1, 3])
        >>> OrderedSet([1, 2, 3]).difference(OrderedSet([2]), OrderedSet([3]))
        OrderedSet([1])
        >>> OrderedSet([1, 2, 3]) - OrderedSet([2])
        OrderedSet([1, 3])
        >>> OrderedSet([1, 2, 3]).difference()
        OrderedSet([1, 2, 3])

  issubset(other)

    Report whether another set contains this set.

    Parameters:

      other (Iterable) – check if items in other are all contained in self.

    Returns:

      bool

    Example

        >>> OrderedSet([1, 2, 3]).issubset({1, 2})
        False
        >>> OrderedSet([1, 2, 3]).issubset({1, 2, 3, 4})
        True
        >>> OrderedSet([1, 2, 3]).issubset({1, 4, 3, 5})
        False

  issuperset(other)

    Report whether this set contains another set.

    Parameters:

      other (Iterable) – check all items in self are contained in other.

    Returns:

      bool

    Example

        >>> OrderedSet([1, 2]).issuperset([1, 2, 3])
        False
        >>> OrderedSet([1, 2, 3, 4]).issuperset({1, 2, 3})
        True
        >>> OrderedSet([1, 4, 3, 5]).issuperset({1, 2, 3})
        False

  symmetric_difference(other)

    Return the symmetric difference of two OrderedSets as a new set. That is, the new set will contain all elements that are in exactly one of the sets.

    Their order will be preserved, with elements from self preceding elements from other.

    Parameters:

      other (Iterable) – items to operate on

    Returns:

      OrderedSet

    Example

        >>> this = OrderedSet([1, 4, 3, 5, 7])
        >>> other = OrderedSet([9, 7, 1, 3, 2])
        >>> this.symmetric_difference(other)
        OrderedSet([4, 5, 9, 2])

  _update_items(items)

    Replace the ‘items’ list of this OrderedSet with a new one, updating self.map accordingly.

  difference_update(*sets)

    Update this OrderedSet to remove items from one or more other sets.

    Example

        >>> this = OrderedSet([1, 2, 3])
        >>> this.difference_update(OrderedSet([2, 4]))
        >>> print(this)
        OrderedSet([1, 3])

        >>> this = OrderedSet([1, 2, 3, 4, 5])
        >>> this.difference_update(OrderedSet([2, 4]), OrderedSet([1, 4, 6]))
        >>> print(this)
        OrderedSet([3, 5])

  intersection_update(other)

    Update this OrderedSet to keep only items in another set, preserving their order in this set.

    Parameters:

      other (Iterable) – items to operate on

    Example

        >>> this = OrderedSet([1, 4, 3, 5, 7])
        >>> other = OrderedSet([9, 7, 1, 3, 2])
        >>> this.intersection_update(other)
        >>> print(this)
        OrderedSet([1, 3, 7])

  symmetric_difference_update(other)

    Update this OrderedSet to remove items from another set, then add items from the other set that were not present in this set.

    Parameters:

      other (Iterable) – items to operate on

    Example

        >>> this = OrderedSet([1, 4, 3, 5, 7])
        >>> other = OrderedSet([9, 7, 1, 3, 2])
        >>> this.symmetric_difference_update(other)
        >>> print(this)
        OrderedSet([4, 5, 9, 2])

  _abc_impl = <_abc._abc_data object>

ubelt.orderedset.oset

  alias of `OrderedSet`