--- title: PriorityQueue --- A priority queue is a data structure that maintains elements in a priority order. Elements with higher priority are served before elements with lower priority when extracting from the priority queue. An immutable priority queue implementation is available in the `Immutable` submodule.
Added in 0.5.3 No other changes yet.
```grain from "priorityqueue" include Priorityqueue ``` ## Types Type declarations included in the PriorityQueue module. ### PriorityQueue.**PriorityQueue** ```grain type PriorityQueue ``` Mutable data structure which maintains a priority order for its elements. ## Values Functions and constants included in the PriorityQueue module. ### PriorityQueue.**make**
Added in 0.5.3
versionchanges
0.6.0Merged with `makeSized`; modified signature to accept size
```grain make: (?compare: ((a, a) => Number), ?size: Number) => PriorityQueue ``` Creates a new priority queue with a given internal storage size and a comparator function, which is used to determine priority of elements. The comparator function takes two elements and must return 0 if both share priority, a positive number if the first has greater priority, and a negative number if the first has less priority. Generally, you won't need to care about the storage size of your priority queue and can use the default size. Parameters: | param | type | description | | ---------- | ------------------ | ------------------------------------------------------- | | `?compare` | `(a, a) => Number` | The comparator function used to indicate priority order | | `?size` | `Number` | The initial storage size of the priority queue | Returns: | type | description | | ------------------ | ----------------------- | | `PriorityQueue` | An empty priority queue | Examples: ```grain PriorityQueue.make() // creates a min priority queue of numbers using the compare pervasive ``` ```grain PriorityQueue.make(compare=compare, size=32) // creates a min priority queue of numbers using the compare pervasive and an initial size of 32 ``` ```grain PriorityQueue.make((a, b) => String.length(b) - String.length(a)) // creates a priority queue by string length (longest to shortest) ``` ### PriorityQueue.**size**
Added in 0.5.3 No other changes yet.
```grain size: (pq: PriorityQueue) => Number ``` Gets the number of elements in a priority queue. Parameters: | param | type | description | | ----- | ------------------ | ----------------------------- | | `pq` | `PriorityQueue` | The priority queue to inspect | Returns: | type | description | | -------- | -------------------------------------------- | | `Number` | The number of elements in the priority queue | ### PriorityQueue.**isEmpty**
Added in 0.5.3 No other changes yet.
```grain isEmpty: (pq: PriorityQueue) => Bool ``` Determines if the priority queue contains no elements. Parameters: | param | type | description | | ----- | ------------------ | --------------------------- | | `pq` | `PriorityQueue` | The priority queue to check | Returns: | type | description | | ------ | ----------------------------------------------------------- | | `Bool` | `true` if the priority queue is empty and `false` otherwise | ### PriorityQueue.**push**
Added in 0.5.3 No other changes yet.
```grain push: (val: a, pq: PriorityQueue) => Void ``` Adds a new element to the priority queue. Parameters: | param | type | description | | ----- | ------------------ | ---------------------------------------- | | `val` | `a` | The value to add into the priority queue | | `pq` | `PriorityQueue` | The priority queue to update | ### PriorityQueue.**peek**
Added in 0.5.3 No other changes yet.
```grain peek: (pq: PriorityQueue) => Option ``` Retrieves the highest priority element in the priority queue. It is not removed from the queue. Parameters: | param | type | description | | ----- | ------------------ | ----------------------------- | | `pq` | `PriorityQueue` | The priority queue to inspect | Returns: | type | description | | ----------- | ---------------------------------------------------------------------------------------------- | | `Option` | `Some(value)` containing the highest priority element or `None` if the priority queue is empty | ### PriorityQueue.**pop**
Added in 0.5.3 No other changes yet.
```grain pop: (pq: PriorityQueue) => Option ``` Removes and retrieves the highest priority element in the priority queue. Parameters: | param | type | description | | ----- | ------------------ | ----------------------------- | | `pq` | `PriorityQueue` | The priority queue to inspect | Returns: | type | description | | ----------- | ---------------------------------------------------------------------------------------------- | | `Option` | `Some(value)` containing the highest priority element or `None` if the priority queue is empty | ### PriorityQueue.**drain**
Added in 0.5.3 No other changes yet.
```grain drain: (pq: PriorityQueue) => List ``` Clears the priority queue and produces a list of all of the elements in the priority queue in priority order. Parameters: | param | type | description | | ----- | ------------------ | --------------------------- | | `pq` | `PriorityQueue` | The priority queue to drain | Returns: | type | description | | --------- | -------------------------------------------------------- | | `List` | A list of all elements in the priority in priority order | ### PriorityQueue.**fromArray**
Added in 0.5.4
versionchanges
0.6.0Made `compare` a default argument
```grain fromArray: (array: Array, ?compare: ((a, a) => Number)) => PriorityQueue ``` Constructs a new priority queue initialized with the elements in the array using a custom comparator function, which is used to determine priority of elements. The comparator function takes two elements and must return 0 if both share priority, a positive number if the first has greater priority, and a negative number if the first has less priority. Parameters: | param | type | description | | ---------- | ------------------ | --------------------------------------------------------- | | `array` | `Array` | An array of values used to initialize the priority queue | | `?compare` | `(a, a) => Number` | A comparator function used to assign priority to elements | Returns: | type | description | | ------------------ | ------------------------------------------------------- | | `PriorityQueue` | A priority queue containing the elements from the array | ### PriorityQueue.**fromList**
Added in 0.5.3
versionchanges
0.6.0Made `compare` a default argument
```grain fromList: (list: List, ?compare: ((a, a) => Number)) => PriorityQueue ``` Constructs a new priority queue initialized with the elements in the list using a custom comparator function, which is used to determine priority of elements. The comparator function takes two elements and must return 0 if both share priority, a positive number if the first has greater priority, and a negative number if the first has less priority. Parameters: | param | type | description | | ---------- | ------------------ | --------------------------------------------------------- | | `list` | `List` | A list of values used to initialize the priority queue | | `?compare` | `(a, a) => Number` | A comparator function used to assign priority to elements | Returns: | type | description | | ------------------ | ------------------------------------------------------ | | `PriorityQueue` | A priority queue containing the elements from the list | ## PriorityQueue.Immutable An immutable priority queue implementation.
Added in 0.6.0
versionchanges
0.5.4Originally in `"immutablepriorityqueue"` module
### Types Type declarations included in the PriorityQueue.Immutable module. #### PriorityQueue.Immutable.**PriorityQueue** ```grain type PriorityQueue ``` Immutable data structure which maintains a priority order for its elements. ### Values Functions and constants included in the PriorityQueue.Immutable module. #### PriorityQueue.Immutable.**empty**
Added in 0.6.0
versionchanges
0.5.4Originally in `"immutablepriorityqueue"` module
```grain empty: PriorityQueue ``` An empty priority queue with the default `compare` comparator. #### PriorityQueue.Immutable.**make**
Added in 0.6.0
versionchanges
0.5.3Originally in `"immutablepriorityqueue"` module with `compare` being a required argument
```grain make: (?compare: ((a, a) => Number)) => PriorityQueue ``` Creates a new priority queue with a comparator function, which is used to determine priority of elements. The comparator function takes two elements and must return 0 if both share priority, a positive number if the first has greater priority, and a negative number if the first has less priority. Parameters: | param | type | description | | ---------- | ------------------ | ------------------------------------------------------- | | `?compare` | `(a, a) => Number` | The comparator function used to indicate priority order | Returns: | type | description | | ------------------ | ----------------------- | | `PriorityQueue` | An empty priority queue | Examples: ```grain PriorityQueue.Immutable.make(compare) // creates a min priority queue of numbers using the compare pervasive ``` ```grain PriorityQueue.Immutable.make((a, b) => String.length(b) - String.length(a)) // creates a priority queue by string length (longest to shortest) ``` #### PriorityQueue.Immutable.**size**
Added in 0.6.0
versionchanges
0.5.3Originally in `"immutablepriorityqueue"` module
```grain size: (pq: PriorityQueue) => Number ``` Gets the number of elements in a priority queue. Parameters: | param | type | description | | ----- | ------------------ | ----------------------------- | | `pq` | `PriorityQueue` | The priority queue to inspect | Returns: | type | description | | -------- | -------------------------------------------- | | `Number` | The number of elements in the priority queue | #### PriorityQueue.Immutable.**isEmpty**
Added in 0.6.0
versionchanges
0.5.3Originally in `"immutablepriorityqueue"` module
```grain isEmpty: (pq: PriorityQueue) => Bool ``` Determines if the priority queue contains no elements. Parameters: | param | type | description | | ----- | ------------------ | --------------------------- | | `pq` | `PriorityQueue` | The priority queue to check | Returns: | type | description | | ------ | ----------------------------------------------------------- | | `Bool` | `true` if the priority queue is empty and `false` otherwise | #### PriorityQueue.Immutable.**push**
Added in 0.6.0
versionchanges
0.5.3Originally in `"immutablepriorityqueue"` module
```grain push: (val: a, pq: PriorityQueue) => PriorityQueue ``` Produces a new priority queue by inserting the given element into the given priority queue. Parameters: | param | type | description | | ----- | ------------------ | ---------------------------------------- | | `val` | `a` | The value to add into the priority queue | | `pq` | `PriorityQueue` | The priority queue | Returns: | type | description | | ------------------ | ---------------------------------------------------- | | `PriorityQueue` | A new priority queue with the given element inserted | #### PriorityQueue.Immutable.**peek**
Added in 0.6.0
versionchanges
0.5.3Originally in `"immutablepriorityqueue"` module
```grain peek: (pq: PriorityQueue) => Option ``` Retrieves the highest priority element in the priority queue. It is not removed from the queue. Parameters: | param | type | description | | ----- | ------------------ | ----------------------------- | | `pq` | `PriorityQueue` | The priority queue to inspect | Returns: | type | description | | ----------- | ---------------------------------------------------------------------------------------------- | | `Option` | `Some(value)` containing the highest priority element or `None` if the priority queue is empty | #### PriorityQueue.Immutable.**pop**
Added in 0.6.0
versionchanges
0.5.3Originally in `"immutablepriorityqueue"` module
```grain pop: (pq: PriorityQueue) => PriorityQueue ``` Produces a new priority queue without the highest priority element in the given priority queue. If the input priority queue is empty, this function will return it. Parameters: | param | type | description | | ----- | ------------------ | ------------------ | | `pq` | `PriorityQueue` | The priority queue | Returns: | type | description | | ------------------ | --------------------------------------------------------- | | `PriorityQueue` | A new priority queue without the highest priority element | #### PriorityQueue.Immutable.**drain**
Added in 0.6.0
versionchanges
0.5.3Originally in `"immutablepriorityqueue"` module
```grain drain: (pq: PriorityQueue) => List ``` Produces a list of all elements in the priority queue in priority order. Parameters: | param | type | description | | ----- | ------------------ | --------------------------- | | `pq` | `PriorityQueue` | The priority queue to drain | Returns: | type | description | | --------- | -------------------------------------------------------- | | `List` | A list of all elements in the priority in priority order | #### PriorityQueue.Immutable.**fromList**
Added in 0.6.0
versionchanges
0.5.3Originally in `"immutablepriorityqueue"` module with `compare` being a required argument
```grain fromList: (list: List, ?compare: ((a, a) => Number)) => PriorityQueue ``` Constructs a new priority queue initialized with the elements in the list using a custom comparator function, which is used to determine priority of elements. The comparator function takes two elements and must return 0 if both share priority, a positive number if the first has greater priority, and a negative number if the first has less priority. Parameters: | param | type | description | | ---------- | ------------------ | --------------------------------------------------------- | | `list` | `List` | A list of values used to initialize the priority queue | | `?compare` | `(a, a) => Number` | A comparator function used to assign priority to elements | Returns: | type | description | | ------------------ | ------------------------------------------------------ | | `PriorityQueue` | A priority queue containing the elements from the list | #### PriorityQueue.Immutable.**fromArray**
Added in 0.6.0
versionchanges
0.5.4Originally in `"immutablepriorityqueue"` module with `compare` being a required argument
```grain fromArray: (array: Array, ?compare: ((a, a) => Number)) => PriorityQueue ``` Constructs a new priority queue initialized with the elements in the array using a custom comparator function, which is used to determine priority of elements. The comparator function takes two elements and must return 0 if both share priority, a positive number if the first has greater priority, and a negative number if the first has less priority. Parameters: | param | type | description | | ---------- | ------------------ | --------------------------------------------------------- | | `array` | `Array` | An array of values used to initialize the priority queue | | `?compare` | `(a, a) => Number` | A comparator function used to assign priority to elements | Returns: | type | description | | ------------------ | ------------------------------------------------------- | | `PriorityQueue` | A priority queue containing the elements from the array |