Yineleyici İşlevleri
********************

.[perex]{data-version:4.0.4}
[api:Nette\Utils\Iterables] yineleyicilerle çalışmak için işlevler içeren statik bir sınıftır. Diziler için karşılığı [Nette\Utils\Arrays' |arrays]dir.


Kurulum:

```shell
composer require nette/utils
```

Tüm örnekler aşağıdaki takma adın oluşturulduğunu varsayar:

```php
use Nette\Utils\Iterables;
```


contains(iterable $iterable, $value): bool .[method]
----------------------------------------------------

Bir yineleyici içinde verilen bir değeri arar. Bir eşleşme olup olmadığını kontrol etmek için katı karşılaştırma (`===`) kullanır. Değer bulunursa `true`, aksi takdirde `false` döndürür.

```php
Iterables::contains(new ArrayIterator([1, 2, 3]), 1);    // true
Iterables::contains(new ArrayIterator([1, 2, 3]), '1');  // false
```

Bu yöntem, tüm öğeleri manuel olarak yinelemeden bir yineleyicide belirli bir değerin bulunup bulunmadığını hızlı bir şekilde belirlemeniz gerektiğinde kullanışlıdır.


containsKey(iterable $iterable, $key): bool .[method]
-----------------------------------------------------

Bir yineleyici içinde verilen bir anahtarı arar. Bir eşleşme olup olmadığını kontrol etmek için katı karşılaştırma (`===`) kullanır. Anahtar bulunursa `true`, aksi takdirde `false` döndürür.

```php
Iterables::containsKey(new ArrayIterator([1, 2, 3]), 0);  // true
Iterables::containsKey(new ArrayIterator([1, 2, 3]), 4);  // false
```


every(iterable $iterable, callable $predicate): bool .[method]
--------------------------------------------------------------

Yineleyicinin tüm öğelerinin `$predicate` içinde tanımlanan koşulu sağlayıp sağlamadığını kontrol eder. `$predicate` işlevi `function ($value, $key, iterable $iterable): bool` imzasına sahiptir ve `every()` yönteminin `true` döndürmesi için her öğe için `true` döndürmelidir.

```php
$iterator = new ArrayIterator([1, 30, 39, 29, 10, 13]);
$isBelowThreshold = fn($value) => $value < 40;
$res = Iterables::every($iterator, $isBelowThreshold); // true
```

Bu yöntem, bir koleksiyondaki tüm öğelerin, tüm sayıların belirli bir değerin altında olup olmadığı gibi belirli bir koşulu karşıladığını doğrulamak için kullanışlıdır.


filter(iterable $iterable, callable $predicate): Generator .[method]
--------------------------------------------------------------------

Orijinal yineleyiciden yalnızca `$predicate` adresinde tanımlanan koşulu sağlayan öğeleri içeren yeni bir yineleyici oluşturur. `$predicate` işlevi `function ($value, $key, iterable $iterable): bool` imzasına sahiptir ve tutulması gereken öğeler için `true` döndürmelidir.

```php
$iterator = new ArrayIterator([1, 2, 3]);
$iterator = Iterables::filter($iterator, fn($v) => $v < 3);
// 1, 2
```

Yöntem bir üreteç kullanır, yani filtreleme yineleme sırasında artımlı olarak gerçekleşir. Bu, bellek açısından verimlidir ve çok büyük koleksiyonların işlenmesine olanak sağlar. Elde edilen yineleyicinin tüm öğeleri boyunca yineleme yapmazsanız, orijinal yineleyicinin tüm öğeleri işlenmediğinden hesaplama çabasından tasarruf edersiniz.


first(iterable $iterable, ?callable $predicate=null, ?callable $else=null): mixed .[method]
-------------------------------------------------------------------------------------------

Yineleyicinin ilk öğesini döndürür. `$predicate` sağlanmışsa, verilen koşulu karşılayan ilk öğeyi döndürür. `$predicate` işlevi `function ($value, $key, iterable $iterable): bool` imzasına sahiptir. Eşleşen bir öğe bulunamazsa, `$else` işlevi (sağlanmışsa) çağrılır ve sonucu döndürülür. `$else` sağlanmamışsa, `null` döndürülür.

```php
Iterables::first(new ArrayIterator([1, 2, 3]));                   // 1
Iterables::first(new ArrayIterator([1, 2, 3]), fn($v) => $v > 2); // 3
Iterables::first(new ArrayIterator([]));                          // null
Iterables::first(new ArrayIterator([]), else: fn() => false);     // false
```

Bu yöntem, bir koleksiyonun ilk öğesini veya belirli bir koşulu karşılayan ilk öğeyi, tüm koleksiyonda manuel olarak yinelemeden hızlı bir şekilde almanız gerektiğinde kullanışlıdır.


firstKey(iterable $iterable, ?callable $predicate=null, ?callable $else=null): mixed .[method]
----------------------------------------------------------------------------------------------

Yineleyicinin ilk öğesinin anahtarını döndürür. `$predicate` sağlanmışsa, verilen koşulu karşılayan ilk öğenin anahtarını döndürür. `$predicate` işlevi `function ($value, $key, iterable $iterable): bool` imzasına sahiptir. Eşleşen bir öğe bulunamazsa, `$else` işlevi (sağlanmışsa) çağrılır ve sonucu döndürülür. `$else` sağlanmamışsa, `null` döndürülür.

```php
Iterables::firstKey(new ArrayIterator([1, 2, 3]));                   // 0
Iterables::firstKey(new ArrayIterator([1, 2, 3]), fn($v) => $v > 2); // 2
Iterables::firstKey(new ArrayIterator(['a' => 1, 'b' => 2]));        // 'a'
Iterables::firstKey(new ArrayIterator([]));                          // null
```


map(iterable $iterable, callable $transformer): Generator .[method]
-------------------------------------------------------------------

Orijinal yineleyicinin her bir öğesine `$transformer` işlevini uygulayarak yeni bir yineleyici oluşturur. `$transformer` işlevi `function ($value, $key, iterable $iterable): mixed` imzasına sahiptir ve geri dönüş değeri öğenin yeni değeri olarak kullanılır.

```php
$iterator = new ArrayIterator([1, 2, 3]);
$iterator = Iterables::map($iterator, fn($v) => $v * 2);
// 2, 4, 6
```

Yöntem bir üreteç kullanır, yani dönüşüm yineleme sırasında artımlı olarak gerçekleşir. Bu, bellek açısından verimlidir ve çok büyük koleksiyonların işlenmesine olanak sağlar. Elde edilen yineleyicinin tüm öğeleri boyunca yineleme yapmazsanız, orijinal yineleyicinin tüm öğeleri işlenmediğinden hesaplama çabasından tasarruf edersiniz.


mapWithKeys(iterable $iterable, callable $transformer): Generator .[method]
---------------------------------------------------------------------------

Orijinal yineleyicinin değerlerini ve anahtarlarını dönüştürerek yeni bir yineleyici oluşturur. `$transformer` işlevi `function ($value, $key, iterable $iterable): ?array{$newKey, $newValue}` imzasına sahiptir. `$transformer` , `null` döndürürse, öğe atlanır. Tutulan elemanlar için, döndürülen dizinin ilk elemanı yeni anahtar ve ikinci elemanı yeni değer olarak kullanılır.

```php
$iterator = new ArrayIterator(['a' => 1, 'b' => 2]);
$iterator = Iterables::mapWithKeys($iterator, fn($v, $k) => $v > 1 ? [$v * 2, strtoupper($k)] : null);
// [4 => 'B']
```

 `map()` gibi, bu yöntem de artımlı işleme ve bellek verimliliği için bir üreteç kullanır. Bu, büyük koleksiyonlarla çalışmaya ve sonucun yalnızca bir kısmını işleyerek hesaplama çabasından tasarruf etmeye olanak tanır.


memoize(iterable $iterable): IteratorAggregate .[method]
--------------------------------------------------------

Yineleme sırasında anahtarlarını ve değerlerini önbelleğe alan bir yineleyici etrafında bir sarmalayıcı oluşturur. Bu, orijinal veri kaynağını yeniden işlemek zorunda kalmadan veriler üzerinde tekrarlanan yinelemelere olanak tanır.

```php
$iterator = /* data that cannot be iterated multiple times */
$memoized = Iterables::memoize($iterator);
// Now you can iterate $memoized multiple times without data loss
```

Bu yöntem, aynı veri kümesi üzerinde birden çok kez yineleme yapmanız gereken, ancak orijinal yineleyicinin yinelemeyi desteklemediği veya yinelemenin maliyetli olacağı durumlarda (örneğin, bir veritabanından veya dosyadan veri okuma) kullanışlıdır.


some(iterable $iterable, callable $predicate): bool .[method]
-------------------------------------------------------------

Yineleyicinin en az bir öğesinin `$predicate` içinde tanımlanan koşulu sağlayıp sağlamadığını kontrol eder. `$predicate` işlevi `function ($value, $key, iterable $iterable): bool` imzasına sahiptir ve `some()` yönteminin `true` döndürmesi için en az bir öğe için `true` döndürmelidir.

```php
$iterator = new ArrayIterator([1, 30, 39, 29, 10, 13]);
$isEven = fn($value) => $value % 2 === 0;
$res = Iterables::some($iterator, $isEven); // true
```

Bu yöntem, bir koleksiyonda belirli bir koşulu karşılayan en az bir öğe olup olmadığını (örneğin, koleksiyonun en az bir çift sayı içerip içermediğini) hızlı bir şekilde doğrulamak için kullanışlıdır.

Bkz. [every() |#every()].


toIterator(iterable $iterable): Iterator .[method]
--------------------------------------------------

Herhangi bir yinelenebilir nesneyi (dizi, Traversable) bir Iterator'a dönüştürür. Girdi zaten bir Iterator ise, değişmeden döndürülür.

```php
$array = [1, 2, 3];
$iterator = Iterables::toIterator($array);
// Now you have an Iterator instead of an array
```

Bu yöntem, girdi veri türünden bağımsız olarak bir Yineleyiciniz olduğundan emin olmanız gerektiğinde kullanışlıdır. Bu, farklı yinelenebilir veri türleriyle çalışan fonksiyonlar oluştururken faydalı olabilir.