binary-heap-plus 0.2.0

Enhanced version of std::collections::BinaryHeap that supports max, min, and custom-order heaps.
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
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

# binary-heap-plus-rs


[![Build Status](https://travis-ci.org/sekineh/binary-heap-plus-rs.svg?branch=master)](https://travis-ci.org/sekineh/binary-heap-plus-rs)
[![Build status](https://ci.appveyor.com/api/projects/status/oewb6667ul5pl05d?svg=true)](https://ci.appveyor.com/project/sekineh/binary-heap-plus-rs)

Enhancement over Rust's `std::collections::BinaryHeap`.

It supports the following features and still maintains backward compatibility.
- Max heap
- Min heap
- Heap ordered by closure
- Heap ordered by key generated by closure

You can change the line

```
use std::collections::BinaryHeap;
```

to like below.

```
use binary_heap_plus::*;
```

Your code will compile as before unless you use unstable APIs.

This crate requires Rust 1.26 or later.

# Added muthods


## `BinaryHeap::new_xxx()`


- (original) `::new()`     // creates a max heap
- `::new_min()` // creates a min heap
- `::new_by(f)` // creates a heap ordered by the given closure `f`
- `::new_by_key(g)` // creates a heap ordered by key generated by the given closure `g`

## `BinaryHeap::with_capacity_xxx()`


- (original) `::with_capacity(n)` // creates a max heap with capacity `n`
- `::with_capacity_min(n)` // creates a min heap with capacity `n`
- `::with_capacity_by(n, f)` // creates a heap with capacity `n`, ordered by the given closure `f`
- `::with_capacity_by_key(n, g)` // creates a heap with capacity `n`,  ordered by key generated by the given closure `g`

## `BinaryHeap::from_vec()`


Currently, the `From<Vec<T>>` trait is implemented for max heap only.
If you add generic impl for other heaps, the existing code breaks, requires 
slight modification such as type annotation.

To maintain good compatibility with `std` version, `::from_vec()` method was added
for the same purpose.

# Changes


## v0.2.0


* [COMPATIBILITY CHANGE] Use `Compare` trait from `compare` crate instead of our own definition.
Most users should not be affected by this. TIP: External `Compare<T>` impls needs to be updated to use `Fn` instead of `FnMut`.
* [COMPATIBILITY CHANGE] rename feature `serde1` to `serde` in order to comply with the guideline: 
https://rust-lang-nursery.github.io/api-guidelines/interoperability.html#c-serde
* Refactor ctor impl.

## v0.1.6


* Add generic constructor `from_vec()` and `from_vec_cmp()`.
* Refactor other ctor to call above methods.

## v0.1.5


* Add `serde1` feature which adds Serialize/Deserialize

## v0.1.4


* Merge #1) Do not require T: Ord when a custom comparator is provided

## v0.1.3


* Add comprehensive CI based on `trust` CI template v0.1.2
* README.md tweaks.

## v0.1.2


* Cargo.toml tweaks

# Thanks


- I received many valuable feedback from Pre-RFC thread [1].
  - The current design is based on @ExpHP's suggestion that compiles on stable compiler.
  - DDOtten, steven099, CAD97, ExpHP, scottmcm, Nemo157 and gnzlbg, thanks for looking into the design!
- @ulysseB sent me a first pull request!
- @inesseq contributed feature `serde1`.

# References


See the following discussions for the background of the crate:
- [1] https://internals.rust-lang.org/t/pre-rfc-binaryheap-flexibility/7482
- https://users.rust-lang.org/t/binaryheap-flexibility-revisited-supporting-other-than-max-heap/17062
- https://users.rust-lang.org/t/binaryheap-flexibility/8766
- https://github.com/rust-lang/rust/issues/38886