iterator_count — Funktion · PHP-Referenz

Signatur

iterator_count(Traversable $iterator): int

Beschreibung

iterator_count() ermittelt die Anzahl der Elemente, die ein Traversable-Objekt liefert, indem es den Iterator von Anfang bis Ende vollständig durchläuft und dabei jeden Schritt zählt. Der Rückgabewert entspricht der Anzahl der Iterationsschritte.

Wichtig zu verstehen ist, dass die Funktion den Iterator tatsächlich vollständig konsumiert. Bei Iteratoren, die keinen rewind()-Mechanismus besitzen (z. B. Generatoren), ist der Iterator nach dem Aufruf erschöpft und kann nicht erneut durchlaufen werden. Bei regulären Objekten, die Iterator implementieren, wird rewind() am Anfang aufgerufen.

Typische Anwendungsfälle sind die Vorababfrage der Elementanzahl eines Datenbankresultats, eines Generators oder einer gefilterten Iterator-Kette (z. B. CallbackFilterIterator, LimitIterator), ohne die Daten manuell in ein Array umwandeln zu müssen.

Für Arrays steht count() zur Verfügung; für Countable-Objekte genügt ebenfalls count(). iterator_count() ist dann sinnvoll, wenn das Objekt lediglich Traversable, aber nicht Countable ist.

Parameter

Name	Typ	Default	Beschreibung
$iterator Pflicht	Traversable		Ein `Iterator`- oder `IteratorAggregate`-Objekt, dessen Elemente gezählt werden sollen. Das Objekt wird dabei vollständig durchlaufen.

Rückgabewert

Typ

int

Beschreibung

Gibt die Anzahl der Iterationsschritte als nicht-negatives int zurück. Bei einem leeren Iterator wird 0 zurückgegeben.

Beispiele

Elemente eines ArrayIterators zählen

<?php
$array = ['Apfel', 'Birne', 'Kirsche', 'Mango'];
$iterator = new ArrayIterator($array);

$anzahl = iterator_count($iterator);
echo "Anzahl der Elemente: " . $anzahl;

Anzahl der Elemente: 4

Gefilterte Elemente mit CallbackFilterIterator zählen

<?php
$daten = new ArrayIterator([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);

// Nur gerade Zahlen durchlassen
$gefilterter = new CallbackFilterIterator($daten, function (int $wert): bool {
    return $wert % 2 === 0;
});

$anzahlGerade = iterator_count($gefilterter);
echo "Anzahl gerader Zahlen: " . $anzahlGerade;

Anzahl gerader Zahlen: 5

Generator wird nach iterator_count() erschöpft

<?php
function zahlenGenerator(int $bis): Generator {
    for ($i = 1; $i <= $bis; $i++) {
        yield $i;
    }
}

$gen = zahlenGenerator(5);
echo "Anzahl: " . iterator_count($gen) . PHP_EOL;

// Generator ist jetzt erschöpft!
$rest = iterator_to_array($gen);
echo "Elemente nach iterator_count: " . count($rest);

Anzahl: 5 Elemente nach iterator_count: 0

// Wichtig · Fallstricke

Achtung bei Generatoren: Da Generatoren nicht zurückgespult werden können, ist der Generator nach dem Aufruf von iterator_count() vollständig erschöpft. Wenn die Elemente anschließend noch benötigt werden, sollten sie zuerst mit iterator_to_array() in ein Array umgewandelt werden, auf dem dann count() aufgerufen werden kann.

Performance: Bei sehr großen oder ressourcenintensiven Iteratoren kann das vollständige Durchlaufen teuer sein. Wenn das Objekt Countable implementiert, ist count($objekt) deutlich effizienter.

Ab PHP 8.2 akzeptiert die Funktion ausschließlich Traversable-Objekte. Die frühere implizite Übergabe von Arrays führt zu einem TypeError.

Siehe auch

iterator_to_array iterator_apply count Iterator Traversable CallbackFilterIterator