fpq 0.4.0

Priority Queue with scoring Function
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

# FPQ 
Priority Queue with scoring function

# Usage

- Rust Edition: 2024
- MSRV: 1.85

```toml
[dependencies]
fpq = "0.3.0"
```

In the code, you first need to create an instance with `fpq::PriorityQueue::new`. It takes a boxed closure that converts your item type `&T` into score type `S: Ord`. Then you can use `push/pop/peek` methods in the same way as `std::collections::BinaryHeap`.

# Example

```rust
use std::cmp::Reverse;

use fpq::PriorityQueue;

fn main() {
    // a score function that returns the length of a string
    let score_fn = Box::new(|s: &String| s.len());
    // create a new priority queue with the score function
    let mut queue = PriorityQueue::new(score_fn);

    // the queue is empty at the beginning
    assert!(queue.peek().is_none());

    // push some items into the queue
    // the score function is used to calculate the score of each item
    queue.push("a".to_string()); // score = 1
    queue.push("ccc".to_string()); // score = 3
    queue.push("bb".to_string()); // score = 2

    // you can also push an item with a explicit score
    queue.push_with_score("b".to_string(), 10); // score = 10

    // peek the item with the highest priority
    assert_eq!(queue.peek(), Some((10, &"b".to_string())));

    // pop the item with the highest priority
    assert_eq!(queue.pop(), Some((10, "b".to_string())));
    assert_eq!(queue.pop(), Some((3, "ccc".to_string())));
    assert_eq!(queue.pop(), Some((2, "bb".to_string())));
    assert_eq!(queue.pop(), Some((1, "a".to_string())));

    // the queue is empty again
    assert!(queue.peek().is_none());

    // you can also use a reverse order
    let score_fn = Box::new(|s: &String| Reverse(s.len()));
    let mut queue = PriorityQueue::new(score_fn);

    queue.push("a".to_string()); // score = -1
    queue.push("ccc".to_string()); // score = -3
    queue.push("bb".to_string()); // score = -2

    // remember to use Reverse when pushing an item with an explicit score
    queue.push_with_score("b".to_string(), Reverse(10)); // score = -10

    assert_eq!(queue.peek(), Some((Reverse(1), &"a".to_string())));
    assert_eq!(queue.pop(), Some((Reverse(1), "a".to_string())));
    assert_eq!(queue.pop(), Some((Reverse(2), "bb".to_string())));
    assert_eq!(queue.pop(), Some((Reverse(3), "ccc".to_string())));
    assert_eq!(queue.pop(), Some((Reverse(10), "b".to_string())));

    assert!(queue.peek().is_none());
}
```