Reorganize crates, document a bunch of em

Author: fasterthanlime

Cargo.lock

@@ -1,5 +1,6 @@
 [workspace]
 members = [
+    "crates/sacabase",
     "crates/divsufsort",
     "crates/cdivsufsort",
     "crates/divsuftest",

Cargo.toml

@@ -0,0 +1,19 @@
+
+# suffixsearch
+
+[![Build Status](https://travis-ci.org/fasterthanlime/suffixsearch.svg?branch=master)](https://travis-ci.org/fasterthanlime/suffixsearch)
+
+A collection of SACAs (suffix array construction algorithms) and other
+methods of indexing and searching for substrings in all suffixes of a
+given input.
+
+## Crates
+
+  * [divsufsort](crates/divsufsort) is Rust version of Yuta Mori's `libdivsufsort`, ported by hand
+  * [cdivsfusort](crates/cdivsufsort) is Yuta Mori's original `libdivsufsort`, built with the `cc` crate
+  * [divsuftest](crates/divsuftest) is a test executable that allows comparing against the
+    above crates.
+  * [dc3](crates/dc3) is a naive work-in-progress implementation of DC3 (Differential Cover, v=3)
+
+See the crates' README files for more information on their status,
+expected performance and licensing.

README.md

@@ -8,6 +8,7 @@ edition = "2018"
 crosscheck = []
 
 [dependencies]
+sacabase = { path = "../sacabase" }
 
 [build-dependencies]
 cc = "1.0.47"

crates/cdivsufsort/Cargo.toml

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 Amos Wenger All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

crates/cdivsufsort/LICENSE

@@ -0,0 +1,37 @@
+
+# cdivsufsort
+
+This crate contains Yuta Mori's C codebase `libdivsufsort`, as found on:
+
+  * <https://github.com/y-256/libdivsufsort/tree/5f60d6f026c30fb4ac296f696b3c8b0eb71bd428>
+
+...and a minimal Rust interface to it.
+
+## Changes
+
+There are no functional changes to the codebase, however:
+
+  * Parts of the code have been formatted with clang-format (LLVM style)
+  * Many of the loops (for, do..while) have been given names in comments, for
+    ease of translation.
+  * The codebase contains "cross-checking" facilities (the macros `crosscheck`,
+    `SA_dump`, etc.) so its behavior can be compared with the Rust port.
+
+Cross-checking is only built when the `crosscheck` feature is enabled. It is
+not intended for general use, only for debugging the `divsufsort` crate.
+
+## Further reading
+
+The divsufsort algorithm is based on "",
+
+## Authors
+
+The original code was written by Yuta Mori, and its essence is not changed
+here.
+
+## License
+
+`cdivsufsort` is released under the MIT license, same as the original.
+
+See the `LICENSE` and `c-sources/LICENSE` files for details.
+

crates/cdivsufsort/README.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2003 Yuta Mori All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

crates/cdivsufsort/c-sources/LICENSE

@@ -1,4 +1,30 @@
 extern "C" {
-    pub fn divsufsort(T: *const u8, SA: *mut i32, n: i32) -> i32;
+    fn divsufsort(T: *const u8, SA: *mut i32, n: i32) -> i32;
     pub fn dss_flush();
 }
+
+/// Sort suffixes of `text` and store their lexographic order
+/// in the given suffix array `sa`.
+/// Will panic if `sa.len()` != `text.len()`
+pub fn sort_in_place(text: &[u8], sa: &mut [i32]) {
+    assert_eq!(
+        text.len(),
+        sa.len(),
+        "text and suffix array should have same len"
+    );
+    assert!(
+        text.len() < i32::max_value() as usize,
+        "text too large, should not exceed {} bytes",
+        i32::max_value() - 1
+    );
+
+    let ret = unsafe { divsufsort(text.as_ptr(), sa.as_mut_ptr(), text.len() as i32) };
+    assert_eq!(0, ret);
+}
+
+//// Sort suffixes
+pub fn sort<'a>(text: &'a [u8]) -> sacabase::SuffixArray<i32> {
+    let mut sa = vec![0; text.len()];
+    sort_in_place(text, &mut sa);
+    sacabase::SuffixArray::new(text, sa)
+}

crates/cdivsufsort/src/lib.rs

@@ -0,0 +1,4 @@
+
+# dc3
+
+An incomplete, exploratory implementation of DC-3.

crates/dc3/README.md

@@ -9,3 +9,4 @@ crosscheck = ["once_cell"]
 
 [dependencies]
 once_cell = { version = "1.2.0", optional = true }
+sacabase = { path = "../sacabase" }

crates/divsufsort/Cargo.toml

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 Amos Wenger All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

crates/divsufsort/LICENSE

@@ -0,0 +1,33 @@
+
+# divsufsort
+
+This crate contains a Rust handmade port of Yuta Mori's `libdivsufsort`, as found on:
+
+  * <https://github.com/y-256/libdivsufsort/tree/5f60d6f026c30fb4ac296f696b3c8b0eb71bd428>
+
+## Changes
+
+The main changes from the C codebase are as follows.
+
+Instead of passing pointers to T (the original text) and SA (the suffix array),
+slices and indices are passed instead. This sometimes involves adding more parameters
+to functions (like `tr_heapsort`).
+
+Some macros (for stacks, used in `sssort` and `trsort`) have been replaced with
+proper Rust types. The `SAPtr` type is used to represent an index into `SA`.
+A/B/B* access has also been translated from C macros to Rust (inlined) functions.
+
+Cross-checking is only built when the `crosscheck` feature is enabled. It is
+not intended for general use, only for debugging the `divsufsort` crate.
+
+## Authors
+
+The original C code was written by Yuta Mori.
+
+The port was done by hand, by [Amos Wenger](https://github.com/fasterthanlime).
+
+## License
+
+`divsufsort` is released under the MIT license, same as the original.
+
+See the `LICENSE` file for details.

crates/divsufsort/README.md

@@ -13,8 +13,6 @@ pub const ALPHABET_SIZE: usize = u8::max_value() as usize + 1;
 pub const BUCKET_A_SIZE: usize = ALPHABET_SIZE;
 pub const BUCKET_B_SIZE: usize = ALPHABET_SIZE * ALPHABET_SIZE;
 
-pub const MAX_INPUT_SIZE: usize = i32::max_value() as usize;
-
 // Read-only input to suffix-sort
 pub struct Text<'a>(pub &'a [Char]);
 

crates/divsufsort/papers/dismantling-divsufsort-2017.pdf

@@ -1,18 +1,18 @@
 use crate::{common::*, crosscheck, crosscheck::*, sssort, trsort};
 
 pub fn divsufsort(T: &[Char], SA: &mut [Idx]) {
-    if T.len() != SA.len() {
-        panic!("divsufsort: T and SA arguments should have same length");
-    }
+    assert_eq!(
+        T.len(),
+        SA.len(),
+        "text and suffix array should have same len"
+    );
+    assert!(
+        T.len() < i32::max_value() as usize,
+        "text too large, should not exceed {} bytes",
+        i32::max_value() - 1
+    );
 
     let n = T.len();
-    if n >= MAX_INPUT_SIZE {
-        // This one ought to not be a panic, maybe?
-        panic!(
-            "divsufsort: input too large (max input size: {})",
-            MAX_INPUT_SIZE
-        )
-    }
 
     // short T cases
     match n {

crates/divsufsort/src/common.rs

@@ -11,8 +11,22 @@ mod divsufsort;
 mod sssort;
 mod trsort;
 
-pub use crate::divsufsort::divsufsort;
-pub use common::Idx;
+use common::Idx;
+use sacabase::SuffixArray;
+
+/// Sort suffixes of `text` and store their lexographic order
+/// in the given suffix array `sa`.
+/// Will panic if `sa.len()` != `text.len()`
+pub fn sort_in_place(text: &[u8], sa: &mut [Idx]) {
+    divsufsort::divsufsort(text, sa);
+}
+
+//// Sort suffixes
+pub fn sort<'a>(text: &'a [u8]) -> sacabase::SuffixArray<Idx> {
+    let mut sa = vec![0; text.len()];
+    sort_in_place(text, &mut sa);
+    sacabase::SuffixArray::new(text, sa)
+}
 
 #[cfg(test)]
 mod tests {
@@ -30,8 +44,6 @@ mod tests {
     where
         T: AsRef<[u8]>,
     {
-        let s = s.as_ref();
-        let mut SA = vec![0; s.len()];
-        super::divsufsort(s, &mut SA[..]);
+        super::sort(s.as_ref());
     }
 }

crates/divsufsort/src/divsufsort.rs

@@ -13,4 +13,4 @@ cdivsufsort = { path = "../cdivsufsort" }
 suffix_array = "0.4.0"
 better-panic = "0.2.0"
 size_format = "1.0.2"
-wavelet-matrix = { path = "./wavelet-matrix-rs" }
+cli-table = "0.2.0"