feat: add Vernam cipher implementation

[AliAlimohammadi]

Description

This PR adds an implementation of the Vernam cipher (also known as a simple substitution cipher using modular arithmetic) to the ciphers module. The Vernam cipher is a symmetric stream cipher that combines plaintext with a key using modular addition and subtraction.

Implementation Details

The implementation provides two public functions:

1. vernam_encrypt(plaintext: &str, key: &str) -> String

   • Encrypts plaintext using the formula: C = (P + K) mod 26
   • Converts input to uppercase automatically
   • Filters out non-alphabetic characters
   • Cycles the key if it's shorter than the plaintext

2. vernam_decrypt(ciphertext: &str, key: &str) -> String

   • Decrypts ciphertext using the formula: P = (C - K) mod 26
   • Converts input to uppercase automatically
   • Filters out non-alphabetic characters
   • Cycles the key if it's shorter than the ciphertext

Algorithm Details

• Character Set: Works with uppercase letters A-Z only
• Key Cycling: If the key is shorter than the text, it repeats cyclically
• Modular Arithmetic: Uses mod 26 to wrap around the alphabet
• Input Handling: Automatically converts to uppercase and filters non-alphabetic characters
• Time Complexity: $O(n)$ where n is the length of the input text
• Space Complexity: $O(n)$ for storing the result

Security Note

This implementation is for educational purposes. In practice, the Vernam cipher is only secure when:

• The key is truly random
• The key is at least as long as the message
• The key is never reused (one-time pad principle)

Changes Made

• ✅ Added src/ciphers/vernam.rs with complete implementation
• ✅ Will update src/ciphers/mod.rs to include and export the new module
• ✅ Implemented comprehensive unit tests covering:
  • Basic encryption and decryption
  • Round-trip encryption/decryption verification
  • Long text handling
  • Case insensitivity (lowercase, uppercase, mixed)
  • Single character operations
  • Key wrapping/cycling
  • Alphabet boundary conditions (wrapping at Z/A)
  • Non-alphabetic character filtering
  • Edge cases (empty inputs, invalid keys)
  • Panic behavior for invalid inputs
• ✅ Added detailed documentation with examples for all public functions
• ✅ Included doctests demonstrating usage

Type of Change

• New cipher implementation
• Documentation (docstrings and examples)
• Tests

Testing

All tests pass successfully:

cargo test vernam
cargo test --doc
cargo fmt --check
cargo clippy -- -D warnings

Test Coverage

• ✅ Basic encryption: "HELLO" + "KEY" = "RIJVS"
• ✅ Basic decryption: "RIJVS" + "KEY" = "HELLO"
• ✅ Round-trip verification
• ✅ Long text handling
• ✅ Case insensitivity
• ✅ Single character operations
• ✅ Key cycling when key is shorter than text
• ✅ Alphabet boundary wrapping
• ✅ Non-alphabetic character filtering
• ✅ Empty input handling
• ✅ Invalid input panics (empty key, key with no letters)
• ✅ Doctests for public API

Examples

use the_algorithms_rust::ciphers::{vernam_encrypt, vernam_decrypt};

// Basic usage
let ciphertext = vernam_encrypt("HELLO", "KEY");
assert_eq!(ciphertext, "RIJVS");

let plaintext = vernam_decrypt("RIJVS", "KEY");
assert_eq!(plaintext, "HELLO");

// Handles lowercase automatically
let ciphertext = vernam_encrypt("hello", "key");
assert_eq!(ciphertext, "RIJVS");

// Key cycling for short keys
let ciphertext = vernam_encrypt("HELLOWORLD", "KEY");
let plaintext = vernam_decrypt(&ciphertext, "KEY");
assert_eq!(plaintext, "HELLOWORLD");

// Filters non-alphabetic characters
let ciphertext = vernam_encrypt("HELLO 123 WORLD!", "KEY");
// Same as: vernam_encrypt("HELLOWORLD", "KEY")

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my implementation is correct
• New and existing unit tests pass locally with my changes
• I have checked my code with cargo fmt
• I have checked my code with cargo clippy
• Any dependent changes have been merged and published

[AliAlimohammadi]

@siriak, this is ready to be merged.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 99.17355% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 95.80%. Comparing base (35a5743) to head (d8368dd).

Files with missing lines	Patch %	Lines
src/ciphers/vernam.rs	99.17%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #984      +/-   ##
==========================================
+ Coverage   95.77%   95.80%   +0.02%     
==========================================
  Files         354      355       +1     
  Lines       23407    23528     +121     
==========================================
+ Hits        22419    22540     +121     
  Misses        988      988              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.