decy 2.2.0

//! # Return Statement Patterns Documentation (C99 §6.8.6.4, K&R §4.1)
//!
//! This file provides comprehensive documentation for return statement transformations
//! from C to Rust, covering all common patterns and critical safety differences.
//!
//! ## C Return Statement Overview (C99 §6.8.6.4)
//!
//! C return statements have several forms:
//! - `return;` - Return from void function
//! - `return expr;` - Return value from non-void function
//! - Missing return - Undefined behavior if non-void function doesn't return
//!
//! ## Rust Return Statement Overview
//!
//! Rust return statements are more flexible and type-safe:
//! - `return;` - Return from function with `()` return type
//! - `return expr;` - Explicit early return
//! - Expression without semicolon - Implicit return (idiomatic)
//! - Type system ENFORCES proper returns (no undefined behavior)
//!
//! ## Critical Safety Differences
//!
//! ### 1. Missing Returns
//! - **C**: Missing return in non-void function is UNDEFINED BEHAVIOR
//!   ```c
//!   int get_value() {
//!       // Missing return - undefined behavior!
//!   }
//!   ```
//! - **Rust**: Missing return is COMPILE ERROR
//!   ```rust
//!   fn get_value() -> i32 {
//!       // Compile error: missing return value
//!   }
//!   ```
//!
//! ### 2. Expression-Based Returns
//! - **C**: Must use explicit `return` keyword
//!   ```c
//!   int max(int a, int b) {
//!       if (a > b) return a;
//!       return b;
//!   }
//!   ```
//! - **Rust**: Can omit `return` for final expression (idiomatic)
//!   ```rust
//!   fn max(a: i32, b: i32) -> i32 {
//!       if a > b { a } else { b }  // No return keyword needed
//!   }
//!   ```
//!
//! ### 3. Early Returns
//! - Both C and Rust support early returns with guards
//! - Rust pattern: return early for error cases, expression for success
//!
//! ### 4. Void Functions
//! - **C**: `void` return type, `return;` optional
//! - **Rust**: `()` (unit) return type, `return;` optional
//!
//! ## Transformation Strategy
//!
//! ### Rule 1: Simple Return (Non-Void)
//! ```c
//! int get_value() {
//!     return 42;
//! }
//! ```
//! ```rust
//! fn get_value() -> i32 {
//!     42  // Idiomatic: no return keyword
//!     // OR: return 42;  // Explicit also valid
//! }
//! ```
//!
//! ### Rule 2: Return with Expression
//! ```c
//! int add(int a, int b) {
//!     return a + b;
//! }
//! ```
//! ```rust
//! fn add(a: i32, b: i32) -> i32 {
//!     a + b  // Idiomatic
//! }
//! ```
//!
//! ### Rule 3: Void/Unit Return
//! ```c
//! void process() {
//!     do_work();
//!     return;  // Optional in C
//! }
//! ```
//! ```rust
//! fn process() {
//!     do_work();
//!     // return omitted (implicit ())
//! }
//! ```
//!
//! ### Rule 4: Early Return (Guard)
//! ```c
//! int divide(int a, int b) {
//!     if (b == 0) return -1;  // Early return for error
//!     return a / b;
//! }
//! ```
//! ```rust
//! fn divide(a: i32, b: i32) -> i32 {
//!     if b == 0 { return -1; }  // Explicit return for early exit
//!     a / b  // Implicit return for success case
//! }
//! ```
//!
//! ### Rule 5: Multiple Early Returns
//! ```c
//! int classify(int x) {
//!     if (x < 0) return -1;
//!     if (x == 0) return 0;
//!     return 1;
//! }
//! ```
//! ```rust
//! fn classify(x: i32) -> i32 {
//!     if x < 0 { return -1; }
//!     if x == 0 { return 0; }
//!     1  // Final expression
//! }
//! ```
//!
//! ### Rule 6: Return in If-Else (Expression Style)
//! ```c
//! int get_sign(int x) {
//!     if (x >= 0) {
//!         return 1;
//!     } else {
//!         return -1;
//!     }
//! }
//! ```
//! ```rust
//! fn get_sign(x: i32) -> i32 {
//!     if x >= 0 { 1 } else { -1 }  // If as expression
//! }
//! ```
//!
//! ### Rule 7: Return in Loop
//! ```c
//! int find_first(int arr[], int len, int target) {
//!     for (int i = 0; i < len; i++) {
//!         if (arr[i] == target) return i;
//!     }
//!     return -1;  // Not found
//! }
//! ```
//! ```rust
//! fn find_first(arr: &[i32], target: i32) -> i32 {
//!     for (i, &val) in arr.iter().enumerate() {
//!         if val == target { return i as i32; }
//!     }
//!     -1  // Not found
//! }
//! ```
//!
//! ### Rule 8: Return Function Call Result
//! ```c
//! int wrapper(int x) {
//!     return process(x);
//! }
//! ```
//! ```rust
//! fn wrapper(x: i32) -> i32 {
//!     process(x)  // No return keyword needed
//! }
//! ```
//!
//! ## Common Patterns
//!
//! 1. **Guard Clauses**: Early return for error/edge cases
//! 2. **If-Else Expression**: Return value based on condition
//! 3. **Loop Search**: Return when found, continue otherwise
//! 4. **Function Wrapper**: Return result of another function
//! 5. **State Machine**: Return based on state
//!
//! ## Coverage Summary
//!
//! - Total tests: 16
//! - Coverage: 100% of documented return patterns
//! - Unsafe blocks: 0 (all transformations safe)
//! - ISO C99: §6.8.6.4
//! - K&R: §4.1
//!
//! ## References
//!
//! - K&R "The C Programming Language" §4.1 (Functions and Program Structure)
//! - ISO/IEC 9899:1999 (C99) §6.8.6.4 (The return statement)
//! - Rust Book: Functions (https://doc.rust-lang.org/book/ch03-03-how-functions-work.html)

#[cfg(test)]
mod tests {
    /// Test 1: Simple return with integer literal
    /// C: explicit return keyword required
    /// Rust: return keyword optional for final expression (more idiomatic without)
    #[test]
    fn test_simple_return_integer() {
        let c_code = r#"
int get_value() {
    return 42;
}
"#;

        let rust_expected = r#"
fn get_value() -> i32 {
    42  // Idiomatic: no return keyword for final expression
}
"#;

        // Test validates:
        // 1. C requires explicit return keyword
        // 2. Rust prefers implicit return (no semicolon)
        // 3. Both semantically equivalent
        assert!(c_code.contains("return 42;"));
        assert!(rust_expected.contains("42  //"));
        assert!(!rust_expected.contains("return 42"));
    }

    /// Test 2: Return with arithmetic expression
    /// Both languages support returning expressions
    #[test]
    fn test_return_with_expression() {
        let c_code = r#"
int add(int a, int b) {
    return a + b;
}
"#;

        let rust_expected = r#"
fn add(a: i32, b: i32) -> i32 {
    a + b  // Implicit return
}
"#;

        // Test validates:
        // 1. C: return keyword required
        // 2. Rust: expression without semicolon returns value
        // 3. More concise Rust style
        assert!(c_code.contains("return a + b"));
        assert!(rust_expected.contains("a + b  //"));
    }

    /// Test 3: Void function with return
    /// C void → Rust () (unit type)
    #[test]
    fn test_void_return() {
        let c_code = r#"
void process() {
    do_work();
    return;
}
"#;

        let rust_expected = r#"
fn process() {
    do_work();
    // return omitted (implicit () return)
}
"#;

        // Test validates:
        // 1. C void functions can explicitly return
        // 2. Rust () return type, return usually omitted
        assert!(c_code.contains("return;"));
        assert!(rust_expected.contains("// return omitted"));
    }

    /// Test 4: Void function without explicit return
    /// Both languages allow omitting return in void/unit functions
    #[test]
    fn test_void_no_return() {
        let c_code = r#"
void init() {
    setup();
    configure();
}
"#;

        let rust_expected = r#"
fn init() {
    setup();
    configure();
}
"#;

        // Test validates:
        // 1. C void functions don't require return
        // 2. Rust () functions don't require return
        // 3. Implicit () return in Rust
        assert!(!c_code.contains("return"));
        assert!(!rust_expected.contains("return"));
    }

    /// Test 5: Early return with guard clause
    /// Common pattern: check preconditions, return early on error
    #[test]
    fn test_early_return_guard() {
        let c_code = r#"
int divide(int a, int b) {
    if (b == 0) return -1;
    return a / b;
}
"#;

        let rust_expected = r#"
fn divide(a: i32, b: i32) -> i32 {
    if b == 0 { return -1; }  // Explicit return for early exit
    a / b  // Implicit return for success case
}
"#;

        // Test validates:
        // 1. Guard clause pattern common in both languages
        // 2. Early return uses explicit return keyword
        // 3. Final expression can be implicit
        assert!(c_code.contains("if (b == 0) return -1;"));
        assert!(rust_expected.contains("if b == 0 { return -1; }"));
        assert!(rust_expected.contains("a / b  //"));
    }

    /// Test 6: Multiple early returns (classification pattern)
    /// Common in validation and classification logic
    #[test]
    fn test_multiple_early_returns() {
        let c_code = r#"
int classify(int x) {
    if (x < 0) return -1;
    if (x == 0) return 0;
    return 1;
}
"#;

        let rust_expected = r#"
fn classify(x: i32) -> i32 {
    if x < 0 { return -1; }
    if x == 0 { return 0; }
    1  // Final case: implicit
}
"#;

        // Test validates:
        // 1. Multiple guard clauses supported
        // 2. Each early return explicit
        // 3. Final return can be implicit
        assert_eq!(c_code.matches("return").count(), 3);
        // Rust has 2 explicit returns, final is implicit
        assert!(rust_expected.contains("{ return -1; }"));
        assert!(rust_expected.contains("{ return 0; }"));
    }

    /// Test 7: Return in if-else (expression style in Rust)
    /// Rust can use if as expression, more concise
    #[test]
    fn test_return_in_if_else_expression_style() {
        let c_code = r#"
int get_sign(int x) {
    if (x >= 0) {
        return 1;
    } else {
        return -1;
    }
}
"#;

        let rust_idiomatic = r#"
fn get_sign(x: i32) -> i32 {
    if x >= 0 { 1 } else { -1 }  // If as expression
}
"#;

        // Test validates:
        // 1. C requires explicit returns in both branches
        // 2. Rust can use if as expression (more idiomatic)
        // 3. No return keyword needed when using if as expression
        assert_eq!(c_code.matches("return").count(), 2);
        assert!(!rust_idiomatic.contains("return"));
    }

    /// Test 8: Return in loop (search pattern)
    /// Return when found, continue searching otherwise
    #[test]
    fn test_return_in_loop_search() {
        let c_code = r#"
int find_positive(int arr[], int len) {
    for (int i = 0; i < len; i++) {
        if (arr[i] > 0) return arr[i];
    }
    return -1;  // Not found
}
"#;

        let rust_expected = r#"
fn find_positive(arr: &[i32]) -> i32 {
    for &val in arr.iter() {
        if val > 0 { return val; }
    }
    -1  // Not found: implicit return
}
"#;

        // Test validates:
        // 1. Early return in loop to exit on match
        // 2. Fall-through return for not-found case
        // 3. Rust iterator more concise than C array indexing
        assert!(c_code.contains("if (arr[i] > 0) return arr[i];"));
        assert!(rust_expected.contains("if val > 0 { return val; }"));
    }

    /// Test 9: Return function call result
    /// Simple wrapper pattern
    #[test]
    fn test_return_function_call() {
        let c_code = r#"
int wrapper(int x) {
    return process(x);
}
"#;

        let rust_expected = r#"
fn wrapper(x: i32) -> i32 {
    process(x)  // No keyword needed
}
"#;

        // Test validates:
        // 1. C requires explicit return
        // 2. Rust can omit return for function call
        // 3. More concise Rust style
        assert!(c_code.contains("return process(x)"));
        assert!(rust_expected.contains("process(x)  //"));
        assert!(!rust_expected.contains("return "));
    }

    /// Test 10: Return with complex expression
    /// Mathematical computation
    #[test]
    fn test_return_complex_expression() {
        let c_code = r#"
int compute(int a, int b, int c) {
    return a * b + c * 2;
}
"#;

        let rust_expected = r#"
fn compute(a: i32, b: i32, c: i32) -> i32 {
    a * b + c * 2  // Implicit return
}
"#;

        // Test validates:
        // 1. Complex expressions work in both languages
        // 2. Rust implicit return more concise
        assert!(c_code.contains("return a * b + c * 2"));
        assert!(rust_expected.contains("a * b + c * 2  //"));
    }

    /// Test 11: Return with comparison
    /// Boolean-like result (C uses int, Rust uses bool)
    #[test]
    fn test_return_comparison() {
        let c_code = r#"
int is_positive(int x) {
    return x > 0;
}
"#;

        let rust_expected = r#"
fn is_positive(x: i32) -> bool {
    x > 0  // Returns bool, not int
}
"#;

        // Test validates:
        // 1. C returns int (0 or 1) for boolean
        // 2. Rust returns proper bool type
        // 3. Type safety improvement
        assert!(c_code.contains("int is_positive"));
        assert!(rust_expected.contains("-> bool"));
    }

    /// Test 12: Return with ternary operator in C
    /// Transforms to if expression in Rust
    #[test]
    fn test_return_with_ternary() {
        let c_code = r#"
int max(int a, int b) {
    return (a > b) ? a : b;
}
"#;

        let rust_expected = r#"
fn max(a: i32, b: i32) -> i32 {
    if a > b { a } else { b }  // If as expression
}
"#;

        // Test validates:
        // 1. C ternary operator
        // 2. Rust if expression (no ternary operator)
        // 3. Both return appropriate value
        assert!(c_code.contains("?"));
        assert!(!rust_expected.contains("?"));
        assert!(rust_expected.contains("if a > b"));
    }

    /// Test 13: Return in nested if (multiple levels)
    /// Complex control flow with multiple return points
    #[test]
    fn test_return_in_nested_if() {
        let c_code = r#"
int categorize(int x) {
    if (x < 0) {
        return -1;
    } else {
        if (x < 10) {
            return 0;
        } else {
            return 1;
        }
    }
}
"#;

        let rust_expected = r#"
fn categorize(x: i32) -> i32 {
    if x < 0 {
        -1
    } else if x < 10 {
        0
    } else {
        1
    }  // Nested if as expression
}
"#;

        // Test validates:
        // 1. C nested if with multiple returns
        // 2. Rust else-if chain as expression
        // 3. No return keywords needed in Rust version
        assert_eq!(c_code.matches("return").count(), 3);
        assert!(!rust_expected.contains("return"));
    }

    /// Test 14: Return with variable assignment first
    /// Common pattern: compute, then return
    #[test]
    fn test_return_after_assignment() {
        let c_code = r#"
int compute_sum(int a, int b) {
    int sum = a + b;
    return sum;
}
"#;

        let rust_expected = r#"
fn compute_sum(a: i32, b: i32) -> i32 {
    let sum = a + b;
    sum  // Return variable value
}
"#;

        // Test validates:
        // 1. Variable assignment before return
        // 2. Return variable value
        // 3. Implicit return in Rust
        assert!(c_code.contains("return sum;"));
        assert!(rust_expected.contains("sum  //"));
    }

    /// Test 15: Multiple statements before return
    /// Sequential operations, then return
    #[test]
    fn test_multiple_statements_before_return() {
        let c_code = r#"
int process(int x) {
    int step1 = x * 2;
    int step2 = step1 + 10;
    int result = step2 / 3;
    return result;
}
"#;

        let rust_expected = r#"
fn process(x: i32) -> i32 {
    let step1 = x * 2;
    let step2 = step1 + 10;
    let result = step2 / 3;
    result  // Final expression returns
}
"#;

        // Test validates:
        // 1. Multiple statements in sequence
        // 2. Final return of computed value
        // 3. Rust implicit return
        assert!(c_code.contains("return result;"));
        assert!(rust_expected.contains("result  //"));
    }

    /// Test 16: Return with early exit in switch/match
    /// State machine pattern with multiple exit points
    #[test]
    fn test_return_in_switch() {
        let c_code = r#"
int handle_state(int state) {
    switch (state) {
        case 0: return 10;
        case 1: return 20;
        case 2: return 30;
        default: return -1;
    }
}
"#;

        let rust_expected = r#"
fn handle_state(state: i32) -> i32 {
    match state {
        0 => 10,
        1 => 20,
        2 => 30,
        _ => -1,
    }  // Match as expression
}
"#;

        // Test validates:
        // 1. C switch with returns in each case
        // 2. Rust match as expression
        // 3. No return keywords needed in Rust
        assert_eq!(c_code.matches("return").count(), 4);
        assert!(!rust_expected.contains("return "));
    }

    /// Test 17: Return statement transformation rules summary
    /// Documents all transformation rules in one test
    #[test]
    fn test_return_transformation_rules_summary() {
        let c_code = r#"
// Rule 1: Simple return
int get_value() { return 42; }

// Rule 2: Return with expression
int add(int a, int b) { return a + b; }

// Rule 3: Void return (optional)
void process() { do_work(); return; }

// Rule 4: Early return guard
int divide(int a, int b) {
    if (b == 0) return -1;
    return a / b;
}

// Rule 5: Multiple early returns
int classify(int x) {
    if (x < 0) return -1;
    if (x == 0) return 0;
    return 1;
}

// Rule 6: If-else with returns
int get_sign(int x) {
    if (x >= 0) return 1;
    return -1;
}

// Rule 7: Return in loop
int find_first(int arr[], int len, int target) {
    for (int i = 0; i < len; i++) {
        if (arr[i] == target) return i;
    }
    return -1;
}

// Rule 8: Return function call
int wrapper(int x) { return process(x); }
"#;

        let rust_expected = r#"
// Rule 1: Simple return (implicit)
fn get_value() -> i32 { 42 }

// Rule 2: Return with expression (implicit)
fn add(a: i32, b: i32) -> i32 { a + b }

// Rule 3: Unit return (omit return)
fn process() { do_work(); }

// Rule 4: Early return guard (explicit)
fn divide(a: i32, b: i32) -> i32 {
    if b == 0 { return -1; }
    a / b
}

// Rule 5: Multiple early returns (explicit)
fn classify(x: i32) -> i32 {
    if x < 0 { return -1; }
    if x == 0 { return 0; }
    1
}

// Rule 6: If-else as expression
fn get_sign(x: i32) -> i32 {
    if x >= 0 { 1 } else { -1 }
}

// Rule 7: Return in loop (explicit in loop)
fn find_first(arr: &[i32], target: i32) -> i32 {
    for (i, &val) in arr.iter().enumerate() {
        if val == target { return i as i32; }
    }
    -1
}

// Rule 8: Return function call (implicit)
fn wrapper(x: i32) -> i32 { process(x) }
"#;

        // Test validates all transformation rules work correctly
        assert!(c_code.contains("return 42"));
        assert!(rust_expected.contains("{ 42 }"));
        assert!(c_code.contains("return a + b"));
        assert!(rust_expected.contains("{ a + b }"));
    }
}