Orderable Dictionary

Python’s built-in collections.OrderedDict only remembers the order of which keys were inserted into it, and does not allow users to re-order the keys and/or insert new keys into arbitrary position in the current key order.

OrderableDict, Orderable Dictionary, is almost exactly the same as python collections.OrderedDict with the added ability to order & re-order the keys that are inserted into it.

# Example
# -------
#
#   using OrderableDict

from pyats.datastructures import OrderableDict

# create a blank OrderableDict
obj = OrderableDict()

# all added keys are remembered in the order as they are added
obj['A'] = 1
obj['B'] = 2
obj['C'] = 3
# OrderableDict([('A', 1), ('B', 2), ('C', 3)])

# use move() api to move an existing key to a new positions
# eg, moving 'C' key and value to first position
obj.move('C', 0)
# OrderableDict([('C', 3), ('A', 1), ('B', 2)])

# use insert() to insert new keys into arbitrary positions
# eg, insert 'D' key into 2nd position
obj.insert('D', 4, position = 1)
# OrderableDict([('C', 3), ('D', 4), ('A', 1), ('B', 2)])

OrderableDict behavior is normally exactly identical to those of python collections.OrderedDict, except that it comes with two new APIs:

move(key, position)

moves an existing key in the datastructure to just before position.

insert(key, value, position)

insert a new key/value pair into the datastructure just before position.

When using OrderableDict, the``position`` argument refers to the corresponding index value of the list of all currently ordered keys. That is, if you create a list from the ordered keys of the current datastrucuture, each key’s position is exactly its list index value.

Known Limitations

The implementation of OrderableDict``is not as efficient as``dict and OrderedDict. A separate list is used internally to store the current order of keys, and thus can lead to a larger memory footprint. This problem may be further exacerbated if the keys are very large.