Introduction

Underbar.phpUnderscore.jsライクなコレクション処理のためのPHPのライブラリです。 Underscore.jsとの大きな違いとしてIteratorを利用した遅延リストが生成できる点が上げられます。

Features

Example

以下は配列の要素を2倍にして新しい配列を返す例です。

use Underbar\ArrayImpl as _;  // 配列を返す実装

$xs = _::map([1, 2, 3, 4], function($n) { return $n * 2; });
var_dump(is_array($xs));  // true
var_dump($xs);  // [2, 4, 6, 8]

これをIteratorを返す実装に切り替えてみます。 Iteratorは実際に要素を走査するまで計算が遅延されるので、空間効率で有利な場合があります。

use Underbar\IteratorImpl as _;  // Iterator implement class

$xs = _::map([1, 2, 3, 4], function($n) { return $n * 2; });
var_dump($xs instanceof Traversable);  // true
var_dump(iterator_to_array($xs));  // [2, 4, 6, 8]

メソッドチェインで処理を書くにはchain()を利用します。

use Underbar\IteratorImpl as _;

// Fibonacci sequence
echo _::chain([1, 1])
    ->iterate(function($pair) { return [$pair[1], _::sum($pair)]; })
    ->map(function($pair) { return $pair[0]; })
    ->take(10)
    ->join();  // 1,1,2,3,5,8,13,21,34,55

TOP

Getting Started

Underbar.phpの動作にはバージョン5.4以上のPHP処理系と、Composerが必要です。 インストールが完了したらプロジェクトルートに以下のような内容のcomposer.jsonを作成して下さい。 詳しいcomposer.jsonの書き方についてはこちらを参照して下さい。

{
    "require": {
        "emonkak/underbar.php": "dev-master"
    }
}

composer.jsonを作成したら同じディレクトリで

$ php composer.phar install

を実行するとUnderbar.phpのインストールは完了です。

TOP

Classes

Underbar Namespace

AbstractImpl ClassSource

Underbar.phpの各実装での共通の手続きが定義された抽象クラスです。 すべての手続きはstaticメソッドとして定義されています。 このクラスを直接扱うことはありません。

TOP

ArrayImpl ClassSource

  1. AbstractImpl
  2. ArrayImpl

配列を返す実装を提供するクラスです。

TOP

GeneratorImpl ClassSource

  1. AbstractImpl
  2. GeneratorImpl

Generatorを返す実装を提供するクラスです。 GeneratorIteratorよりも高速に動作しますが、走査を繰り返すと例外が発生することに注意して下さい。

use Underbar\GeneratorImpl as _;

$xs = _::range(10);
foreach ($xs as $x);
// 'Exception' with message 'Cannot traverse an already closed generator'
foreach ($xs as $x);

TOP

Enumerable TraitSource

Underbar.phpの手続きをmixinするためのトレイトです。 このトレイトのソースはスクリプトによって自動生成されています。

利用する際は対象のクラスに以下の抽象メソッドを実装する必要があります。

Method Description
string getUndebarImpl() Underbar.phpの実装クラスを取得する
value value() Underbar.phpの手続きに与える値を返す

Version 0.2.0からchain()がこのトレイトに依存するようになりました。

class Collection implements IteratorAggregate
{
    use Underbar\Enumerable;

    protected $array;

    public function __construct()
    {
        $this->array = func_get_args();
    }

    public function getIterator()
    {
        return new ArrayIterator($this->array);
    }

    public function getUndebarImpl()
    {
        return 'Underbar\\IteratorImpl';
    }

    public function value()
    {
        return $this->array;
    }
}

$collection = new Collection(1, 2, 3, 4, 5);
$collection
    ->filter(function($n) { return $n % 2 === 0; })
    ->map(function($n) { return $n * 2; })
    ->toList();
=> [4, 8]

$collection = new Collection(1, 2, 3);
$collection
    ->cycle()
    ->map(function($n) { return $n * 2; })
    ->take(6)
    ->join(', ');
=> '2, 4, 6, 2, 4, 6'

TOP

Functions

ArrayImplIteratorImplGeneratorImplで利用可能な関数の一覧です。

Collection Functions

array each(array|Traversable $xs, callable $f)

Iterator each(array|Traversable $xs, callable $f)

$xsの各要素に対して関数$fを呼び出して$xsをそのまま返します。 $f(element, key, array)の3つの引数を取ります。

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

TOP

array map(array|Traversable $xs, callable $f)

Iterator map(array|Traversable $xs, callable $f)

$xsの各要素に対して関数$fを適用します。 $f(element, key, array)の3つの引数を取ります。

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

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

TOP

mixed reduce(array|Traversable $xs, callable $f, mixed $acc)

  • inject()
  • foldl()

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

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

TOP

mixed reduceRight(array|Traversable $xs, callable $f, mixed $acc)

  • foldr()

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

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

TOP

mixed find(array|Traversable $xs, callable $f)

  • detect()

$xsの要素の中から$fが最初にtrueを返す要素を返します。 見付からなかった場合はnullを返します。

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

TOP

array filter(array|Traversable $xs, callable $f)

Iterator filter(array|Traversable $xs, callable $f)

  • select()

$xsの要素について$ftrueを返すものを選択します。 逆の操作を行なう関数としてreject()があります。

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

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

TOP

array where(array|Traversable $xs, array $properties)

Iterator where(array|Traversable $xs, array $properties)

$xsの要素から$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]
];
_::where($members, ['age' => 24]);
=> [["name" => "Yuka Iguchi", "age" => 24],
    ["name" => "Kana Hanazawa", "age" => 24]]

TOP

mixed findWhere(array|Traversable $xs, array $properties)

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

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

TOP

array reject(array|Traversable $xs, callable $f)

Iterator reject(array|Traversable $xs, callable $f)

$xsの要素について$ftrueを返すものを除外します。 逆の操作を行う関数としてfilter()があります。

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

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

TOP

boolean every(array|Traversable $xs [, callable|string $f])

  • all()

$xsの要素がすべてtrueとして評価される値であればtrueを返します。

_::every([true, 1, null, 'yes']);
=> false

TOP

boolean some(array|Traversable $xs, [callable|string $f])

  • any()

$xsの要素の中にtrueとして評価される値が1つでもあればtrueを返します。

_::some([true, 1, null, 'yes']);
=> true

TOP

boolean contains(array|Traversable $xs, mixed $target)

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

_::contains([1, 2, 3], 3);
=> true

TOP

array invoke(array|Traversable $xs, string $method [, mixed $argments...])

Iterator invoke(array|Traversable $xs, string $method [, mixed $argments...])

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

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

TOP

array pluck(array|Traversable $xs, string $property)

Iterator pluck(array|Traversable $xs, string $property)

$xsの要素の中から指定した$propertyの値を抽出します。

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

TOP

int max(array|Traversable $xs)

mixed max(array|Traversable $xs, callable|string $f)

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

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

TOP

int min(array|Traversable $xs)

mixed min(array|Traversable $xs, callable|string $f)

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

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

TOP

int sum(array|Traversable $xs)

$xsの要素の合計を返します。

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

TOP

int product(array|Traversable $xs)

$xsの要素の積を返します。

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

TOP

float average(array|Traversable $xs)

$xsの要素を数値と見なして平均を求めます。

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

TOP

array sortBy(array|Traversable $xs [, callable|string $f])

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

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

TOP

array groupBy(array|Traversable $xs [, callable|string $f])

Iterator groupBy(array|Traversable $xs [, callable|string $f])

$xsの要素を$fを呼び出した結果を基準にグループ化します。 $fに文字列を指定した場合は該当するプロパティを基準にします。

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

TOP

array indexBy(array|Traversable $xs [, callable|string $f])

Iterator indexBy(array|Traversable $xs, callable|string $f)

$xsの要素を$fを呼び出した結果をキーとした新しい配列にします。 $fに文字列を指定した場合は該当するプロパティを基準にします。

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

TOP

array countBy(array|Traversable $xs, callable|string $f)

Iterator countBy(array|Traversable $xs, callable|string $f)

$xsの要素を$fを呼び出した結果を基準にカウントします。 $fに文字列を指定した場合は該当するプロパティを基準にします。

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

TOP

array shuffle(array|Traversable $xs)

Iterator shuffle(array|Traversable $xs)

$xsの要素をシャッフルします。 内部で組込みのshuffle()を利用しています。

_::shuffle([1, 2, 3, 4, 5, 6]);
=> [4, 1, 6, 3, 5, 2]

TOP

mixed sample(array|Traversable $xs)

Iterator sample(array|Traversable $xs, mixed $n)

$xsの要素をシャッフルします。 内部で組込みのshuffle()を利用しています。

_::shuffle([1, 2, 3, 4, 5, 6]);
=> [4, 1, 6, 3, 5, 2]

TOP

array memoize(Iterator $xs)

Iterator memoize(Iterator $xs)

$xsを一度計算した要素をキャッシュするMemoizeIteratorでラップします。

$fibs = _::chain(array(0, 1))
    ->iterate(function($pair) {
        return [$pair[1], $pair[0] + $pair[1]];
    })
    ->map(function($pair) { return $pair[0]; })
    ->memoize()
    ->value();
$fibs[10];
=> 55

TOP

array toArray(mixed $xs)

指定した値をキーを維持したまま連想配列にします。 文字列が与えられた時は文字の配列を返します。

_::toArray(new ArrayObject(['a' => 1, 'b' => 2, 'c' => 3]));
=> ["a" => 1, "b" => 2, "c" => 3]

TOP

array toList(mixed $xs)

指定した値をキーを破棄して連番のインデックスの配列にします。 文字列が与えられた時は文字の配列を返します。

_::toList(new ArrayObject(['a' => 1, 'b' => 2, 'c' => 3]));
=> [1, 2, 3]

TOP

int size(mixed $xs)

配列の場合は要素数を、Iteratorの場合は長さを、文字列の場合は文字数を返します。

_::size(["one" => 1, "two" => 2, "three" => 3]);
=> 3

TOP

Array Functions

mixed first(array|Traversable $xs)

array first(array|Traversable $xs, int $n)

Iterator first(array|Traversable $xs, int $n)

  • head()
  • take()

$xsの最初の要素を返します。 $nを指定した場合は先頭からn個分の要素を含む配列を返します。

_::first([1, 2, 3]);
=> 1
_::first([1, 2, 3], 1);
=> [1]
_::first([1, 2, 3], 2);
=> [1, 2]

TOP

mixed firstOrElse(array|Traversable $xs, mixed $default)

$xsの最初の要素を返します。見付からなかった場合は$defaultを返します。

_::firstOrElse([1, 2, 3], 10);
=> 1

_::firstOrElse([], 10);
=> 10

TOP

array initial(array|Traversable $xs [, int $n = 1])

Iterator initial(array|Traversable $xs [, int $n = 1])

$xsの末尾から$n個の要素を除いた新しい配列を返します。

_::initial([5, 4, 3, 2, 1]);
=> [5, 4, 3, 2]

TOP

mixed last(array|Traversable $xs)

Iterator Iterator(array|Traversable $xs, int $n)

$xsの最後の要素を返します。 $nに2以上の値が指定された時は末尾の$n個の要素を返します。

_::last([5, 4, 3, 2, 1]);
=> 1
_::last([5, 4, 3, 2, 1], 2);
=> [2, 1]

TOP

mixed lastOrElse(array|Traversable $xs, mixed $default)

$xsの最後の要素を返します。見付からなかった場合は$defaultを返します。

_::lastOrElse([1, 2, 3], 10);
=> 3

_::lastOrElse([], 10);
=> 10

TOP

array rest(array|Traversable $xs [, int $n = 1])

Iterator rest(array|Traversable $xs [, int $n = 1])

  • tail()
  • drop()

$xsの先頭から$n個の要素を除いた新しい配列を返します。

_::rest([5, 4, 3, 2, 1]);
=> [4, 3, 2, 1]

TOP

array takeWhile(array|Traversable $xs, callable $f)

Iterator takeWhile(array|Traversable $xs, callable $f)

$fが最初にtrueを返すまでの要素の配列を返します。

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

TOP

array dropWhile(array|Traversable $xs, callable $f)

Iterator dropWhile(array|Traversable $xs, callable $f)

$fが最初にtrueを返すまでの要素を除いた配列を返します。

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

TOP

array compact(array|Traversable $xs)

Iterator compact(array|Traversable $xs)

$xsの要素の中からfalseとして評価される値を除いた新しい配列を返します。

_::compact([0, 1, false, 2, '', 3]);
=> [1, 2, 3]

TOP

array flatten(array|Traversable $xs [, boolean $shallow = false])

Iterator flatten(array|Traversable $xs [, boolean $shallow = false])

ネストした配列を平坦化します。 $shallowtrueの時は1つ分の深さしか平坦化しません。

_::flatten([1, [2], [3, [[4]]]]);
=> [1, 2, 3, 4]

_::flatten([1, [2], [3, [[4]]]], true);
=> [1, 2, 3, [[4]]]

TOP

array without(array|Traversable $xs [, mixed $values...])

Iterator without(array|Traversable $xs [, mixed $values...])

$xsから$valuesの値を除いた配列を返します。

_::without([1, 2, 1, 0, 3, 1, 4], 0, 1);
=> [2, 3, 4]

TOP

array union(array|Traversable $xss...)

Iterator union(array|Traversable $xss...)

引数で指定した配列$xssを結合した上で、値が一意になる配列を返します。 concat()した後にuniq()を呼び出すのと等価です。

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

TOP

array intersection(array|Traversable $xss...)

Iterator intersection(array|Traversable $xss...)

引数で指定した配列すべてに存在する値でのみ構成される配列を新しく返します。

_::intersection([1, 2, 3], [101, 2, 1, 10], [2, 1]);
=> [1, 2]

TOP

array difference(array|Traversable $xs, array $others...)

Iterator difference(array|Traversable $xs, array $others...)

$xsから$othersの配列の要素を取り除いた新しい配列を返します。

_::difference([1, 2, 3, 4, 5], [5, 2, 10]);
=> [1, 3, 4]

TOP

array uniq(array|Traversable $xs [, callable|string $f])

Iterator uniq(array|Traversable $xs [, callable|string $f])

  • unique()

$xsから要素の重複を排除します。 $fに関数が与えられた場合は$fを適用した結果を基準にします。 $fに文字列が与えられた場合は該当するプロパティを基準にします。 比較は===を使って厳密に行われます。

_::uniq([1, 2, 1, 3, 1, 4]);
=> [1, 2, 3, 4]

TOP

array zip(array|Traversable $xss...)

Iterator zip(array|Traversable $xss...)

$xssの各要素のインデックスが対応するもの同士を配列にして返します。

指定した配列の長さが違う場合は小さいものに合わせます。 この挙動はUnderscore.jsとは違いますが、引数に無限リストが含まれている時に計算が終了しなくなるためです。

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

TOP

array zipWith(array|Traversable $xss..., callable $f)

Iterator zipWith(array|Traversable $xss..., callable $f)

zip()した結果に$fを適用させます。

_::zipWith([1, 2, 3], [4, 5, 6], function($x, $y) {
    return $x + $y;
});
=> [5, 7, 9]

TOP

array unzip(array|Traversable $xss)

Iterator unzip(array|Traversable $xss)

動作自体はzip()と同じですが、引数に配列の配列を受けとります。

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

TOP

array object(array|Traversable $xs [, array $values])

Iterator object(array|Traversable $xs [, array $values])

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

_::object(['moe', 'larry', 'curly'], [30, 40, 50]);
=> ["moe" => 30, "larry" => 40, "curly" => 50]

_::object([['moe', 30], ['larry', 40], ['curly', 50]]);
=> ["moe" => 30, "larry" => 40, "curly" => 50]

TOP

int indexOf(array|Traversable $xs, mixed $value [, boolean $isSorted = false])

int indexOf(array|Traversable $xs, mixed $value [, int $fromIndex = 0])

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

ソート済みの配列であれば$isSortedtrueを指定することで、二分探索による効率的な探索を実行できます。

_::indexOf([1, 2, 3], 2);
=> 1

TOP

int lastIndexOf(array|Traversable $xs, mixed $value [, int $fromIndex = 0])

indexOf()の末尾から探索するバージョンです。

_::lastIndexOf([1, 2, 3, 1, 2, 3], 2);
=> 4

TOP

array sortedIndex(array|Traversable $xs, mixed $value [, callable|string $f])

二分探索を実行して$valueの挿入位置を調べます。

_::sortedIndex([10, 20, 30, 40, 50], 35);
=> 3

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

TOP

array cycle(array|Traversable $xs, int, $n)

Iterator cycle(array|Traversable $xs [, int $n])

$xsの要素が$nで指定された回数だけ繰り返された配列を返します。 $nが与えられなかった場合は繰り返しを無限に続けます。 ArrayImplから$nを与えずに呼び出された場合はOverflowExceptionが発生します。

_::cycle([1, 2], 2);
=> [1, 2, 1, 2]

_::chain([1, 2, 3])->cycle()->take(5)->toList();
=> [1, 2, 3, 1, 2]

TOP

array repeat(mixed $value)

Iterator repeat(mixed $value, int, $n)

$value$n個分繰り返される配列を返します。 $nが与えられなかった場合は$valueを無限に繰り返し続けます。 ArrayImplから呼び出された時に$nが与えられなかった場合はOverflowexceptionが発生します。

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

_::chain(1)->repeat()->take(5)->toList()->value();
=> [1, 1, 1, 1, 1]

TOP

Iterator iterate(mixed $acc, callable $f)

$accに対して$fを繰り返し適用していくIteratorを返します。 ArrayImplから呼び出された場合はOverflowExceptionが発生します。

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

TOP

array reverse(array|Traversable $xs)

Iterator reverse(array|Traversable $xs)

$xsの要素の順序を逆順にした配列を返します。

_::reverse([1, 2, 3]);
=> [3, 2, 1]

TOP

array sort(array|Traversable $xs [, callable $compare])

Iterator sort(array|Traversable $xs)

$xsをPHP組み込みのsortを使って要素を昇順にソートします。 比較関数$compareが与えられた場合はusortでソートされます。

_::sort([2, 3, 1]);
=> [1, 2, 3]

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

TOP

array concat(array|Traversable $xs...)

Iterator concat(array|Traversable $xs...)

引数で指定された配列$xsを1つの配列に結合します。

_::concat([1, 2, 3], [4, 5, 6])
=> [1, 2, 3, 4, 5, 6]

TOP

array join(array|Traversable $xs [ , string $separator = ","])

$xsの要素を$separatorを区切文字として文字列に結合します。 PHP組み込みのimplodeと等価な処理です。

_::join(['foo', 'bar', 'baz'], ',')
=> "foo,bar,baz"

TOP

Object Functions

array keys(array|Traversable $xs)

Iterator keys(array|Traversable $xs)

$xsからキーをすべて取得します。

_::keys(['one' => 1, 'two' => 2, 'three' => 3]);
=> ["one", "two", "three"]

TOP

array values(array|Traversable $xs)

Iterator values(array|Traversable $xs)

$xsから値をすべて取得します。

_::values(['one' => 1, 'two' => 2, 'three' => 3]);
=> [1, 2, 3]

TOP

array pairs(array|Traversable $xs)

Iterator pairs(array|Traversable $xs)

$xsの各要素をキーと値のペアの配列にして返します。

_::pairs(['one' => 1, 'two' => 2, 'three' => 3]);
=> [["one", 1], ["two", 2], ["three", 3]]

TOP

array invert(array|Traversable $xs)

$xsのキーと値を入れ替えます。 キーが重複した場合は前のものを上書きします。 組み込みのarray_flip()と等価な操作です。

_::invert(["Moe" => "Moses", "Larry" => "Louis", "Curly" => "Jerome"]);
=> ["Moses" => "Moe", "Louis" => "Larry", 'Jerome' => "Curly"];

TOP

array extend(array|Traversable $destination [, array $sources...])

$destinationを与えられた$sourcesで拡張します。 同名のキーが存在した場合は前のものを上書きします。 組み込みのarray_merge()と等価な操作です。

_::extend(['name' => 'moe'], ['age' => 50]);
=> ['name' => 'moe', 'age' => 50]

TOP

mixed get(array|Traversable $xs, string $key)

$xsからキーが$keyの値を取り出します。 見つからなかった時はnullを返します。 getOrElse($xs, $key, null)と等価な操作です。

_::get(['foo' => 'bar', 'hoge' => 'fuga'], 'foo');
=> "bar"

_::get(['foo' => 'bar', 'hoge' => 'fuga'], 'piyo');
=> null

TOP

mixed getOrElse(array|Traversable $xs, string $key, mixed $default)

$xsからキーが$keyの値を取り出します。 見つからなかった時は$defaultを返します。

_::getOrElse(['foo' => 'bar', 'hoge' => 'fuga'], 'foo', 'payo');
=> "bar"

_::getOrElse(['foo' => 'bar', 'hoge' => 'fuga'], 'piyo', 'payo');
=> "payo"

TOP

array pick(array|Traversable $xs [, array|string $keys...])

Iterator pick(array|Traversable $xs [, array|string $keys...])

$xsの要素の中から$keysで指定されたキーの値を取り出します。

_::pick(['name' => 'moe', 'age' => 50, 'userid' => 'moe1'], 'name', 'age');
=> ['name' => 'moe', 'age' => 50]

TOP

array omit(array|Traversable $xs [, array|string $keys...])

Iterator omit(array|Traversable $xs [, array|string $keys...])

$xsの要素の中から$keysで指定されたキーの以外の値を取り出します。

_::pick(['name' => 'moe', 'age' => 50, 'userid' => 'moe1'], 'userid');
=> ['name' => 'moe', 'age' => 50]

TOP

array defaults(array|Traversable $xs [, array $defaults...])

Iterator defaults(array|Traversable $xs [, array $defaults...])

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

$iceCream = ['flavor' => 'chocolate'];
_::defaults($iceCream, ['flavor' => 'vanilla', 'sprinkles' => 'lots']);
=> ["flavor" => "chocolate", "sprinkles" => "lots"]

TOP

array tap(mixed $value, callable $interceptor)

$valueを引数として$interceptorを呼び出して$valueをそのまま返します。

_::chain([1, 2, 3, 200])
  ->filter(function($num) { return $num % 2 == 0; })
  ->tap(function($num) { var_dump($num); })
  ->map(function($num) { return $num * $num; })
  ->value();
=> // [1 => 2, 3 => 200] (var_dump)
=> [1 => 4, 3 => 40000]

TOP

boolean isEmpty(mixed $xs)

与えられた配列かIteratorIteratorAggregateなどのTraversableなオブジェクトが空かどうかを返します。

_::isEmpty([1, 2, 3]);
=> false
_::isEmpty(new EmptyIterator());
=> true

TOP

Utility Functions

array identity(mixed $value)

与えられた値をそのまま返します。

$moe = ['name' => 'moe'];
$moe === _::identity($moe);
=> true

TOP

array range(int $start, int $end [, int $step = 1])

Iterator range(int $start, int $end [, int $step = 1])

$startから$stepごとにインクリメントされた$endまでの数値の配列を返します。 $stepに負の値を設定するとデクリメントされます。 PHP組込みのrange()とは違って$end自体は含まれません。

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

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

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

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

_::range(0);
=> []

TOP

Parallel Functions

Parallel parMap(array|Traversable $xs, callable $f, int $n = 4)

map()の並列実行版です。 $xsの各要素に対して関数$fを並列に適用した結果を返すParallelオブジェクトを返します。 ParallelクラスはIteratorインターフェイスとCountableインターフェイスを実装しています。

$fは引数(element)を1つだけ取る関数です。 $nは同時に起動するワーカープロセスの数です。 $nが2以上の時は複数のワーカープロセスによって処理されるため、返ってくる要素の順序は不定です。

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

Parallelで利用可能なメソッド
Method Description
void fork() ワーカープロセスを1つ起動させる
void terminate() ワーカープロセスを1つ停止させる
int processes() 現在起動中のワーカープロセスの数を取得する
void push($value) 処理したい値を追加する
void pushAll($values) 処理したい値を複数追加する
mixed result() 処理の結果を1つ取り出す
int count() 未処理のタスクの数を返す
$xs = _::parMap([1, 2, 3], function($x) {
    sleep(2);
    return $x * 3;
});
// 4並列で実行されるので約2秒ですべての計算が終わる
foreach ($xs as $x) {
    var_dump($x);  // 3, 6, 9が順不同に出力される
}

TOP

Chaining

Wrapper chain(mixed $value)

$valueをメソッドチェインで処理するためのWrapperで包んで返します。 WrapperEnumerableをmix-inしたメソッドチェイン用のクラスです。

チェイン中にtoArray()toList()以外のarrayIteratorを返す関数を呼び出した場合は、返り値を新たなWrapperのインスタンスで包んで返します。 それ以外の値を返す関数を呼び出した時は値をそのまま返します。

$stooges = [
    ['name' => 'curly', 'age' => 25],
    ['name' => 'moe', 'age' => 21],
    ['name' => 'larry', 'age' => 23]
];
$youngest = _::chain($stooges)
  ->sortBy(function($stooge){ return $stooge['age']; })
  ->map(function($stooge){ return $stooge['name'] . ' is ' . $stooge['age']; })
  ->first();
=> "moe is 21"

TOP

Change Log

0.3.0 - Sep 7, 2013

Removal

Feature

Fix

0.2.3 - Aug 7, 2013

0.2.2 - Aug 4, 2013

0.2.1 - Aug 3, 2013

0.2.0 - Jul 30, 2013

0.1.2 - Jul 27, 2013

0.1.1 - Jul 25, 2013

0.1.0 - Jul 24, 2013

TOP