feat(iter): add mapi

[peter-jerry-ye]

Related #1866

Note that we may want a labelled argument offset or something similar in the future to avoid computing the addition every time.

[peter-jerry-ye-code-review]

Counter initialization and increment could be optimized

Category
Performance
Code Snippet
let mut i = -1
i = i + 1
Recommendation
Consider using let mut i = 0 for initialization and the increment operator i += 1
Reasoning
Starting from -1 and using addition is less intuitive and potentially less performant than starting from 0 and using the increment operator. The current implementation also requires an additional operation on the first iteration.

Function documentation could be more detailed with examples

Category
Maintainability
Code Snippet
///|
/// Transforms the elements of the iterator using a mapping function.
Recommendation
Add example usage in documentation showing common use cases, similar to other iterator methods
Reasoning
Examples in documentation help users understand the intended usage and make the API more accessible. The current documentation, while technically correct, could be more helpful with concrete examples.

Consider adding bounds check documentation

Category
Maintainability
Code Snippet
pub fn Iter::mapi[T, R](self : Iter[T], f : (Int, T) -> R) -> Iter[R]
Recommendation
Add documentation about the index bounds (starting from 0) and any limitations on the maximum index value
Reasoning
Users should be aware of the index behavior, especially for very large iterators where index values might be important. This helps prevent potential misuse of the API.

[coveralls]

Pull Request Test Coverage Report for Build 6459

Details

• 3 of 3 (100.0%) changed or added relevant lines in 1 file are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage increased (+0.003%) to 92.673%

---

Totals
Change from base Build 6455:	0.003%
Covered Lines:	6122
Relevant Lines:	6606

---

💛 - Coveralls

[hackwaly]

There's both map_with_index and mapi in core. We should choose one to stick.