fkarg / confertus

Implementation of succinct bit vectors for lecture

confertus

Implementation of succinct bit vectors for lecture 'advanced datastructures' at KIT. Find code documentation here.

Usage

General usage is confertus [bv|bp] input_file output_file (if you were to install it via cargo install --path .).

• bv and bp are two different algorithms/datastructures used/tested, where bv is short for bitvector, and bp for balanced parantheses.
• input_file is a file containing a number of line-by-line commands.
  • For bv, the first line specifies a number n of elements to push, and the following n lines (being 1 or 0) the bit to insert.
  • Example input files can be found at the lecture page.
• output_file may or may not exist beforehand, but will be overwritten if it does.

Commands

Available commands, depending on selected algorithm:

Dynamic Bitvector: algo bv

• insert i [0|1] insert a 0 or 1 at the i-th position of the bit vector
• delete i delete the i-th bit
• flip i flip the i-th bit
• rank [0|1] i write rank0 or rank1 up to position i to the output file
• select [0|1] i write select0 or select1 for the i-th occurrence to the output file

Dynamic Tree datastructure (via Balanced Parentheses): algo bp

• deletenode v delete node v
• insertchild v i k TODO: check lecture 05
• child v i write i-th child of v to output file
• subtre size v write subtree size of v (including v) to output file
• parent v write parent of v to output file

(more information about supported operations can also be found in the documentation, specifically on traits and the specific implementations for bv and bp)

Install Rust and Execute

Install rustup via your distributions package manager, or, according to the official rust website via:

$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
$ # Ensure that ~/.local/bin is in your PATH.
$ # now we need to set the default toolchain
$ rustup default stable

$ # Or, in case of a previous rust install, update with:
$ rustup update

$ # Build and open documentation locally
$ cargo doc --open

$ # Build and run (debug, provides additional information on execution)
$ cargo run [bp|bv] input_file output_file

$ # Run tests
$ cargo test

$ # Build and run (optimized)
$ RUSTFLAGS="-C target-cpu=native" cargo run --release [bp|bv] input_file output_file

Dependencies

• either: Provides the Either-datatype. Saves about 10min of implementing it manually.

Development-Dependencies

These are dependencies required to execute tests, not for running the binary itself.

• pretty_assertions: improved visualization of differences in failed assertions, useful for debugging
• quickcheck: rust-reimplementation of popular eponymous haskell-based, strongly heuristic property-based fuzzing testing library
• quickcheck_macros: additional macros for quickcheck.
• test-case: macros for generating parametricized tests (unused?)
• rand: access to a random number generator for tests. It has been suggested for integration in std, but that hasn't happened yet.

I recommend running cargo watch or [bacon] on a terminal nearby during active development. Both run cargo check on filechange.

Remarks on usage

This project is an inefficient, incomplete and unsound implementation of a dynamic bit vector as part of a university lecture requirement. Again, it is not complete and contains numerous bugs. I recommend using established implementations such as bitvec and succinct.