Toolshed: types
: XMinHeap
¶
Import XMinHeap
¶
from Naked.toolshed.types import XMinHeap
Import XMinHeap
from C Module¶
from Naked.toolshed.c.types import XMinHeap
The C module must be compiled before you import it. See the naked build documentation for more information.
Description¶
The XMinHeap
class is a min heap priority queue that extends Python heapq
. This class supports sorting of new items that are pushed to the queue by assigned priority and pop of the lowest priority item. It also supports the addition of attribute metadata on instantiation of the class.
-
class
Naked.toolshed.types.
XMinHeap
([attribute_dictionary])¶ Parameters: attribute_dictionary (dict) – (optional) a Python dictionary that is used to define the attributes of a new instance of a XMinHeap
. Key names are mapped to attribute names and their corresponding values are mapped to the attribute values.Function Overload
-
__len__
()¶ Returns: (int) returns the number of items in the XMinHeap
. This allows you to uselen(XMinHeap())
to determine the number of items in the priority queue.
XMinHeap Methods
-
length
()¶ Returns: (int) returns the number of items in the XMinHeap
-
pop
()¶ Pops the lowest priority item off of the queue.
Returns: (item type dependent) returns the lowest priority item which is defined as the item that has the lowest item_priority
value. If multiple items have the same value, they are returned on a first-in, first-out order (FIFO). If the queue is empty, returnsNone
.
-
push
(queue_item, item_priority)¶ Pushes an item to the queue with the priority defined
Parameters: - queue_item (any) – an object that is added to the priority queue.
- item_priority (int) – an integer that represents the priority of the item from 1 (min) to x (max). It is possible to assign the same priority level to multiple items in the queue.
-
pushpop
(queue_item, item_priority)¶ Pushes an item to the queue and immediately pops and returns the lowest priority item off of the queue.
Parameters: - queue_item (any) – an object that is added to the priority queue.
- item_priority (int) – an integer that represents the priority of the item from 1 (min) to x (max). It is possible to assign the same priority level to multiple items in the queue.
Returns: (item type dependent) returns the lowest priority item which is defined as the item that has the lowest
item_priority
value. If multiple items have the same value, they are returned on a first-in, first-out order (FIFO). If the item that is pushed to the queue is the lowest priority item, it is immediately returned. If the queue is empty, returnsNone
.
-
Examples¶
Create a New Instance of XMinHeap, No Metadata
from Naked.toolshed.types import XMinHeap
xmh = XMinHeap()
Create a New Instance of XMinHeap, With Metadata
from Naked.toolshed.types import XMinHeap
xmh = XMinHeap({'heapnumber': 1})
Access XMinHeap Attribute Data
from Naked.toolshed.types import XMinHeap
xmh = XMinHeap({'heapnumber': 1})
print(xmh.heapnumber) # prints 1
Push Items on to the XMinHeap
from Naked.toolshed.types import XMinHeap
xmh = XMinHeap({'heapnumber': 1})
xmh.push('eat eggs', 1)
xmh.push('eat spam', 2)
Pop Items off of the XMinHeap by Priority
from Naked.toolshed.types import XMinHeap
xmh = XMinHeap({'heapnumber': 1})
xmh.push('eat eggs', 1)
xmh.push('eat spam', 2)
print(xmh.pop()) # prints 'eat eggs'
print(xmh.pop()) # prints 'eat spam'
Priority Tie Handling with XMinHeap
from Naked.toolshed.types import XMinHeap
xmh = XMinHeap({'heapnumber': 1})
xmh.push('eat eggs', 1)
xmh.push('eat spam', 1) # same priority as above
print(xmh.pop()) # prints 'eat eggs' --> FIFO handling of ties
print(xmh.pop()) # prints 'eat spam'
Simultaneous Push and Pop with XMinHeap
from Naked.toolshed.types import XMinHeap
xmh = XMinHeap({'heapnumber': 1})
xmh.push('eat eggs', 1)
xmh.push('eat spam', 2)
result = xmh.pushpop('buy Chris a coffee', 1)
print(result) # prints 'eat eggs'
print(xmh.pop()) # prints 'buy Chris a coffee' ;)
print(xmh.pop()) # prints 'eat spam'