Array.prototype.find()‎

الدالة Array.prototype.find()‎ تُعيد قيمة أوّل عنصر في المصفوفة الذي يُطابِق الشرط الموجود في دالة الاختبار؛ وإلا ستُعاد القيمة undefined.

function isBigEnough(element) {
  return element >= 15;
}

[12, 5, 8, 130, 44].find(isBigEnough); // 130

انظر أيضًا إلى صفحة الدالة findIndex()‎ التي تُعيد فهرس العنصر الذي عُثِر عليه في المصفوفة بدلًا من قيمته؛ أما إذا أردتَ معرفة موضع عنصر مُحدَّد فانظر إلى الدالة indexOf()‎، وإذا شئت تحديد إن كان العنصر موجودًا ضمن المصفوفة فاستعمل الدالة includes()‎.

البنية العامة

arr.find(callback[, thisArg])

callback

الدالة التي ستختبر كل عنصر من عناصر المصفوفة، وتقبل ثلاثة وسائط.

currentValue

العنصر الحالي الذي يُعالِج في المصفوفة، وهذه القيمة مطلوبة.

index

فهرس العنصر الحالي في المصفوفة، وهذه القيمة اختيارية.

array

المصفوفة التي استدعيت الدالة find عليها، وهذه القيمة اختيارية.

thisArg

القيمة التي ستُستخدَم في this عند استدعاء الدالة callback، وهي قيمة اختيارية.

القيمة المعادة

أوّل قيمة تجتاز دالة الاختبار في المصفوفة، وإن لم تكن موجودةً فستُعاد القيمة undefined.

الوصف

الدالة find تُنفِّذ الدالة callback في كل عنصر موجود في المصفوفة حتى تجد عنصرًا يُعيد القيمة true من الدالة callback، فعند وجود ذلك العنصر فستُعيد الدالة find قيمة ذاك العنصر؛ وإذا لم يُعثر على ذاك العنصر، فستُعيد الدالة find القيمة undefined. لاحظ أنَّ الدالة callback ستُستدعى على الفهارس من 0 إلى length -1 وليس على الفهارس لها قيمٌ مسندةٌ إليها، وهذا يعني أنَّ هذه الدالة أقل كفاءةً من الدوال الأخرى التي لا تختبر إلا الفهارس المرتبطة بقيم.

ستستدعى الدالة callback مع تمرير ثلاثة وسائط إليها: قيمة العنصر، وفهرسه، وكائن المصفوفة التي ستُختَبر عناصرها.

إذا وفّرنا المعامل thisArg إلى الدالة find، فسيستخدم كقيمة this داخل الدالة callback، وإن لم نُحدِّد له قيمةً فستستعمل القيمة undefined.

لاحظ أنَّ الدالة find لا تغيّر المصفوفة التي تستدعى عليها بأيّ شكلٍ من الأشكال.

أمثلة

العثور على كائن في مصفوفة باختبار إحدى خاصياته

var inventory = [
    {name: 'apples', quantity: 2},
    {name: 'bananas', quantity: 0},
    {name: 'cherries', quantity: 5}
];

function isCherries(fruit) { 
    return fruit.name === 'cherries';
}

console.log(inventory.find(isCherries)); 
// { name: 'cherries', quantity: 5 }

العثور على عدد أوليّ في مصفوفة

function isPrime(element, index, array) {
  var start = 2;
  while (start <= Math.sqrt(element)) {
    if (element % start++ < 1) {
      return false;
    }
  }
  return element > 1;
}

console.log([4, 6, 8, 12].find(isPrime)); // undefined, not found
console.log([4, 5, 8, 12].find(isPrime)); // 5

العناصر المحذوفة أو غير الموجودة

المثال الآتي يوضِّح كيف أنَّ الدالة callback ستُستدعى على جميع الفهارس، حتى تلك المرتبطة بعناصر قد حُذِفَت:

var a = [0,1,,,,5,6];

// إظهار جميع الفهارس، وليس الفهارس المرتبطة بعناصر فقط
a.find(function(value, index) {
  console.log('Visited index ' + index + ' with value ' + value); 
});

// إظهار جميع الفهارس، بما في ذلك المحذوفة
a.find(function(value, index) {

  // حذف العنصر 5 في أوّل استدعاء للدالة
  if (index == 0) {
    console.log('Deleting a[5] with value ' + a[5]);
    delete a[5];
  }
  // العنصر 5 ما يزال موجودًا حتى بعد الحذف
  console.log('Visited index ' + index + ' with value ' + value); 
});

تعويض نقص دعم المتصفحات

أضيفت هذه الدالة في معيار ECMAScript 2015 (أي ES6)، لذا يمكنك استخدام الشيفرة الآتية لإضافتها للمتصفحات التي لا تدعمها:

// https://tc39.github.io/ecma262/#sec-array.prototype.find
if (!Array.prototype.find) {
  Object.defineProperty(Array.prototype, 'find', {
    value: function(predicate) {
     // 1. Let O be ? ToObject(this value).
      if (this == null) {
        throw new TypeError('"this" is null or not defined');
      }

      var o = Object(this);

      // 2. Let len be ? ToLength(? Get(O, "length")).
      var len = o.length >>> 0;

      // 3. If IsCallable(predicate) is false, throw a TypeError exception.
      if (typeof predicate !== 'function') {
        throw new TypeError('predicate must be a function');
      }

      // 4. If thisArg was supplied, let T be thisArg; else let T be undefined.
      var thisArg = arguments[1];

      // 5. Let k be 0.
      var k = 0;

      // 6. Repeat, while k < len
      while (k < len) {
        // a. Let Pk be ! ToString(k).
        // b. Let kValue be ? Get(O, Pk).
        // c. Let testResult be ToBoolean(? Call(predicate, T, « kValue, k, O »)).
        // d. If testResult is true, return kValue.
        var kValue = o[k];
        if (predicate.call(thisArg, kValue, k, o)) {
          return kValue;
        }
        // e. Increase k by 1.
        k++;
      }

      // 7. Return undefined.
      return undefined;
    }
  });
}

دعم المتصفحات

الميزة	Chrome	Firefox	Internet Explorer	Opera	Safari
الدعم الأساسي	45	25	غير مدعومة	32	8

على النقيض من متصفح IE، يدعم Edge هذه الميزة.

مصادر ومواصفات

• مسودة المعيار ECMAScript Latest Draft.
• معيار ECMAScript 2015 (6th Edition)‎.