| 1 |
# Requirements Document |
| 2 |
|
| 3 |
## Introduction |
| 4 |
|
| 5 |
This feature refactors the CRC-16 and CRC-32 algorithm implementations to share a common base module, reducing code duplication. Since CRC-16 operates in 32-bit space (scaling values up and down), both widths use nearly identical SIMD operations. Extracting this shared logic into a common module improves maintainability and prepares the codebase for future CRC width additions. |
| 6 |
|
| 7 |
## Glossary |
| 8 |
|
| 9 |
- **Width32_Ops**: The shared module containing 32-bit-space SIMD operations used by both CRC-16 and CRC-32 |
| 10 |
- **EnhancedCrcWidth**: The trait that defines width-specific CRC operations |
| 11 |
- **Width16**: The CRC-16 width implementation that operates in 32-bit space |
| 12 |
- **Width32**: The CRC-32 width implementation |
| 13 |
- **Width64**: The CRC-64 width implementation (unchanged by this refactoring) |
| 14 |
- **process_0_to_15**: The function handling small inputs (0-15 bytes) |
| 15 |
- **Barrett_Reduction**: The algorithm for fast modular reduction used in final CRC computation |
| 16 |
|
| 17 |
## Requirements |
| 18 |
|
| 19 |
### Requirement 1: Create Shared Width32 Operations Module |
| 20 |
|
| 21 |
**User Story:** As a library maintainer, I want shared 32-bit-space operations in a common module, so that CRC-16 and CRC-32 implementations don't duplicate code. |
| 22 |
|
| 23 |
#### Acceptance Criteria |
| 24 |
|
| 25 |
1. THE system SHALL create a new module `src/crc32/width32_ops.rs` containing shared 32-bit-space operations |
| 26 |
2. THE Width32_Ops module SHALL export a `process_0_to_15_width32()` function that handles small inputs for both CRC-16 and CRC-32 |
| 27 |
3. THE Width32_Ops module SHALL export helper functions for `fold_16`, `fold_width`, and `barrett_reduction` operations |
| 28 |
4. THE Width32_Ops module SHALL export the shared `load_constants()` values |
| 29 |
5. THE Width32_Ops module SHALL export the shared `get_last_bytes_table_ptr()` logic |
| 30 |
|
| 31 |
### Requirement 2: Refactor Width16 Implementation |
| 32 |
|
| 33 |
**User Story:** As a library maintainer, I want the Width16 implementation to delegate to shared operations, so that code duplication is eliminated. |
| 34 |
|
| 35 |
#### Acceptance Criteria |
| 36 |
|
| 37 |
1. THE Width16 `EnhancedCrcWidth` implementation SHALL delegate `fold_16()` to the shared Width32_Ops module |
| 38 |
2. THE Width16 `EnhancedCrcWidth` implementation SHALL delegate `fold_width()` to the shared Width32_Ops module |
| 39 |
3. THE Width16 `EnhancedCrcWidth` implementation SHALL delegate `create_coefficient()` to the shared Width32_Ops module |
| 40 |
4. THE Width16 `EnhancedCrcWidth` implementation SHALL delegate `perform_final_reduction()` to the shared Width32_Ops module |
| 41 |
5. THE Width16 `EnhancedCrcWidth` implementation SHALL delegate `get_last_bytes_table_ptr()` to the shared Width32_Ops module |
| 42 |
6. THE Width16 `barrett_reduction()` SHALL call the shared implementation and extract the 16-bit result |
| 43 |
7. THE crc16::algorithm::process_0_to_15 function SHALL be removed and replaced with a call to the shared implementation |
| 44 |
|
| 45 |
### Requirement 3: Refactor Width32 Implementation |
| 46 |
|
| 47 |
**User Story:** As a library maintainer, I want the Width32 implementation to use shared operations, so that code duplication is eliminated. |
| 48 |
|
| 49 |
#### Acceptance Criteria |
| 50 |
|
| 51 |
1. THE Width32 `EnhancedCrcWidth` implementation SHALL delegate `fold_16()` to the shared Width32_Ops module |
| 52 |
2. THE Width32 `EnhancedCrcWidth` implementation SHALL delegate `fold_width()` to the shared Width32_Ops module |
| 53 |
3. THE Width32 `EnhancedCrcWidth` implementation SHALL delegate `create_coefficient()` to the shared Width32_Ops module |
| 54 |
4. THE Width32 `EnhancedCrcWidth` implementation SHALL delegate `perform_final_reduction()` to the shared Width32_Ops module |
| 55 |
5. THE Width32 `EnhancedCrcWidth` implementation SHALL delegate `get_last_bytes_table_ptr()` to the shared Width32_Ops module |
| 56 |
6. THE Width32 `barrett_reduction()` SHALL call the shared implementation and extract the 32-bit result |
| 57 |
7. THE crc32::algorithm::process_0_to_15 function SHALL call the shared implementation |
| 58 |
|
| 59 |
### Requirement 4: Backwards Compatibility |
| 60 |
|
| 61 |
**User Story:** As an existing library user, I want all CRC functionality to remain unchanged, so that my existing code continues to work correctly. |
| 62 |
|
| 63 |
#### Acceptance Criteria |
| 64 |
|
| 65 |
1. WHEN computing CRC-16 checksums after refactoring, THE system SHALL produce identical results to the current implementation |
| 66 |
2. WHEN computing CRC-32 checksums after refactoring, THE system SHALL produce identical results to the current implementation |
| 67 |
3. WHEN computing CRC-64 checksums after refactoring, THE system SHALL produce identical results to the current implementation |
| 68 |
4. THE public API SHALL remain unchanged with no breaking changes |
| 69 |
5. ALL existing tests SHALL continue to pass without modification |
| 70 |
|
| 71 |
### Requirement 5: Code Quality |
| 72 |
|
| 73 |
**User Story:** As a library maintainer, I want the refactored code to be clean and maintainable, so that future development is easier. |
| 74 |
|
| 75 |
#### Acceptance Criteria |
| 76 |
|
| 77 |
1. THE refactored code SHALL pass `cargo fmt --check` without errors |
| 78 |
2. THE refactored code SHALL pass `cargo clippy -- -D warnings` without warnings |
| 79 |
3. THE refactored code SHALL pass all existing tests via `cargo test` |
| 80 |
4. THE shared module SHALL have clear documentation explaining its purpose |
| 81 |
5. THE Width16 and Width32 implementations SHALL have comments indicating delegation to shared operations where applicable |