algorist

Helper tools, algorithms and data structures for competitive programming.

Algorist is both a CLI tool for managing programming contest projects AND a collection of useful algorithms and data structures to use in those projects.

Installation

The crate provides cargo sub-command algorist, which can be installed using:

cargo install algorist

Once installed, you can use it as cargo algorist.

Usage

When contesting, you will normally have a set of problems to solve, each of which is identified by a problem ID (usually a letter from a to h). Each problem will have its own source file, and while that file can use any number of additional modules, it is expected that the final submission is a single file that contains all the necessary code to solve the problem.

The algorist CLI tool provides a way to create a new contest project, which is a normal Rust project, use additional modules with common algorithms and data structures, and then bundle each problem into a single output file that can be submitted to the contest system (only modules actually used will be bundled, not all available data structures and algorithms).

Create a new contest project

To create a new contest project (contest_id will be normally contest number):

cargo algorist create <contest_id>

# examples:
cargo algorist create 4545
cargo algorist create contests/4545 # sub-folders are also supported

This will create Rust project with all the necessary problem files and algorithm modules copied into it. Problem files will be created in src/bin directory, and the library with algorithms and data structures will be created in src/algorist/ module.

# run problem A (`src/bin/a.rs`)
# it expects input from stdin
cargo run --bin a

# it is a normal Rust project, so you can use all the usual commands
cargo build
cargo test

If you don't want to have initial problem files, you can create a new contest project with --empty flag:

cargo algorist create <contest_id> --empty

Later on, you can always add a problem file into src/bin directory, using:

cargo algorist add <problem_id>

# examples:
cargo algorist add a        # `.rs` is not required
cargo algorist add a.rs     # same as above

Work on a problem

All problems are located in src/bin/<problem_id>.rs files. The file will contain entry point main function, which is expected to read input from standard input and write output to standard output. The starter code for the problem file will look something like this:

use {
    algorist::io::{Scanner, wln},
    std::io::{self, Write},
};

fn main() {
    let mut scan = Scanner::new(io::stdin().lock());
    let mut w = io::BufWriter::new(io::stdout().lock());

    scan.test_cases(&mut |scan| {
        let n = scan.u();
        let vals: Vec<i32> = scan.vec(n);

        let ans = vals.len();
        wln!(w, "{}", ans);
    });
}

See the documentation on io module (and other provided algorithms and data structures) for more details on the default code provided in problem files.

To test a problem, you can use (again, it is a normal Rust project, so you can use all the usual machinery):

cargo test --bin <problem_id>

# alias pbpaste=’xsel — clipboard — output’ on Linux
pbpaste | cargo run --bin <problem_id>   # gets input from clipboard
cargo run --bin <problem_id> < input.txt # gets input from file

Once you are happy with your solution, you can submit it to the contest system (by bundling into a single file).

Bundle the project

Contest systems expect a single output file, where all used modules are packed within the scope of that file.

To bundle the problem which you are working on, and which might include various additional modules (at the very least io module is included), in a single output file, you can use:

cargo algorist bundle <problem_id>

# examples:
cargo algorist bundle a # `.rs` is not required
cargo algorist bundle a.rs

This will create a single output file in bundled/<problem_id>.rs file, which can be submitted to the contest system.

Note that while the library provides a lot of algorithms and data structures, only those actually used in the problem will be included in the output file, so the final file will be as concise and readable as possible (it is NOT just a dump of everything).

Included algorithms and data structures

The Algorist is also a library of algorithms and data structures, which will be copied into your contest project, and can be used in your problem files.

See algorist module documentation for a complete list of available algorithms and data structures, as well as their usage examples.

License

MIT