Implements Iterator trait and for loops.

[esdrubal]

Description

This implements an Iterator trait in std-lib, and adds iter() to Vec.
This also adds parsing and desugaring of for loops.

    for pattern in iterator {
        code_block
    }

is desugared into:

    let mut iterable = iterator;
    while true {
        let value_opt = iterable.next();
        if value_opt.is_none() {
             break;
        }
        let value = value_opt.unwrap();
        code_block
    }

This also adds for loops documentation to the control flow docs.

We still have to fix this issues:

• Improve error handling when bad iterator is used in for loop. #5567
• Add IntoIterator and support to fallback to calling iterator.into_iter() on failure #5568
• Add support for ranges such as 0..10 #5570
• Implement iterator related methods such as zip, enumerate, nth, map, collect ... #5571

Closes #145

Checklist

• I have linked to any relevant issues.
• I have commented my code, particularly in hard-to-understand areas.
• I have updated the documentation where relevant (API docs, the reference, and the Sway book).
• I have added tests that prove my fix is effective or that my feature works.
• I have added (or requested a maintainer to add) the necessary Breaking* or New Feature labels where relevant.
• I have done my best to ensure that my PR adheres to the Fuel Labs Code Review Standards.
• I have requested a review from the relevant team or maintainers.

[IGI-111]

LGTM but @esdrubal can you create the issues you mention in the description before we merge this?

[esdrubal]

@IGI-111 I created the issues.

[xunilrj]

Any reason why we materialize next before the code block?
It makes sense to avoid the generation of the next item if the user wants to break the loop and it is not going to use it.

    let mut iterable = iterator;
    let mut value_opt = iterable.next();
    while value_opt.is_some() {
        let value = value_opt.unwrap();
        code_block                                     // <- swaped this
        value_opt = iterable.next();            // and this
    }

[esdrubal]

Any reason why we materialize next before the code block? It makes sense to avoid the generation of the next item if the user wants to break the loop and it is not going to use it.

    let mut iterable = iterator;
    let mut value_opt = iterable.next();
    while value_opt.is_some() {
        let value = value_opt.unwrap();
        code_block                                     // <- swaped this
        value_opt = iterable.next();            // and this
    }

You may have a continue inside the code_block that would skip the next() call if it is at the end as you suggested.

[esdrubal]

We could fix the issue of calling next prematurely by doing something like:

    let mut iterable = iterator;
    while true {
        let value_opt = iterable.next();
        if value_opt.is_none() {
             break;
        }
        let value = value_opt.unwrap();
        code_block
    }

[IGI-111]

We could fix the issue of calling next prematurely by doing something like:

    let mut iterable = iterator;
    while true {
        let value_opt = iterable.next();
        if value_opt.is_none() {
             break;
        }
        let value = value_opt.unwrap();
        code_block
    }

That seems much more robust. 👍

[esdrubal]

Updated desugaring code to the better version.