Adding a New Language Implementation to The Algorithms Repository

Useful answer

To add a new algorithm implementation in a language that is not yet supported, place the source file under src///. and create a test file that loads the shared test vectors. The CI will then run the language‑specific test suite on every pull request, verifying correctness against the same inputs used for all other languages.

Mechanism explained with a worked example

We will add a factorial function in Rust (rs) under the math category.

1. Fork and clone the repository

# Replace  with your GitHub username
git clone https://github.com//TheAlgorithms.git
cd TheAlgorithms

You need write access to your fork; pushing to the upstream repository requires a pull‑request review.

2. Create the directory structure

The repository follows src///. For Rust factorial:

mkdir -p src/rust/math

3. Write the implementation

Create src/rust/math/factorial.rs with an idiomatic Rust function:

/// Computes n! using an iterative approach.
/// Returns None if n is too large for a u64.
pub fn factorial(n: u64) -> Option {
    let mut result = 1u64;
    for i in 2..=n {
        result = result.checked_mul(i)?;
    }
    Some(result)
}

4. Add a test file that uses the shared test vectors

The Algorithms provides a JSON file testdata/factorial.json containing input‑output pairs. A Rust test can read this file and verify each case.

use std::fs;
use serde_json::Value;

#[test]
fn test_factorial_from_vectors() {
    let data = fs::read_to_string("../testdata/factorial.json").expect("cannot read test data");
    let vectors: Value = serde_json::from_str(&data).expect("invalid JSON");
    if let Value::Array(cases) = vectors["test_cases"] {
        for case in cases {
            let n = case["input"].as_u64().expect("input must be u64");
            let expected = case["output"].as_u64().expect("output must be u64");
            assert_eq!(super::factorial(n), Some(expected), "failed for n={}", n);
        }
    }
}

Place this test in src/rust/math/factorial_test.rs. The test uses the serde_json crate; add it to Cargo.toml under [dev-dependencies] if not already present.

5. Run the language‑specific test suite locally

cargo test --package rust_math_factorial

You should see all tests pass. If you encounter a missing dependency, install it via cargo add.

6. Commit and open a pull request

git add src/rust/math/factorial.rs src/rust/math/factorial_test.rs Cargo.toml
 git commit -m "Add Rust factorial implementation"
 git push origin HEAD:add-rust-factorial

Open the PR against the upstream TheAlgorithms/TheAlgorithms repository. The CI will automatically matrix‑build the Rust test suite alongside all other languages.

Limits and common mistakes

Limits of the shared test‑vector approach

• Language‑specific behaviours: The JSON vectors cannot capture nuances such as integer overflow rules, floating‑point rounding, or memory model differences. An implementation may pass the shared tests yet fail on edge cases unique to the language.
• Test coverage variance: Mature language tracks (Python, Java, C++) usually have extensive edge‑case vectors; newer language ports may rely on a smaller subset, increasing the chance of missed bugs.
• No formal API specification: Function signatures follow language idioms (e.g., fn factorial(n: u64) -> Option in Rust vs. def factorial(n: int) -> int: in Python). Consistency across languages is not enforced.

Common mistakes to avoid

1. Placing files in the wrong directory: The CI expects src///. Misplaced sources cause the build to skip the test suite.
2. Omitting the test file: Without a test that loads the shared vectors, the PR will still be accepted but the implementation will not be verified.
3. Using language‑specific test frameworks incorrectly: Each language expects its native test runner (e.g., cargo test for Rust, pytest for Python). Running the wrong command yields false passes.
4. Exceeding CI minute limits: Large PRs that touch many languages can trigger the full matrix and consume GitHub Actions minutes quickly. If you are only adding one language, you can ask maintainers to run a reduced matrix, but do not rely on bypassing the full check.
5. Assuming the implementation is production‑ready: The repository favours readability over performance. Do not reuse these snippets in latency‑critical systems without profiling.

Practical way to check the result

After your PR is merged, verify correctness by:

1. Checking the Actions tab for the workflow run; ensure the job for your language shows all tests passed.
2. Locating the artifact test-results-.txt (if uploaded) and confirming no failures.
3. Running cargo test locally on the updated main branch to ensure no regression was introduced.

If any of these steps show a failure, revisit the implementation or the test vector usage before considering the contribution complete.