Add more precise types

doc/tags/for.rst

@@ -86,8 +86,7 @@ Use ``loop.cycle`` to cycle among a list of values:
         <li class="{{ loop.cycle('odd', 'even') }}">{{ row }}</li>
     {% endfor %}
 
-Use ``loop.previous`` and ``loop.next`` to compare the current value with the
-previous or next values:
+Use ``loop.previous`` and ``loop.next`` to access the previous or next values:
 
 .. code-block:: twig
 
@@ -101,7 +100,10 @@ previous or next values:
         {% endif %}
     {% endfor %}
 
-Use ``loop.changed`` to check if the value has changed since the last iteration:
+``loop.previous`` is ``null`` when called at the first item, and ``loop.next``
+is ``null`` when called at the last item.
+
+Use ``loop.changed`` to check if the value has changed since the last call:
 
 .. code-block:: html+twig
 

src/Runtime/LoopIterator.php

@@ -25,9 +25,12 @@ final class LoopIterator implements \Iterator
     private \Iterator $seq;
     private int $index0;
     private int $length;
-    private array $previous = [];
-    private array $current = [];
-    private array $next = [];
+    /** @var array{valid: bool, key: mixed, value: mixed} */
+    private array $previous;
+    /** @var array{valid: bool, key: mixed, value: mixed} */
+    private array $current;
+    /** @var array{valid: bool, key: mixed, value: mixed}|null */
+    private ?array $next = null;
 
     public function __construct($seq)
     {
@@ -49,7 +52,7 @@ final class LoopIterator implements \Iterator
     {
         $this->previous = $this->current;
         if ($this->next) {
-            $this->next = [];
+            $this->next = null;
         } else {
             $this->seq->next();
         }
@@ -62,7 +65,7 @@ final class LoopIterator implements \Iterator
         $this->seq->rewind();
         $this->previous = ['valid' => false, 'key' => null, 'value' => null];
         $this->current = ['valid' => $this->seq->valid(), 'key' => $this->seq->key(), 'value' => $this->seq->current()];
-        $this->next = [];
+        $this->next = null;
         $this->index0 = 0;
     }
 
@@ -96,20 +99,21 @@ final class LoopIterator implements \Iterator
 
     public function isLast(): bool
     {
-        return !$this->peek()['valid'];
+        return !$this->getNext()['valid'];
     }
 
+    /**
+     * @return array{valid: bool, key: mixed, value: mixed}
+     */
     public function getPrevious(): array
     {
         return $this->previous;
     }
 
+    /**
+     * @return array{valid: bool, key: mixed, value: mixed}
+     */
     public function getNext(): array
-    {
-        return $this->peek();
-    }
-
-    public function peek(): array
     {
         if (!$this->next) {
             $this->seq->next();