Home

Emonkak\Collection

Requirements

• PHP 5.4 or higher
• HHVM

API Reference

Emonkak\Collection\CollectionのAPIリファレンスです。

Enumerable Trait

Emonkak\Collection\CollectionのインスタンスメソッドはすべてEmonkak\Collection\Enumerableで実装されているので、 これをuseすることで任意のクラスでこれらのメソッドを呼び出すこともできます。

エイリアスメソッドについてはEmonkak\Collection\EnumerableAliasesで実装されています。

Accessor Expression

$valueSelectorのようにselectorと付いたパラメータには関数の他、配列とオブジェクトのアクセサーを表す文字列を渡すことができます。 配列に対するアクセサーは[foo]のように、オブジェクトに対するアクセサーはfooのように表記します。 ネストした配列・オブジェクトに対するアクセサーをfoo[bar].bazのように定義することもできます。

Collection::from([['foo' => 1], ['foo' => 2]])
  ->map('[foo]')
  ->toList()
// => [1, 2]

Collection::from(Traversable|mixed[] $source): Collection

配列かTraversableな値からコレクションを生成します。

Collection::from([1, 2, 3]);
Collection::from(new \ArrayIterator([1, 2, 3]));

Collection::concat(mixed[][] $sources): Collection

引数で指定された複数の要素の一覧を結合して1つのコレクションにします。

Collection::concat([[1, 2, 3], [4, 5, 6]]);
// => [1, 2, 3, 4, 5, 6]

Collection::iterate(mixed $acc, callable $f): Collection

$accに対して$fを繰り返し適用して要素を生成するコレクションを返します。

Collection::iterate(0, function($n) {
    return $n + 1;
  })
  ->take(5)
  ->toList();
// => [0, 1, 2, 3, 4]

Collection::range(integer $start, integer $end [, integer $step = 1]): Collection

$startから$stepごとにインクリメントされた$endまでの数値を要素とするコレクションを生成します。 $stepに負の値を設定するとデクリメントされます。 $endに指定した数値自体は含まれません。

Collection::range(10);
// => [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

Collection::range(1, 11);
// => [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

Collection::range(0, 30, 5);
// => [0, 5, 10, 15, 20, 25]

Collection::range(0, -10, -1);
// => [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]

Collection::range(0);
// => []

Collection::repeat(mixed $value [, integer $n ]): Collection

$valueが$n個分繰り返されるコレクションを返します。 $nが与えられなかった場合は$valueの無限コレクションが得られます。

Collection::repeat(1, 2);
// => [1, 1]

Collection::repeat(1)->take(5)->toList();
// => [1, 1, 1, 1, 1]

Collection::union(mixed[][] $sources): Collection

引数で指定した複数の要素の一覧を結合した上で、重複した要素を除いたコレクションを返します。 concat()した後にuniq()を呼び出すのと等価です。

Collection::union([[1, 2, 3], [101, 2, 1, 10], [2, 1]]);
// => [1, 2, 3, 101, 10]

Collection::zip(mixed[][] $sources): Collection

コレクションの各要素のインデックスが対応するもの同士を配列にしたコレクションを返します。

要素数が違う場合は小さいものに合わせます。

Collection::zip([['moe', 'larry', 'curly'], [30, 40, 50], [true, false, false]]);
// => [["moe", 30, true], ["larry", 40, false], ["curly", 50, false]]

each(callable $f): void

コレクションの各要素に対して関数$fを呼び出します。 $fは($element, $key, $array)の3つの引数を取ります。

Collection::from([1, 2, 3])->each(function($x, $k, $xs) {
    // 1, 2, 3を順番に出力
    echo $x, PHP_EOL;
});

$xs = ['one' => 1, 'two' => 2, 'three' => 3];
Collection::from($xs)->each(function($x, $k, $xs) {
    // one-1, two-2, three-3を順番に出力
    echo $k, '-', $x, PHP_EOL;
});

map(callable $valueSelector, callable $keySelector): Collection

Alias: collect()

コレクションの各要素に対して関数$valueSelectorを適用します。 $valueSelectorは($element, $key, $xs)の3つの引数を取ります。

$keySelectorが与えられた場合はキーに対しても関数を適用します。 $keySelectorは($key, $element, $xs)の3つの引数を取ります。

Collection::from([1, 2, 3])->map(function($x) {
    return $x * 3;
});
// => [3, 6, 9]

Collection_::from(['one' => 1, 'two' => 2, 'three' => 3])->map(function($x) {
    return $x * 3;
});
// => [3, 6, 9]

concatMap(callable $valueSelector): Collection

Alias: flatMap()

コレクションの各要素に対して関数$valueSelectorを適用した結果を平坦化して返します。

Collection::from([1, 2, 3])
    ->concatMap(function($n) {
        return range(1, $n);
    });
// => [1, 1, 2, 1, 2, 3];

parMap(callable $valueSelector [, integer $n = 4 [, $timeout = null ] ]): Collection

コレクションの各要素に対して関数$valueSelectorを並列に適用します。

$valueSelectorは引数(element)を1つだけ取る関数です。 $nは同時に起動するワーカープロセスの数です。 $nが2以上の時は複数のワーカープロセスによって処理されるため、返ってくる要素の順序は不定です。 $timeoutが与えられた時は指定した秒数で処理をタイムアウトさせます。

parMap()は内部でpcntl_fork()を利用しているので処理系が--enable-pcntlを指定してコンパイルされている必要があります。

$xs = Collection::from([1, 2, 3])->parMap(function($x) {
    sleep(2);
    return $x * 3;
});
// 4並列で実行されるので約2秒ですべての計算が終わる
foreach ($xs as $x) {
    var_dump($x);  // 3, 6, 9が順不同に出力される
}

reduce(callable $f, mixed $acc): mixed

Aliases: inject(), foldl()

コレクションの要素の左結合で畳み込んだ結果を返します。 $fは($acc, $value, $key, $xs)の4つの引数を取ります。

$sum = Collection::from([1, 2, 3])->reduce(function($acc, $n) {
    return $acc + $n;
}, 0);
// => 6

reduceRight(callable $f, mixed $acc): mixed

Aliases: foldr()

コレクションの要素を右結合で畳み込んだ結果を返します。 $fは($acc, $value, $key, $xs)の4つの引数を取ります。

$xss = [[0, 1], [2, 3], [4, 5]];
$flat = Collection::from($xss)->reduceRight(function($acc, $xs) {
    return array_merge($acc, $xs);
}, []);
// => [4, 5, 2, 3, 0, 1]

find(callable $valueSelector): mixed

Alias: detect()

コレクションの要素の中から$valueSelectorが最初にtrueを返す要素を返します。 見付からなかった場合はnullを返します。

$even = Collection::from([1, 2, 3, 4, 5, 6])->find(function($n) {
    return $n % 2 === 0;
});
// => 2

filter(callable $valueSelector): Collection

Alias: select()

コレクションの要素について$valueSelectorがtrueを返すものを選択します。 逆の操作を行なうメソッドとしてreject()があります。

キーを維持したままフィルタリングをするので、返り値のコレクションのインデックスは連番にならないことがあります。

$evens = Collection::from([1, 2, 3, 4, 5, 6])->filter(function($n) {
    return $n % 2 === 0;
});
// => [1 => 2, 3 => 4, 5 => 6]

where(array $properties): Collection

コレクションの要素から$propertiesのキーと値のペアに一致するものを選択します。

$members = [
    ['name' => 'Yui Ogura', 'age' => 17],
    ['name' => 'Rina Hidaka', 'age' => 19],
    ['name' => 'Yuka Iguchi', 'age' => 24],
    ['name' => 'Yoko Hikasa', 'age' => 27],
    ['name' => 'Kana Hanazawa', 'age' => 24]
];
Collection::from($members)->where(['[age]' => 24]);
// => [
//   ["name" => "Yuka Iguchi", "age" => 24],
//   ["name" => "Kana Hanazawa", "age" => 24]
// ]

findWhere(array $properties): mixed

コレクションの要素から$propertiesのキーと値のペアに最初に一致するものを返します。 見付からなかった場合はnullを返します。

$members = [
    ['name' => 'Yukari Tamura', 'age' => 17],
    ['name' => 'Yui Horie', 'age' => 17]
];
Collection::from($members)->findWhere(['[age]' => 17]);
// => ["name" => "Yukari Tamura", "age" => 17]

reject(callable $valueSelector): Collection

コレクションの要素について$valueSelectorがtrueを返すものを除外します。 逆の操作を行うメソッドとしてfilter()があります。

キーを維持したままフィルタリングをするので、返り値のコレクションのインデックスは連番にならないことがあります。

$odds = Collection::from([1, 2, 3, 4, 5, 6])->reject(function($n) {
    return $n % 2 === 0;
});
// => [0 => 1, 2 => 3, 4 => 5]

every([ callable $valueSelector ]): boolean

Alias: all()

コレクションの要素がすべてtrueとして評価される値であればtrueを返します。

$valueSelectorが与えられた時はその結果から判断します。

Collection::from([true, 1, null, 'yes'])->every();
// => false

some([ callable $valueSelector ]): boolean

Alias: any()

コレクションの要素の中にtrueとして評価される値が1つでもあればtrueを返します。

$valueSelectorが与えられた時はその結果から判断します。

Collection::from([true, 1, null, 'yes'])->some();
// => true

contains(mixed $target): boolean

Alias: includes()

コレクションの要素に$targetが含まれていればtrueを返します。 比較は===演算子を使って厳密に行われます。

Collection::from([1, 2, 3])->contains(3);
// => true

invoke(string $method [, mixed ...$argments]): Collection

コレクションの要素をオブジェクトと見なして指定した$methodを呼び出します。

$xs = [new DateTime('2000-01-01'), new DateTime('2013-01-01')];
Collection::from($xs)->invoke('format', 'Y-m-d H:i:s');
// => [
//   "2000-01-01 00:00:00",
//   "2013-01-01 00:00:00"
// ]

pluck(string $property): Collection

コレクションの要素の中から指定した$propertyの値を抽出します。

$stooges = [
    ['name' => 'moe', 'age' => 40],
    ['name' => 'larry', 'age' => 50],
    ['name' => 'curly', 'age' => 60]
];
Collection::from($stooges)->pluck('[name]');
// => ["moe", "larry", "curly"]

join(mixed[] $inner, callable $outerKeySelector, callable $innerKeySelector, callable $resultValueSelector): Collection

コレクションの要素と$innerの要素を一致するキーに基いて結合させます。 キーが一致する要素がないものは結果に含まれません(内部結合)。

キーは、コレクションの要素に対する$outerKeySelectorの呼び出し、$innerの要素に対する$innerKeySelectorの呼び出しで決定されます。

$resultValueSelectorはキーが一致した要素のペアを受け取って結果を返す関数です。 引数は($outerValue, $innerValue)で与えられます。

$users = [
    ['user_id' => 1, 'name' => 'User1'],
    ['user_id' => 2, 'name' => 'User2'],
    ['user_id' => 3, 'name' => 'User3'],
    ['user_id' => 4, 'name' => 'User4'],
    ['user_id' => 5, 'name' => 'User5'],
];
$addresses = [
    ['user_id' => 1, 'address' => 'Address1'],
    ['user_id' => 2, 'address' => 'Address2'],
    ['user_id' => 2, 'address' => 'Address3'],
    ['user_id' => 5, 'address' => 'Address4']
];
Collection::from($users)
    ->join(
        $addresses,
        function($user) { return $user['user_id']; },
        function($address) { return $address['user_id']; },
        function($user, $address) {
            $user['address'] = $address;
            return $user;
        }
    );
// => [
//   ['user_id' => 1, 'name' => 'User1', 'address' => ['user_id' => 1, 'address' => 'Address1']],
//   ['user_id' => 2, 'name' => 'User2', 'address' => ['user_id' => 2, 'address' => 'Address2']],
//   ['user_id' => 2, 'name' => 'User2', 'address' => ['user_id' => 2, 'address' => 'Address3']],
//   ['user_id' => 5, 'name' => 'User5', 'address' => ['user_id' => 5, 'address' => 'Address4']
// ]

outerJoin(mixed[] $inner, callable $outerKeySelector, callable $innerKeySelector, callable $resultValueSelector): Collection

コレクションの要素と$innerの要素を一致するキーに基いて結合させます。 キーが一致する要素がないものはnullとして$resultValueSelectorに渡されます(外部結合)。

キーは、コレクションの要素に対する$outerKeySelectorの呼び出し、$innerの要素に対する$innerKeySelectorの呼び出しで決定されます。

$resultValueSelectorはキーが一致した要素のペアを受け取って結果を返す関数です。 引数は($outerValue, $innerValue)で与えられます。 $innerValueはnullの可能性があります。

$users = [
    ['user_id' => 1, 'name' => 'User1'],
    ['user_id' => 2, 'name' => 'User2'],
    ['user_id' => 3, 'name' => 'User3'],
    ['user_id' => 4, 'name' => 'User4'],
    ['user_id' => 5, 'name' => 'User5'],
];
$addresses = [
    ['user_id' => 1, 'address' => 'Address1'],
    ['user_id' => 2, 'address' => 'Address2'],
    ['user_id' => 2, 'address' => 'Address3'],
    ['user_id' => 5, 'address' => 'Address4']
];
Collection::from($users)
    ->join(
        $addresses,
        function($user) { return $user['user_id']; },
        function($address) { return $address['user_id']; },
        function($user, $address) {
            $user['address'] = $address;
            return $user;
        }
    );
// => [
//   ['user_id' => 1, 'name' => 'User1', 'address' => ['user_id' => 1, 'address' => 'Address1']],
//   ['user_id' => 2, 'name' => 'User2', 'address' => ['user_id' => 2, 'address' => 'Address2']],
//   ['user_id' => 2, 'name' => 'User2', 'address' => ['user_id' => 2, 'address' => 'Address3']],
//   ['user_id' => 3, 'name' => 'User3', 'address' => null],
//   ['user_id' => 4, 'name' => 'User3', 'address' => null],
//   ['user_id' => 5, 'name' => 'User5', 'address' => ['user_id' => 5, 'address' => 'Address4']
// ]

groupJoin(mixed[] $inner, callable $outerKeySelector, callable $innerKeySelector, callable $resultValueSelector): Collection

コレクションの要素と$innerの要素を一致するキーに基いて結合させてその結果をグループ化します。

キーは、コレクションの要素に対する$outerKeySelectorの呼び出し、$innerの要素に対する$innerKeySelectorの呼び出しで決定されます。

$resultValueSelectorはキーが一致した要素のペアを受け取って結果を返す関数です。 引数は($outerValue, $innerValues)で与えられます。 $innerValueはnullの可能性があります。

$users = [
    ['user_id' => 1, 'name' => 'User1'],
    ['user_id' => 2, 'name' => 'User2'],
    ['user_id' => 3, 'name' => 'User3'],
    ['user_id' => 4, 'name' => 'User4'],
    ['user_id' => 5, 'name' => 'User5'],
];
$addresses = [
    ['user_id' => 1, 'address' => 'Address1'],
    ['user_id' => 2, 'address' => 'Address2'],
    ['user_id' => 2, 'address' => 'Address3'],
    ['user_id' => 5, 'address' => 'Address4']
];
Collection::from($users)
    ->groupJoin(
        $addresses,
        function($user) { return $user['user_id']; },
        function($addresses) { return $address['user_id']; },
        function($user, $addresses) {
            $user['addresses'] = $addresses;
            return $user;
        }
    );
// => [
//   ['user_id' => 1, 'name' => 'User1', 'addresses' => [['user_id' => 1, 'address' => 'Address1']]],
//   ['user_id' => 2, 'name' => 'User2', 'addresses' => [['user_id' => 2, 'address' => 'Address2'], ['user_id' => 2, 'address' => 'Address3']]],
//   ['user_id' => 3, 'name' => 'User3', 'addresses' => []],
//   ['user_id' => 4, 'name' => 'User3', 'addresses' => []],
//   ['user_id' => 5, 'name' => 'User5', 'address' => [['user_id' => 5, 'address' => 'Address4']]
// ]

max([ callable $valueSelector ]): mixed

コレクションの要素の中から最大の値を返します。 $valueSelectorに関数を指定した場合は、その関数を適用した結果を基準にします。 $valueSelectorに文字列を指定した場合は、該当のプロパティを基準にします。 $xsが空の時は-INFを返します。

$stooges = [
    ['name' => 'moe', 'age' => 40],
    ['name' => 'larry', 'age' => 50],
    ['name' => 'curly', 'age' => 60]
];
Collection::from($stooges)->max('[age]');
// => ["name" => "curly", "age" => 60]

maxWith(callable $comparer): mixed

コレクションの要素の中から比較関数$comparerの結果を基準に、最大の要素を返します。

Collection::from([1, 2, 3])
    ->maxWith(function($v0, $v1) {
        if ($v0 == $v1) return 0;
        return ($v0 < $v1) ? -1 : 1;
    });
// => 3

min([ callable $valueSelector ]): mixed

コレクションの要素の中の最小の値を返します。 $valueSelectorに関数を指定した場合は、その関数を適用した結果を基準にします。 $valueSelectorに文字列を指定した場合は、該当のプロパティを基準にします。 $xsが空の時はINFを返します。

$stooges = [
    ['name' => 'moe', 'age' => 40],
    ['name' => 'larry', 'age' => 50],
    ['name' => 'curly', 'age' => 60]
];
Collection::from($stooges)->min('[age]');
// => ["name" => "moe", "age" => 40]

minWith([ callable $comparer ]): mixed

コレクションの要素の中から比較関数$comparerの結果を基準に、最小の要素を返します。

Collection::from([3, 2, 1])
    ->maxWith(function($v0, $v1) {
        if ($v0 == $v1) return 0;
        return ($v0 < $v1) ? -1 : 1;
    });
// => 1

sum(): integer

コレクションの要素の合計を返します。

Collection::from([0, 1, 2, 3, 4, 5])->sum();
=> 15

product(): integer

コレクションの要素の積を返します。

Collection::from([0, 1, 2, 3, 4, 5])->product();
=> 120

average(): integer

コレクションの要素を数値と見なして平均を求めます。

Collection::from([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])->average();
=> 4.5

sortBy([ callable $valueSelector ]): Collection

コレクションの要素を比較関数$valueSelectorを使ってソートします。 $valueSelectorに文字列を指定した場合は該当するプロパティを基準にします。 比較関数は事前にすべての要素に対して計算するので、要素の数だけしか呼び出されません。

Collection::from([1, 2, 3, 4, 5, 6])->sortBy(function($n) { return sin($n); });
// => [5, 4, 6, 3, 1, 2]

groupBy([ callable $valueSelector ]): Collection

コレクションの要素を$valueSelectorを呼び出した結果を基準にグループ化します。

Collection::from([1.3, 2.1, 2.4])->groupBy(function($n) { return floor($n); });
// => [1 => [1.3], 2 => [2.1, 2.4]]

indexBy([ callable $valueSelector ]): Collection

コレクションの要素を$valueSelectorを呼び出した結果をキーとした新しい配列にします。

$stooges = [
    ['name' => 'moe', 'age' => 40],
    ['name' => 'larry', 'age' => 50],
    ['name' => 'curly', 'age' => 60]
];
Collection::from(stooges)->indexBy('[age]');
// => [
//   40 => ['name' => 'moe', 'age' => 40],
//   50 => ['name' => 'larry', 'age' => 50],
//   60 => ['name' => 'curly', 'age' => 60]
// ]

countBy([ callable $valueSelector ]): Collection

コレクションの要素を$valueSelectorを呼び出した結果から数え上げます。

Collection::from([1, 2, 3, 4, 5])->countBy(function($n) {
  return $n % 2 === 0 ? 'even' : 'odd';
});
// => ["odd" => 3, "even" => 2]

shuffle(): Collection

コレクションの要素の順序をシャッフルします。

Collection::from([1, 2, 3, 4, 5, 6])->shuffle();
// => [4, 1, 6, 3, 5, 2]

sample([ integer $n ]): mixed|Collection

コレクションから要素を1つランダムに選んで返します。 $nが与えらた場合は$n個の要素をランダムに選択された新しいコレクションを返します。

Collection::from([1, 2, 3, 4, 5, 6])->sample();
// => 4

Collection::from([1, 2, 3, 4, 5, 6])->sample(3);
// => [1, 6, 2]

memoize(): Collection

一度生成された要素をキャッシュするコレクションを返します。

Collection::iterate([0, 1], function($pair) {
        return [$pair[1], $pair[0] + $pair[1]];
    })
    ->map(function($pair) { return $pair[0]; })
    ->memoize()
    ->take(10)
    ->last();
// => 34

toArray(): array

コレクションをキーを維持したまま連想配列にします。

Collection::from(new \ArrayObject(['a' => 1, 'b' => 2, 'c' => 3]))->toArray();
// => ["a" => 1, "b" => 2, "c" => 3]

toArrayRec([ integer $depth ]): array

コレクションをキーを維持したまま再帰的に連想配列にします。 $depthが与えられた場合はその深さまでしか処理しません。

Collection::from([new \ArrayObject(['foo' => 1, 'bar' => 2]), new \ArrayObject(['baz' => 3])])->toArrayRec();
// => [['foo' => 1, 'bar' => 2], ['baz' => 3]]

toList(): mixed[]

コレクションを連番のインデックスの配列にします。

Collection::from(new \ArrayObject(['a' => 1, 'b' => 2, 'c' => 3]))->toList();
// => [1, 2, 3]

toListRec(): mixed[]

コレクションを再帰的に連番のインデックスの配列にします。 $depthが与えられた場合はその深さまでしか処理しません。

Collection::from([new \ArrayObject(['foo' => 1, 'bar' => 2]), new \ArrayObject(['baz' => 3])])->toListRec();
// => [[1, 2], [3]]

size(): integer

コレクションの要素数を返します。

Collection::from(["one" => 1, "two" => 2, "three" => 3])->size();
// => 3

first([ integer $n ]): mixed|Collection

Aliases: head(), take()

コレクションの最初の要素を返します。 $nを指定した場合は先頭からn個分の要素を含むコレクションを返します。

Collection::from([1, 2, 3])->first();
// => 1

Collection::from([1, 2, 3])->first(1);
// => [1]

Collection::from([1, 2, 3])->first(2);
// => [1, 2]

firstOrElse(mixed $default): mixed

コレクションの最初の要素を返します。見付からなかった場合は$defaultを返します。

Collection::from([1, 2, 3])->firstOrElse(10);
// => 1

Collection::from([])->firstOrElse(10);
// => 10

initial([ integer $n = 1 ]): Collection

コレクションの末尾から$n個の要素を除いた新しいコレクションを返します。

Collection::from([5, 4, 3, 2, 1])->initial();
// => [5, 4, 3, 2]

last([ integer $n ]): mixed|Collection

コレクションの最後の要素を返します。 $nに2以上の値が指定された時は末尾の$n個の要素からなるコレクションを返します。

Collection::from([5, 4, 3, 2, 1])->last();
// => 1

Collection::from([5, 4, 3, 2, 1])->last(2);
// => [2, 1]

lastOrElse(mixed $default): mixed

コレクションの最後の要素を返します。見付からなかった場合は$defaultを返します。

Collection::from([1, 2, 3])->lastOrElse(10);
// => 3

Collection::from([])->lastOrElse(10);
// => 10

rest([ integer $n = 1 ]): Collection

Aliases: tail(), drop()

コレクションの先頭から$n個の要素を除いた新しいコレクションを返します。

Collection::from([5, 4, 3, 2, 1])->rest();
// => [4, 3, 2, 1]

takeWhile(callable $valueSelector): Collection

$valueSelectorが最初にtrueを返すまでの要素からなるコレクションを返します。

Collection::from([1, 2, 3, 4, 5, 1, 2, 3])->takeWhile(function($x) {
    return $x < 3;
});
// => [1, 2]

dropWhile(callable $valueSelector): Collection

$valueSelectorが最初にtrueを返すまでの要素を除いたコレクションを返します。

Collection::from([1, 2, 3, 4, 5, 1, 2, 3])->dropWhile(function($x) {
    return $x < 3;
});
// => [3, 4, 5, 1, 2, 3]

compact(): Collection

コレクションの要素の中からfalseとして評価される値を除いた新しいコレクションを返します。

Collection::from([0, 1, false, 2, '', 3])->compact();
// => [1, 2, 3]

flatten([ boolean $shallow = false ]): Collection

ネストしたコレクションの要素を平坦化します。 $shallowがtrueの時は1つ分の深さしか平坦化しません。

Collection::from([1, [2], [3, [[4]]]])->flatten();
=> [1, 2, 3, 4]

Collection::from([1, [2], [3, [[4]]]], true)->flatten();
=> [1, 2, 3, [[4]]]

without(mixed ...$values): Collection

コレクションの要素から$valuesの値を除いた新しいコレクションを返します。

Collection::from([1, 2, 1, 0, 3, 1, 4])->without(0, 1);
// => [2, 3, 4]

unionWith(mixed[] ...$xss): Collection

Collection::union()のインスタンスメソッド版です。

引数で指定した複数の要素の一覧を結合した上で、重複した要素を除いたコレクションを返します。 concat()した後にuniq()を呼び出すのと等価です。

Collection::from([1, 2, 3])->union([101, 2, 1, 10], [2, 1]);
// => [1, 2, 3, 101, 10]

intersection(mixed[] ...$xss): Collection

与えられた要素の一覧$xssすべてに存在する要素でのみ構成されるコレクションを返します。

Collection::from([1, 2, 3])->intersection([101, 2, 1, 10], [2, 1]);
// => [1, 2]

difference(mixed[] ...$others): Collection

コレクションの要素から$othersの要素を取り除いた新しいコレクションを返します。

Collection::from([1, 2, 3, 4, 5])->difference([5, 2, 10]);
// => [1, 3, 4]

uniq([ callable $valueSelector ]): Collection

Alias: unique()

コレクションの要素から重複するものを排除します。 $valueSelectorに関数が与えられた場合は$valueSelectorを適用した結果を基準にします。 比較は型によって厳密に行われます。

Collection::from([1, 2, 1, 3, 1, 4])->uniq();
// => [1, 2, 3, 4]

zipWith(mixed ...$xss: mixed[]): Collection

Collection::zip()のインスタンスメソッド版です。

コレクションの各要素のインデックスが対応するもの同士を配列にしたコレクションを返します。

要素数が違う場合は小さいものに合わせます。

Collection::from(['moe', 'larry', 'curly'])->zip([30, 40, 50], [true, false, false]);
// => [["moe", 30, true], ["larry", 40, false], ["curly", 50, false]]

unzip(): Collection

Collection::zip()によって結合された要素を元に戻します。

Collection::from([['moe', 'larry', 'curly'], [30, 40, 50], [true, false, false]])->unzip();
// => [["moe", 30, true], ["larry", 40, false], ["curly", 50, false]]

object([ array $values ]): Collection

$xsの要素をキーとして$valuesの要素を値としてコレクションを作成します。 $valuesが与えらなかった場合は$xsにキーと値のペアが格納されていることを期待します。

Collection::from(['moe', 'larry', 'curly'])->object([30, 40, 50]);
// => ["moe" => 30, "larry" => 40, "curly" => 50]

Collection::from([['moe', 30], ['larry', 40], ['curly', 50]])->object();
// => ["moe" => 30, "larry" => 40, "curly" => 50]

indexOf(mixed $value [, integer|boolean $fromIndex = 0]): integer

コレクションの中から$valueのあるインデックスを探します。 存在しなかった場合は-1を返します。 $fromIndexを指定した場合はそのインデックスから探索を開始します。

ソート済みのであることが保証されていれば$fromIndexにtrueを指定することで、二分探索による効率的な探索を実行できます。

Collection::from([1, 2, 3])->indexOf(2);
// => 1

lastIndexOf(mixed $value [, integer $fromIndex = 0]): integer

コレクションの中から$valueのあるインデックスを探します。 indexOf()の末尾から探索する版です。

Collection::from([1, 2, 3, 1, 2, 3])->lastIndexOf(2);
=> 4

sortedIndex(mixed $value [, callable $valueSelector ]): integer

コレクションから二分探索で$valueの挿入位置を調べます。

Collection::from([10, 20, 30, 40, 50])->sortedIndex(35);
// => 3

$stooges = [
    ['name' => 'moe', 'age' => 40],
    ['name' => 'curly', 'age' => 60]
];
Collection::from($stooges)->sortedIndex(['name' => 'larry', 'age' => 50], '[age]');
// => 1

intercalate(string $separator): string

コレクションの要素を$separatorを区切りにして文字列として結合します。

Collection::from(['foo', 'bar', 'baz'])->intercalate(',');
// => 'foo,bar,baz'

cycle(integer $n): Collection

コレクションのすべての要素が$nで指定された回数だけ繰り返されたコレクションを新しく返します。 $nが与えられなかった場合は繰り返しを無限に続けます。

Collection::from([1, 2])->cycle(2);
// => [1, 2, 1, 2]

Collection::from([1, 2, 3])->cycle()->take(5)->toList();
// => [1, 2, 3, 1, 2]

reverse(): Collection

要素の順序を逆順にしたコレクションを返します。

Collection::from([1, 2, 3])->reverse();
// => [3, 2, 1]

sort([ callable $compare ]): Collection

コレクションの要素を昇順にソートします。 比較関数$compareが与えられた場合はそれで比較されたソート結果を返します。

Collection::from([2, 3, 1])->sort();
// => [1, 2, 3]

Collection::from([2, 3, 1])->sort(function($x, $y) {
    if ($x === $y) return 0;
    return $x < $y ? 1 : -1;
});
// => [3, 2, 1]

concatWith(mixed[] ...$xss): Collection

Collection::concat()のインスタンスメソッド版です。

引数で指定された複数の要素の一覧を結合して1つのコレクションにします。

Collection::from([1, 2, 3])->concatWith([4, 5, 6])
// => [1, 2, 3, 4, 5, 6]

keys(): Collection

コレクションの要素のキーをすべて取得します。

Collection::from(['one' => 1, 'two' => 2, 'three' => 3])->keys();
// => ["one", "two", "three"]

values(): Collection

コレクションの要素の値をすべて取得します。

Collection::from(['one' => 1, 'two' => 2, 'three' => 3])->values();
// => [1, 2, 3]

pairs(): Collection

コレクションの各要素をキーと値のペアにして返します。

Collection::from(['one' => 1, 'two' => 2, 'three' => 3])->pairs();
// => [["one", 1], ["two", 2], ["three", 3]]

invert(): Collection

コレクションのキーと値を入れ替えます。 キーが重複した場合は前のものを上書きします。

Collection::from(["Moe" => "Moses", "Larry" => "Louis", "Curly" => "Jerome"])->invert();
// => ["Moses" => "Moe", "Louis" => "Larry", 'Jerome' => "Curly"];

extend(mixed[] ...$sources): Collection

コレクションを$sourcesで拡張します。 同名のキーが存在した場合は上書されます。

Collection::from(['name' => 'moe'])->extend(['age' => 50]);
// => ['name' => 'moe', 'age' => 50]

pick(string[]|string ...$keys): Collection

コレクションの要素の中から$keysで指定されたキーの値を取り出します。

Collection::from(['name' => 'moe', 'age' => 50, 'userid' => 'moe1'])->pick('name', 'age');
// => ['name' => 'moe', 'age' => 50]

omit(string[]|string ...$keys): Collection

コレクションの要素の中から$keysで指定されたキーの以外の値を取り出します。

Collection::from(['name' => 'moe', 'age' => 50, 'userid' => 'moe1'])->omit('userid');
// => ['name' => 'moe', 'age' => 50]

defaults(array ...$defaults): Collection

コレクションに存在しないキーの値を$defaultsから補完します。 isset()でキーの存在を確認しているのでnullは存在しないものとして扱われます。

$iceCream = ['flavor' => 'chocolate'];
Collection::from($iceCream)->defaults(['flavor' => 'vanilla', 'sprinkles' => 'lots']);
// => ["flavor" => "chocolate", "sprinkles" => "lots"]

isEmpty(): boolean

コレクションが空かどうかを判定します。

Collection::from([1, 2, 3])->isEmpty();
// => false

Collection::from(new EmptyIterator())->isEmpty();
// => true