str: impl Three-way quicksort

Author: douchuan

Makefile

@@ -19,6 +19,9 @@ bench:
 eg_quadratic:
 	@$(CARGO) run --example quadratic
 
+doc:
+	@$(CARGO) doc --open
+
 stats:
 	@echo "codes: "
 	@cloc . --exclude-dir=target

README.md

@@ -88,6 +88,7 @@ never worry about system crash.
 
 - Character indexed arrays (Alphabet, count.rs)
 - Radix sort (LSD, MSD)
+- Three-way quicksort (Quick3String, Quick3Way)
 
 ### Running
 

benches/sort.rs

@@ -3,6 +3,7 @@ extern crate test;
 
 use algo::sort;
 use algo::sort::util;
+use algo::strings::Quick3Way;
 use test::Bencher;
 
 #[bench]
@@ -154,6 +155,15 @@ fn large_quick(b: &mut Bencher) {
     });
 }
 
+#[bench]
+fn large_quick_3way(b: &mut Bencher) {
+    let data = util::random_data(util::DATA_LEN);
+    b.iter(|| {
+        let mut numbs = data.clone();
+        Quick3Way::sort(&mut numbs);
+    });
+}
+
 #[bench]
 fn large_sorted_asc_quick(b: &mut Bencher) {
     let data = util::sorted_data_asc(util::DATA_LEN);

benches/strings.rs

@@ -1,10 +1,11 @@
 #![feature(test)]
 extern crate test;
 
-use algo::strings::{util, LSD, MSD};
+use algo::strings::{util, Quick3String, LSD, MSD};
 use test::Bencher;
 
 const WORDS3: &'static str = include_str!("../res/strings/words3.txt");
+const SHELLS: &'static str = include_str!("../res/strings/shells.txt");
 
 #[allow(non_snake_case)]
 #[bench]
@@ -36,10 +37,19 @@ fn sort_str_LSD_radix(b: &mut Bencher) {
     });
 }
 
+#[allow(non_snake_case)]
+#[bench]
+fn sort_i32_LSD_radix(b: &mut Bencher) {
+    let mut nums: Vec<i32> = (0..1000).rev().collect();
+    b.iter(|| {
+        LSD::sort_i32(&mut nums);
+    });
+}
+
 #[allow(non_snake_case)]
 #[bench]
 fn sort_str_MSD_radix(b: &mut Bencher) {
-    let i = WORDS3;
+    let i = SHELLS;
     let mut words = extract_words(i);
     b.iter(|| {
         MSD::sort(&mut words);
@@ -48,10 +58,11 @@ fn sort_str_MSD_radix(b: &mut Bencher) {
 
 #[allow(non_snake_case)]
 #[bench]
-fn sort_i32_LSD_radix(b: &mut Bencher) {
-    let mut nums: Vec<i32> = (0..1000).rev().collect();
+fn sort_str_quick3strings(b: &mut Bencher) {
+    let i = SHELLS;
+    let mut words = extract_words(i);
     b.iter(|| {
-        LSD::sort_i32(&mut nums);
+        Quick3String::sort(&mut words);
     });
 }
 

note.txt

@@ -16,6 +16,8 @@ todo
 
 4. 画图展示Dijkstra’s algorithm的动态构建过程 (p657)
 
+5. fix mod/struct/fn doc error to make doc work well, add more docs
+
 ### 后记
 
 项目缘起

src/graph/mod.rs

@@ -1,17 +1,17 @@
 //!
 //! ## 图的典型应用
 //!
-//! | 应用       |   节点       ｜    连接
-//! |-----------|--------------|--------------
-//! | 地图       |   十字路口     |     公路
-//! | 网络内容    |    网页       |     超链接
-//! | 电路       |    元器件      |    导线
-//! | 任务调度    |     任务      |     限制条件
-//! | 商业交易    |     客户      |     交易
-//! | 配对       |     学生      |     申请
-//! | 计算机网络  |     网站      |     物理连接
-//! | 软件       |     方法      |     调用关系
-//! | 社交网络    |     人       |     友谊关系
+//! | 应用       |   节点       ｜    连接         |
+//! |-----------|--------------|-----------------|
+//! | 地图       |   十字路口     |     公路      |
+//! | 网络内容    |    网页       |     超链接      |
+//! | 电路       |    元器件      |    导线        |
+//! | 任务调度    |     任务      |     限制条件    |
+//! | 商业交易    |     客户      |     交易        |
+//! | 配对       |     学生      |     申请        |
+//! | 计算机网络  |     网站      |     物理连接     |
+//! | 软件       |     方法      |     调用关系     |
+//! | 社交网络    |     人       |     友谊关系      |
 
 #[macro_use]
 pub mod util;

src/sort/insert.rs

@@ -2,6 +2,8 @@
 //!
 //! 基本思想是将一个value插入到有序表中
 
+use std::cmp::Ordering;
+
 pub fn sort<T>(a: &mut [T])
 where
     T: Ord,
@@ -17,3 +19,36 @@ where
         }
     }
 }
+
+/// insertion sort a[lo..=hi], starting at d-th character
+pub fn sort_dth<T>(a: &mut [T], lo: usize, hi: usize, d: usize)
+where
+    T: AsRef<str> + Copy,
+{
+    for i in lo..=hi {
+        let mut j = i;
+        while j > lo && is_less(a[j].as_ref(), a[j - 1].as_ref(), d) {
+            a.swap(j, j - 1);
+            j -= 1;
+        }
+    }
+}
+
+/// is v less than w, starting at character d
+fn is_less(v: &str, w: &str, d: usize) -> bool {
+    for (a, b) in v.bytes().zip(w.bytes()).skip(d) {
+        match a.cmp(&b) {
+            Ordering::Less => return true,
+            Ordering::Equal => (),
+            Ordering::Greater => return false,
+        }
+    }
+    v.as_bytes().len() < w.as_bytes().len()
+}
+
+#[test]
+fn t_less() {
+    assert!(is_less("aaa", "aaaa", 0)); // len less
+    assert!(is_less("aaa", "aaaa", 1)); // len less
+    assert!(is_less("aaa", "abaa", 1)); // 'a' < 'b'
+}

src/strings/mod.rs

@@ -1,11 +1,12 @@
 pub mod alphabet;
 mod count;
-mod lsd;
-mod msd;
-mod quick3;
+pub mod lsd;
+pub mod msd;
+pub mod quick3;
 pub mod util;
 
 pub use alphabet::Alphabet;
 pub use count::Count;
 pub use lsd::LSD;
 pub use msd::MSD;
+pub use quick3::{Quick3String, Quick3Way};

src/strings/msd.rs

@@ -1,8 +1,11 @@
-//! Performance
+//! Sort an array of strings using MSD radix sort.
 //!
-//! The running time of MSD string sort depends on the data.
+//! # Performance
 //!
-//! For random inputs, MSD string sort examines just enough
+//! - The running time of MSD string sort depends on the data,
+//! key length does not play a role. Indeed, the random string
+//! model allows key length to approach infinity.
+//! - For random inputs, MSD string sort examines just enough
 //! characters to distinguish among the keys, and the running
 //! time is sublinear in the number of characters in the data
 //! (it examines a small fraction of the input characters).
@@ -50,14 +53,31 @@
 //! will not be many duplicates and the random model will apply;
 //! for a week’s worth of data on a local road, there will be numerous
 //! duplicates and performance will be closer to the worst case.
+//!
+//! The main challenge in getting maximum efficiency from MSD string
+//! sort on keys that are long strings is to deal with lack of randomness
+//! in the data. Typically, keys may have long stretches of equal data,
+//! or parts of them might fall in only a narrow range. For example,
+//! an information-processing application for student data might have
+//! keys that include graduation year (4 bytes, but one of four different
+//! values), state names (perhaps 10 bytes, but one of 50 different values),
+//! and gender (1 byte with one of two given values), as well as a person’s
+//! name (more similar to random strings, but probably not short, with
+//! nonuniform letter distributions, and with trailing blanks in a fixed-length
+//! field). Restrictions like these lead to large numbers of empty subarrays
+//! during the MSD string sort.
 
 #![allow(clippy::many_single_char_names)]
-use std::cmp::Ordering;
+use crate::sort;
+use crate::strings::util;
 use std::marker::PhantomData;
 
 const R: usize = 256; // extended ASCII alphabet size
 const CUTOFF: usize = 15; // cutoff to insertion sort
 
+/// The MSD provides static methods for sorting an
+/// array of extended ASCII strings using MSD radix
+/// sort.
 pub struct MSD<T> {
     _marker: PhantomData<T>,
 }
@@ -66,6 +86,7 @@ impl<T> MSD<T>
 where
     T: AsRef<str> + Copy,
 {
+    /// Rearranges the array of extended ASCII strings in ascending order.
     pub fn sort(a: &mut [T]) {
         let n = a.len();
         if n > 0 {
@@ -74,17 +95,18 @@ where
         }
     }
 
+    /// sort from a[lo] to a[hi], starting at the d-th character
     fn do_sort(a: &mut [T], lo: usize, hi: usize, d: usize, aux: &mut [T]) {
         // cutoff to insertion sort for small subarrays
         if hi <= lo + CUTOFF {
-            Self::insertion(a, lo, hi, d);
+            sort::insert::sort_dth(a, lo, hi, d);
             return;
         }
 
         // compute frequency counts
         let mut count = [0; R + 2];
         for it in a.iter().take(hi + 1).skip(lo) {
-            let c = char_at(it.as_ref(), d);
+            let c = util::char_at(it.as_ref(), d);
             count[(c + 2) as usize] += 1;
         }
 
@@ -95,7 +117,7 @@ where
 
         // distribute
         for it in a.iter().take(hi + 1).skip(lo) {
-            let c = char_at(it.as_ref(), d);
+            let c = util::char_at(it.as_ref(), d);
             aux[count[(c + 1) as usize]] = *it;
             count[(c + 1) as usize] += 1;
         }
@@ -114,49 +136,4 @@ where
             }
         }
     }
-
-    fn insertion(a: &mut [T], lo: usize, hi: usize, d: usize) {
-        for i in lo..=hi {
-            let mut j = i;
-            while j > lo && less(a[j].as_ref(), a[j - 1].as_ref(), d) {
-                a.swap(j, j - 1);
-                j -= 1;
-            }
-        }
-    }
-}
-
-fn less(v: &str, w: &str, d: usize) -> bool {
-    for (a, b) in v.bytes().zip(w.bytes()).skip(d) {
-        match a.cmp(&b) {
-            Ordering::Less => return true,
-            Ordering::Equal => (),
-            Ordering::Greater => return false,
-        }
-    }
-    v.as_bytes().len() < w.as_bytes().len()
-}
-
-fn char_at(s: &str, d: usize) -> i32 {
-    let len = s.as_bytes().len();
-    if d >= len {
-        -1
-    } else {
-        s.as_bytes()[d] as i32
-    }
-}
-
-#[test]
-fn t_less() {
-    assert!(less("aaa", "aaaa", 0)); // len less
-    assert!(less("aaa", "aaaa", 1)); // len less
-    assert!(less("aaa", "abaa", 1)); // 'a' < 'b'
-}
-
-#[test]
-fn t_char_at() {
-    assert_eq!(b'a' as i32, char_at("abc", 0));
-    assert_eq!(b'b' as i32, char_at("abc", 1));
-    assert_eq!(b'c' as i32, char_at("abc", 2));
-    assert_eq!(-1, char_at("abc", 3));
 }