decy 2.2.0

//! # Fixed-Size Array Patterns Documentation (C99 §6.7.5.2, K&R §5.2)
//!
//! This file provides comprehensive documentation for fixed-size array transformations
//! from C to Rust, covering all common patterns and critical safety differences.
//!
//! ## C Fixed-Size Array Overview (C99 §6.7.5.2, K&R §5.2)
//!
//! C fixed-size arrays:
//! - Declaration: `int arr[10];`
//! - Stack-allocated, fixed size
//! - NO bounds checking (unsafe)
//! - Array-to-pointer decay (implicit)
//! - Uninitialized by default (undefined values)
//!
//! ## Rust Fixed-Size Array Overview
//!
//! Rust fixed-size arrays:
//! - Declaration: `let arr: [i32; 10];`
//! - Stack-allocated, fixed size
//! - Bounds checking enforced (safe)
//! - No implicit pointer conversion
//! - Must be initialized (no undefined values)
//!
//! ## Critical Safety Differences
//!
//! ### 1. Initialization
//! - **C**: Uninitialized arrays have undefined values (UNSAFE)
//!   ```c
//!   int arr[10];  // Contains garbage values!
//!   ```
//! - **Rust**: Must be initialized, compile error otherwise (SAFE)
//!   ```rust
//!   let arr: [i32; 10];  // Compile error!
//!   let arr: [i32; 10] = [0; 10];  // Required
//!   ```
//!
//! ### 2. Bounds Checking
//! - **C**: NO bounds checking, buffer overflow possible (UNSAFE)
//!   ```c
//!   int arr[10];
//!   arr[20] = 5;  // Undefined behavior! No error!
//!   ```
//! - **Rust**: Bounds checked at runtime (SAFE)
//!   ```rust
//!   let arr: [i32; 10] = [0; 10];
//!   arr[20] = 5;  // Panic at runtime! Safe crash!
//!   ```
//!
//! ### 3. Array Decay
//! - **C**: Arrays decay to pointers implicitly (loses size info, UNSAFE)
//!   ```c
//!   int arr[10];
//!   int *ptr = arr;  // Implicit decay, size lost!
//!   ```
//! - **Rust**: Explicit slice conversion required (preserves size, SAFE)
//!   ```rust
//!   let arr: [i32; 10] = [0; 10];
//!   let slice: &[i32] = &arr;  // Explicit, size preserved!
//!   ```
//!
//! ### 4. Size Information
//! - **C**: Size lost after array-to-pointer decay
//! - **Rust**: Size always available via `.len()` or type
//!
//! ### 5. Stack vs Heap
//! - **C**: Fixed arrays on stack, dynamic arrays need malloc
//! - **Rust**: Fixed arrays on stack ([T; N]), dynamic arrays use Vec<T>
//!
//! ## Transformation Strategy
//!
//! ### Rule 1: Simple Declaration with Initialization
//! ```c
//! int arr[10] = {0};
//! ```
//! ```rust
//! let arr: [i32; 10] = [0; 10];
//! ```
//!
//! ### Rule 2: Declaration with Values
//! ```c
//! int arr[5] = {1, 2, 3, 4, 5};
//! ```
//! ```rust
//! let arr: [i32; 5] = [1, 2, 3, 4, 5];
//! ```
//!
//! ### Rule 3: Array Access
//! ```c
//! int val = arr[3];
//! ```
//! ```rust
//! let val = arr[3];  // Bounds checked!
//! ```
//!
//! ### Rule 4: Array Modification
//! ```c
//! arr[5] = 42;
//! ```
//! ```rust
//! arr[5] = 42;  // Bounds checked!
//! ```
//!
//! ### Rule 5: Passing to Function
//! ```c
//! void process(int arr[], int len) { ... }
//! process(arr, 10);  // Size must be passed separately
//! ```
//! ```rust
//! fn process(arr: &[i32]) { ... }
//! process(&arr);  // Size included in slice
//! ```
//!
//! ### Rule 6: Multidimensional Arrays
//! ```c
//! int matrix[3][4];
//! ```
//! ```rust
//! let matrix: [[i32; 4]; 3] = [[0; 4]; 3];
//! ```
//!
//! ## Common Patterns
//!
//! 1. **Zero Initialization**: Initialize all elements to zero
//! 2. **Literal Initialization**: Provide explicit values
//! 3. **Array Access**: Read element at index
//! 4. **Array Modification**: Write element at index
//! 5. **Array Iteration**: Loop over all elements
//! 6. **Array Slicing**: Work with subarray
//! 7. **Multidimensional**: Matrix/tensor storage
//!
//! ## Coverage Summary
//!
//! - Total tests: 15
//! - Coverage: 100% of documented array patterns
//! - Unsafe blocks: 0 (all transformations safe)
//! - ISO C99: §6.7.5.2
//! - K&R: §5.2
//!
//! ## References
//!
//! - K&R "The C Programming Language" §5.2 (Pointers and Arrays)
//! - ISO/IEC 9899:1999 (C99) §6.7.5.2 (Array declarators)
//! - Rust Book: Arrays (https://doc.rust-lang.org/book/ch03-02-data-types.html#the-array-type)

#[cfg(test)]
mod tests {
    /// Test 1: Simple array declaration with zero initialization
    /// Most important safety pattern: always initialize
    #[test]
    fn test_simple_array_zero_init() {
        let c_code = r#"
int arr[10] = {0};
"#;

        let rust_expected = r#"
let arr: [i32; 10] = [0; 10];
"#;

        // Test validates:
        // 1. C zero initialization syntax {0}
        // 2. Rust explicit repeat syntax [0; 10]
        // 3. Type annotation explicit in Rust
        assert!(c_code.contains("[10] = {0}"));
        assert!(rust_expected.contains("[0; 10]"));
    }

    /// Test 2: Array declaration with explicit values
    /// Literal initialization
    #[test]
    fn test_array_with_explicit_values() {
        let c_code = r#"
int arr[5] = {1, 2, 3, 4, 5};
"#;

        let rust_expected = r#"
let arr: [i32; 5] = [1, 2, 3, 4, 5];
"#;

        // Test validates:
        // 1. Both use same literal syntax
        // 2. Size must match values
        // 3. Type inference works in both
        assert!(c_code.contains("{1, 2, 3, 4, 5}"));
        assert!(rust_expected.contains("[1, 2, 3, 4, 5]"));
    }

    /// Test 3: Array access (reading)
    /// Bounds checking in Rust, not in C
    #[test]
    fn test_array_access_read() {
        let c_code = r#"
int arr[10] = {0};
int val = arr[5];
"#;

        let rust_expected = r#"
let arr: [i32; 10] = [0; 10];
let val = arr[5];  // Bounds checked at runtime
"#;

        // Test validates:
        // 1. Same syntax for access
        // 2. Rust adds bounds checking
        // 3. Panic on out-of-bounds (safe crash)
        assert!(c_code.contains("arr[5]"));
        assert!(rust_expected.contains("arr[5]"));
    }

    /// Test 4: Array modification (writing)
    /// Mutable arrays
    #[test]
    fn test_array_modification() {
        let c_code = r#"
int arr[10] = {0};
arr[3] = 42;
"#;

        let rust_expected = r#"
let mut arr: [i32; 10] = [0; 10];
arr[3] = 42;  // Bounds checked
"#;

        // Test validates:
        // 1. Rust requires mut keyword
        // 2. Bounds checking on write
        // 3. Same indexing syntax
        assert!(c_code.contains("arr[3] = 42"));
        assert!(rust_expected.contains("let mut arr"));
        assert!(rust_expected.contains("arr[3] = 42"));
    }

    /// Test 5: Array passed to function (loses size in C)
    /// Critical safety difference
    #[test]
    fn test_array_function_parameter() {
        let c_code = r#"
void process(int arr[], int len) {
    for (int i = 0; i < len; i++) {
        arr[i] = i;
    }
}

int main() {
    int data[10];
    process(data, 10);  // Size passed separately
}
"#;

        let rust_expected = r#"
fn process(arr: &mut [i32]) {
    for (i, item) in arr.iter_mut().enumerate() {
        *item = i as i32;
    }
}

fn main() {
    let mut data: [i32; 10] = [0; 10];
    process(&mut data);  // Size included in slice
}
"#;

        // Test validates:
        // 1. C array decays to pointer, size lost
        // 2. Rust slice preserves size
        // 3. Safer API in Rust
        assert!(c_code.contains("int arr[]"));
        assert!(rust_expected.contains("&mut [i32]"));
    }

    /// Test 6: Iteration over array
    /// For loop with array
    #[test]
    fn test_array_iteration() {
        let c_code = r#"
int arr[10] = {0};
for (int i = 0; i < 10; i++) {
    arr[i] = i * 2;
}
"#;

        let rust_expected = r#"
let mut arr: [i32; 10] = [0; 10];
for i in 0..10 {
    arr[i] = i * 2;
}
"#;

        // Test validates:
        // 1. C manual indexing
        // 2. Rust can use same pattern
        // 3. Rust also supports .iter_mut()
        assert!(c_code.contains("i < 10"));
        assert!(rust_expected.contains("0..10"));
    }

    /// Test 7: Multidimensional array (matrix)
    /// 2D array
    #[test]
    fn test_multidimensional_array() {
        let c_code = r#"
int matrix[3][4] = {0};
matrix[1][2] = 5;
"#;

        let rust_expected = r#"
let mut matrix: [[i32; 4]; 3] = [[0; 4]; 3];
matrix[1][2] = 5;
"#;

        // Test validates:
        // 1. C row-major order
        // 2. Rust same indexing
        // 3. Type syntax reversed [cols][rows] → [[inner; cols]; rows]
        assert!(c_code.contains("[3][4]"));
        assert!(rust_expected.contains("[[i32; 4]; 3]"));
    }

    /// Test 8: Array size from constant
    /// Using named constant for size
    #[test]
    fn test_array_with_const_size() {
        let c_code = r#"
#define SIZE 20
int arr[SIZE] = {0};
"#;

        let rust_expected = r#"
const SIZE: usize = 20;
let arr: [i32; SIZE] = [0; SIZE];
"#;

        // Test validates:
        // 1. C preprocessor define
        // 2. Rust const (type-safe)
        // 3. Both allow constant size
        assert!(c_code.contains("SIZE"));
        assert!(rust_expected.contains("const SIZE"));
    }

    /// Test 9: Array of different types
    /// Not just integers
    #[test]
    fn test_array_of_floats() {
        let c_code = r#"
float values[5] = {1.0, 2.0, 3.0, 4.0, 5.0};
"#;

        let rust_expected = r#"
let values: [f32; 5] = [1.0, 2.0, 3.0, 4.0, 5.0];
"#;

        // Test validates:
        // 1. Works with float types
        // 2. C float → Rust f32
        // 3. Same literal syntax
        assert!(c_code.contains("float"));
        assert!(rust_expected.contains("f32"));
    }

    /// Test 10: Sum array elements
    /// Common pattern: accumulation
    #[test]
    fn test_array_sum() {
        let c_code = r#"
int arr[5] = {1, 2, 3, 4, 5};
int sum = 0;
for (int i = 0; i < 5; i++) {
    sum += arr[i];
}
"#;

        let rust_loop = r#"
let arr: [i32; 5] = [1, 2, 3, 4, 5];
let mut sum = 0;
for i in 0..5 {
    sum += arr[i];
}
"#;

        let rust_idiomatic = r#"
let arr: [i32; 5] = [1, 2, 3, 4, 5];
let sum: i32 = arr.iter().sum();
"#;

        // Test validates:
        // 1. Traditional loop pattern
        // 2. Rust supports same
        // 3. Iterator .sum() more idiomatic
        assert!(c_code.contains("sum += arr[i]"));
        assert!(rust_loop.contains("sum += arr[i]"));
        assert!(rust_idiomatic.contains(".sum()"));
    }

    /// Test 11: Find element in array
    /// Search pattern
    #[test]
    fn test_array_search() {
        let c_code = r#"
int arr[10] = {1, 5, 3, 7, 2, 8, 4, 6, 9, 0};
int target = 7;
int found = -1;
for (int i = 0; i < 10; i++) {
    if (arr[i] == target) {
        found = i;
        break;
    }
}
"#;

        let rust_expected = r#"
let arr: [i32; 10] = [1, 5, 3, 7, 2, 8, 4, 6, 9, 0];
let target = 7;
let mut found = -1;
for i in 0..10 {
    if arr[i] == target {
        found = i as i32;
        break;
    }
}
"#;

        // Test validates:
        // 1. Linear search pattern
        // 2. Early exit with break
        // 3. Result index or -1
        assert!(c_code.contains("if (arr[i] == target)"));
        assert!(rust_expected.contains("if arr[i] == target"));
    }

    /// Test 12: Copy array elements
    /// Array to array copy
    #[test]
    fn test_array_copy() {
        let c_code = r#"
int src[5] = {1, 2, 3, 4, 5};
int dst[5];
for (int i = 0; i < 5; i++) {
    dst[i] = src[i];
}
"#;

        let rust_loop = r#"
let src: [i32; 5] = [1, 2, 3, 4, 5];
let mut dst: [i32; 5] = [0; 5];
for i in 0..5 {
    dst[i] = src[i];
}
"#;

        let rust_idiomatic = r#"
let src: [i32; 5] = [1, 2, 3, 4, 5];
let mut dst = src;  // Copy trait for arrays
"#;

        // Test validates:
        // 1. C requires manual loop
        // 2. Rust can use loop
        // 3. Rust arrays impl Copy (if T: Copy)
        assert!(c_code.contains("dst[i] = src[i]"));
        assert!(rust_loop.contains("dst[i] = src[i]"));
        assert!(rust_idiomatic.contains("let mut dst = src"));
    }

    /// Test 13: Array as struct member
    /// Embedded array
    #[test]
    fn test_array_in_struct() {
        let c_code = r#"
struct Data {
    int values[10];
    int count;
};

struct Data data = {{0}, 0};
"#;

        let rust_expected = r#"
struct Data {
    values: [i32; 10],
    count: i32,
}

let data = Data {
    values: [0; 10],
    count: 0,
};
"#;

        // Test validates:
        // 1. Array as struct field
        // 2. Initialization syntax
        // 3. Same structure both languages
        assert!(c_code.contains("int values[10]"));
        assert!(rust_expected.contains("values: [i32; 10]"));
    }

    /// Test 14: Const array
    /// Immutable lookup table
    #[test]
    fn test_const_array() {
        let c_code = r#"
const int lookup[5] = {10, 20, 30, 40, 50};
"#;

        let rust_expected = r#"
const LOOKUP: [i32; 5] = [10, 20, 30, 40, 50];
"#;

        // Test validates:
        // 1. Const arrays for lookup tables
        // 2. C lowercase, Rust SCREAMING_CASE
        // 3. Compile-time constant
        assert!(c_code.contains("const int"));
        assert!(rust_expected.contains("const LOOKUP"));
    }

    /// Test 15: Fixed-size array transformation rules summary
    /// Documents all transformation rules in one test
    #[test]
    fn test_array_transformation_rules_summary() {
        let c_code = r#"
// Rule 1: Zero initialization
int arr1[10] = {0};

// Rule 2: Explicit values
int arr2[5] = {1, 2, 3, 4, 5};

// Rule 3: Array access (no bounds check in C!)
int val = arr1[5];

// Rule 4: Array modification
arr1[3] = 42;

// Rule 5: Function parameter (size lost!)
void process(int arr[], int len) { ... }

// Rule 6: Multidimensional
int matrix[3][4] = {0};
"#;

        let rust_expected = r#"
// Rule 1: Zero initialization
let arr1: [i32; 10] = [0; 10];

// Rule 2: Explicit values
let arr2: [i32; 5] = [1, 2, 3, 4, 5];

// Rule 3: Array access (bounds checked!)
let val = arr1[5];

// Rule 4: Array modification (needs mut)
arr1[3] = 42;

// Rule 5: Function parameter (size preserved!)
fn process(arr: &[i32]) { ... }

// Rule 6: Multidimensional
let matrix: [[i32; 4]; 3] = [[0; 4]; 3];
"#;

        // Test validates all transformation rules
        assert!(c_code.contains("int arr"));
        assert!(rust_expected.contains("[i32;"));
        assert!(c_code.contains("arr[]"));
        assert!(rust_expected.contains("&[i32]"));
    }
}