Add comprehensive examples for lending iterator library

[Crazytieguy]

This PR adds 5 example files demonstrating various features:

• windows.rs: Basic window operations and transformations
• windows_mut.rs: Mutable window operations
• lending_iterator_basics.rs: Converting iterators and basic operations
• advanced_adapters.rs: Filter, map, scan, and other adapters
• reduce_and_fold.rs: Aggregation operations (fold, sum, max, min, etc.)

These examples showcase the key value proposition of lending iterators: the ability to iterate over borrowed data that references the iterator.

Fixes #6

🤖 Generated with Claude Code

[claude]

PR Review: Add comprehensive examples for lending iterator library

Summary

This PR adds 5 well-structured example files demonstrating the library's features. The examples are pedagogically sound and successfully showcase the key value proposition of lending iterators.

---

✅ Strengths

1. Excellent Documentation Value: The examples progress logically from basic concepts to advanced use cases, making the library accessible to new users.

2. Clear Organization: Each example file has a focused theme and uses descriptive println! headers to separate sections.

3. Practical Demonstrations: The examples show real-world use cases like running sums, window normalization, and data transformations.

4. Good Coverage: The examples cover the main API surface including:

   • Window operations (immutable and mutable)
   • Adapter methods (filter, map, scan, take_while, etc.)
   • Aggregation operations (fold, sum, max, min, etc.)
   • Conversion methods (into_lending, lend_refs)

---

🐛 Issues Found

Critical: Misleading example in windows_mut.rs

Location: examples/windows_mut.rs:11-13

data.clone().windows_mut(2).for_each(|window| {
    window[0] *= 2;
});

Problem: This example calls windows_mut() on a clone, which means the mutations are lost immediately. While the comment on line 16 acknowledges this, it defeats the purpose of demonstrating mutable windows.

Impact: Users may copy this pattern and be confused when their mutations don't persist.

Recommendation: Replace with a proper mutable example:

let mut data = vec![1, 2, 3, 4, 5];
println!("Original data: {:?}", data);

// Double the first element of each window of size 2
// Note: Overlapping windows means earlier elements get modified multiple times
data.windows_mut(2).for_each(|window| {
    window[0] *= 2;
});

println!("After modification: {:?}", data);

Or show a non-destructive transformation that actually demonstrates the API properly.

---

Issue: Confusing behavior in windows_mut.rs normalization example

Location: examples/windows_mut.rs:24-31

Problem: The normalization example shows overlapping windows being modified, which creates confusing output because earlier elements get re-normalized by subsequent windows. The comment "partial overlapping modifications" doesn't adequately explain what's happening.

Recommendation: Either:

1. Add a clearer explanation of why the overlapping modifications produce the final result, or
2. Use a simpler example that doesn't have confusing overlap effects

---

💡 Suggestions for Improvement

1. Add comments explaining the lending iterator value proposition: In windows.rs and windows_mut.rs, add a brief comment explaining WHY lending iterators are needed (i.e., the windows borrow from the iterator's internal buffer).

2. Demonstrate error cases: Consider adding an example showing what happens with edge cases like windows(0) or windows(size > data.len()) to help users understand boundary conditions.

3. Show the difference from standard library: In windows.rs, briefly mention how this differs from slice::windows() (which only works on slices, not iterators).

4. Code consistency: Some examples use into_iter().collect() while others use method chaining more directly. Consider standardizing the style.

---

🔒 Security Considerations

No security concerns identified. The examples use safe Rust only and don't expose any unsafe patterns.

---

⚡ Performance Considerations

The examples correctly demonstrate the library's performance characteristics:

• The window buffer growth to size * 2 is mentioned in the trait docs (good!)
• No performance anti-patterns observed in the examples

---

🧪 Test Coverage

Observation: These are examples, not tests. However, they should compile and run without errors.

Recommendation: Before merging, ensure:

cargo build --examples
cargo run --example windows
cargo run --example windows_mut
cargo run --example lending_iterator_basics
cargo run --example advanced_adapters
cargo run --example reduce_and_fold

All examples should compile cleanly and produce sensible output.

---

📋 Final Verdict

Status: Approve with changes requested

This PR successfully addresses issue #6 by adding comprehensive examples. The code quality is good overall, but the windows_mut.rs example needs correction before merge to avoid confusing users.

Action Items:

1. ✋ Must fix: Correct the misleading .clone().windows_mut() pattern
2. 💭 Should consider: Add clearer explanation for overlapping window modifications
3. 💡 Nice to have: Add brief comments explaining the lending iterator value proposition

---

Great work on these examples! They'll significantly improve the library's usability. 🎉