Merge pull request sekineh#8 from sekineh/sekineh-patch-1

add instruction to create various heaps

Author: sekineh

CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+* Quickstart section in the doc

Cargo.toml

@@ -7,7 +7,7 @@ license = "MIT"
 repository = "https://github.com/sekineh/binary-heap-plus-rs"
 readme = "README.md"
 keywords = ["binary", "heap", "priority", "queue"]
-category = ["data-structures", "algorithms", ]
+categories = ["data-structures", "algorithms", ]
 
 [dependencies]
 compare = "0.1.0"

README.md

@@ -11,39 +11,9 @@ It supports the following features and still maintains backward compatibility.
 - 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()`
+## Note on `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 

appveyor.yml

@@ -42,17 +42,14 @@ install:
 
 # TODO This is the "test phase", tweak it as you see fit
 test_script:
-  # we don't run the "test phase" when doing deploys
-  - if [%APPVEYOR_REPO_TAG%]==[false] (
-      cargo build --target %TARGET% &&
-      cargo build --target %TARGET% --features serde &&
-      cargo build --target %TARGET% --release &&
-      cargo build --target %TARGET% --release --features serde &&
-      cargo test --target %TARGET% &&
-      cargo test --target %TARGET% --features serde &&
-      cargo test --target %TARGET% --release &&
-      cargo test --target %TARGET% --release --features serde
-    )
+  - cargo build --target %TARGET%
+  - cargo test  --target %TARGET%
+  - cargo build --target %TARGET% --features serde
+  - cargo test  --target %TARGET% --features serde
+  - cargo build --target %TARGET% --release
+  - cargo test  --target %TARGET% --release
+  - cargo build --target %TARGET% --release --features serde
+  - cargo test  --target %TARGET% --release --features serde
 
 before_deploy:
   # TODO Update this to build the artifacts that matter to you

ci/script.sh

@@ -13,8 +13,10 @@ main() {
         return
     fi
 
+    cross clean
     cross test --target $TARGET
     cross test --target $TARGET --features serde
+    cross clean
     cross test --target $TARGET --release
     cross test --target $TARGET --release --features serde
 

src/lib.rs

@@ -1,16 +1,66 @@
 //! This crate provides `BinaryHeap` which is backward-compatible with `std::collections::BinaryHeap`.
-//! 
+//!
 //! Added features include:
 //! * Heaps other than max heap.
 //! * Optional `serde` feature.
+//!
+//! # Quick start
+//!
+//! ## Max/Min Heap
+//! 
+//! For max heap, `BiaryHeap::from_vec()` is the most versatile way to create a heap.
+//!
+//! ```rust
+//!     // extern crate binary_heap_plus;
+//!     use binary_heap_plus::*;
+//!
+//!     // max heap
+//!     let mut h: BinaryHeap<i32> = BinaryHeap::from_vec(vec![]);
+//!     // max heap with initial capacity
+//!     let mut h: BinaryHeap<i32> = BinaryHeap::from_vec(Vec::with_capacity(16));
+//!     // max heap from iterator
+//!     let mut h: BinaryHeap<i32> = BinaryHeap::from_vec((0..42).collect());
+//!     assert_eq!(h.pop(), Some(41));
+//! ```
 //! 
+//! Min heap is similar, but requires type annotation.
+//! 
+//! ```rust
+//!     // extern crate binary_heap_plus;
+//!     use binary_heap_plus::*;
+//!
+//!     // min heap
+//!     let mut h: BinaryHeap<i32, MinComparator> = BinaryHeap::from_vec(vec![]);
+//!     // min heap with initial capacity
+//!     let mut h: BinaryHeap<i32, MinComparator> = BinaryHeap::from_vec(Vec::with_capacity(16));
+//!     // min heap from iterator
+//!     let mut h: BinaryHeap<i32, MinComparator> = BinaryHeap::from_vec((0..42).collect());
+//!     assert_eq!(h.pop(), Some(0));
+//! ```
+//!
+//! ## Custom Heap
+//! 
+//! For custom heap, `BinaryHeap::from_vec_cmp()` works in a similar way to max/min heap. The only difference is that you add the comparator closure with apropriate signature.
+//! 
+//! ```rust
+//!     // extern crate binary_heap_plus;
+//!     use binary_heap_plus::*;
+//!
+//!     // custom heap: ordered by second value (_.1) of the tuples; min first
+//!     let mut h = BinaryHeap::from_vec_cmp(
+//!         vec![(1, 5), (3, 2), (2, 3)],
+//!         |a: &(i32, i32), b: &(i32, i32)| b.1.cmp(&a.1), // comparator closure here
+//!     );
+//!     assert_eq!(h.pop(), Some((3, 2)));
+//! ```
+//!
 //! # Constructers
 //!
 //! ## Generic methods to create different kind of heaps from initial `vec` data.
 //!
 //! * `BinaryHeap::from_vec(vec)`
 //! * `BinaryHeap::from_vec_cmp(vec, cmp)`
-//! 
+//!
 //! ```
 //! use binary_heap_plus::*;
 //!
@@ -23,7 +73,7 @@
 //! assert_eq!(heap.pop(), Some(1));
 //!
 //! // custom-sort heap
-//! let mut heap = BinaryHeap::from_vec_cmp(vec![1,5,3], FnComparator(|a: &i32, b: &i32| b.cmp(a)));
+//! let mut heap = BinaryHeap::from_vec_cmp(vec![1,5,3], |a: &i32, b: &i32| b.cmp(a));
 //! assert_eq!(heap.pop(), Some(1));
 //!
 //! // custom-key heap
@@ -47,7 +97,7 @@
 //!
 
 mod binary_heap;
-pub use binary_heap::*;
+pub use crate::binary_heap::*;
 extern crate compare;
 extern crate core;
 #[cfg(feature = "serde")]