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.
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.