.. _iterators:

========
迭代器
========

迭代器是可以在不知道序列实现细节的情况下遍历序列的对象。

Iterator 类型的定义如下::

    iterator_type ::= iterator < type >

    iterator<int>           // 迭代 Integer
    iterator<const Foo&>    // 通过引用迭代 Foo

可以移动迭代器，但不能复制或克隆迭代器。

迭代器可以通过 ``each`` 函数从范围、静态数组或动态数组中创建。
``each`` 函数是不安全的，因为迭代器没有捕获它的参数::

    unsafe {
        var it <- each ( [1,2,3,4] )
    }

遍历迭代器最直接的方法是使用 ``for`` 循环::

    for ( x in it ) {             // 迭代 'it' 的内容
        print("x = {x}\n")
    }

对于引用迭代器， ``for`` 循环将提供一个引用变量::

    var t = fixed_array(1,2,3,4)
    for ( x in t ) {        // x 是 int&
        x ++                // 增加 t 内的值
    }

迭代器可以从 lambda （参见 :ref:`Lambda <lambdas_iterator>`） 或生成器 （参见 :ref:`Generator <generators>`） 创建。

在迭代器上调用 ``delete`` 会让它序列出来并释放它的内存::

    var it <- each_enum(Numbers one)
    delete it                           // 安全删除

    var it <- each_enum(Numbers one)
    for ( x in it ) {
        print("x = {x}\n")
    }
    delete it                           // 删除 Sequenced Out 迭代器始终是安全的

循环和迭代函数会自动执行此作。

-----------------
内置迭代器
-----------------

表键和值迭代器可以通过 ``keys`` 和 ``values`` 函数获得::

    var tab <- { "one"=>1, "two"=>2 }
    for ( k,v in keys(tab),values(tab) ) {  // keys(tab) 是 iterator<string>
        print("{k} => {v}\n")               // values(tab) 是 iterator<int&>
    }

可以通过 ``each`` 函数迭代字符串的每个字符::

    unsafe {
        for ( ch in each("hello,world!") ) {   // string iterator 是 iterator<int>
            print("ch = {ch}\n")
        }
    }

可以通过 ``each_enum`` 函数迭代枚举的每个元素::

    enum Numbers {
        one
        two
        ten = 10
    }

    for ( x in each_enum(Numbers.one) ) {       // argument 是所述枚举中的任何值
        print("x = {x}\n")
    }

-------------------------------------
内置迭代函数
-------------------------------------

``empty`` 函数检查迭代器是 null 还是已经排序出去::

    unsafe {
        var it <- each ( fixed_array(1,2,3,4) )
        for ( x in it ) {
            print("x = {x}\n")
        }
        verify(empty(it))           // iterator 被排序出来
    }

更复杂的迭代模式可能需要 ``next`` 函数::

    var x : int
    while ( next(it,x) ) {       // 这在语义上等同于`for x in it`
        print("x = {x}\n")
    }

Next 只能对可复制类型进行作。

-------------------------------------
低级内置迭代函数
-------------------------------------

``_builtin_iterator_first``, ``_builtin_iterator_next``, 和 ``_builtin_iterator_close`` 处理迭代器的常规生命周期。
可以使用这些作显式编写 for 循环的语义等效项::

    var it <- each(range(0,10))
    var i : int
    var pi : void?
    unsafe {
        pi = reinterpret<void?> ( addr(i) )
    }
    if ( _builtin_iterator_first(it,pi) ) {
        print("i = {i}\n")
        while ( _builtin_iterator_next(it,pi) ) {
            print("i = {i}\n")
        }
        _builtin_iterator_close(it,pi)
    }

``_builtin_iterator_iterate``是一个功能来统治它们。它的作用类似于上述所有 3 个功能。
在非空迭代器上，它以 `first` 开始，然后继续调用 `next`，直到序列用完。
一旦迭代器被排序出来，它就会调用 `close`::

    var it <- each(range(0,10))
    var i : int
    var pi : void?
    unsafe {
        pi = reinterpret<void?> ( addr(i) )
    }
    while ( _builtin_iterator_iterate(it,pi) ) {     // 这相当于上面的示例
        print("i = {i}\n")
    }

---------------------------
下一页 实现细节
---------------------------

函数 ``next`` 的实现如下::

    def next ( it:iterator<auto(TT)>; var value : TT& ) : bool {
        static_if (!typeinfo can_copy(type<TT>)) {
            concept_assert(false, "requires type
             which can be copied")
        } static_elif (typeinfo is_ref_value(type<TT>)) {
            var pValue : TT - & ?
            unsafe {
                if ( _builtin_iterator_iterate(it, addr(pValue)) ) {
                    value = *pValue
                    return true
                } else {
                    return false
                }
            }
        } else {
            unsafe {
                return _builtin_iterator_iterate(it, addr(value))
            }
        }

请务必注意，内置迭代函数接受指针而不是引用。