Array.prototype.filter()

概要

引数として与えられたテスト関数を各配列要素に対して実行し、それに合格したすべての配列要素からなる新しい配列を生成します。

構文

var filteredArray = array.filter(callback[, thisObject]);

引数

callback

配列の各要素に対して実行するテスト関数。

thisObject

callback を実行するときに this として使用するオブジェクト。

説明

filter は、与えられた callback 関数を配列の各要素に対して一度ずつ呼び出し、callback が真の値を返したすべての値からなる新しい配列を生成します。callback は値が代入されている配列のインデックスに対してのみ呼び出されます。つまり、すでに削除されたインデックスや、まだ値が代入されていないインデックスに対しては呼び出されません。callback によるテストに合格しなかった配列要素は単純にスキップされ、新しい配列には含まれません。

callback は、要素の値、要素のインデックス、走査されている Array オブジェクトという 3 つの引数をともなって呼び出されます。

filter に thisObject パラメータが与えられると、callback の呼び出しのたびにそのオブジェクトが this として使用されます。thisObject が与えられないか null の場合は、callback に結び付けられたグローバルオブジェクトが代わりに使用されます。

filter は呼び出された配列を変化させません。

filter によって処理される配列要素の範囲は、callback が最初に呼び出される前に設定されます。filter の呼び出しが開始された後に追加された配列要素に対しては、callback は実行されません。既存の配列要素が変更または削除された場合、callback に渡される値は filter がそれらを参照した時点での値になります。削除された配列要素を参照することはありません。

互換性

filter は ECMA-262 標準に対する JavaScript の拡張であり、ECMA-262 標準の他の実装では存在しない場合があります。次のコードをスクリプトの先頭に挿入すると、filter がネイティブでサポートされていない ECMA-262 実装でも filter を使用できるようになります。このアルゴリズムは ECMA-262 第 5 版で指定されたアルゴリズムと全く同じものです。Object と TypeError はそれぞれオリジナルの値を持ち、それらの fun.call は Function.prototype.call のオリジナルの値として評価され、またそれらの Array.prototype.push はオリジナルの値を持ちます。

if (!Array.prototype.filter) {
  Array.prototype.filter = function(fun /*, thisp */) {
    "use strict";

    if (this == null) throw new TypeError();

    var t = Object(this),
        len = t.length >>> 0;

    if (typeof fun != "function") throw new TypeError();

    var res = [],
        thisp = arguments[1];

    for (var i = 0; i < len; i++) {
      if (i in t) {
        var val = t[i]; // fun が this を変化させた場合に備えて
        if (fun.call(thisp, val, i, t)) res.push(val);
      }
    }

    return res;
  };
}

例

例: 小さい値をすべて取り除く

次の例では、filter を使って 10 よりも小さい値を持つ要素をすべて取り除いた配列を生成します。

function isBigEnough(element, index, array) {
  return (element >= 10);
}
var filtered = [12, 5, 8, 130, 44].filter(isBigEnough);
// filtered は [12, 130, 44] となる（10未満の配列要素が取り除かれている） 

ブラウザ実装状況

Kangax's compat tables に基づく。