عرض مصدر jQuery/jQuery/grep

<noinclude>{{DISPLAYTITLE:التابع <code>‎‎jQuery.grep()‎</code>‎ في jQuery}}</noinclude>
== <code>jQuery.grep( array, function [, invert ] )‎</code> ==

=== القيم المعادة ===
يعيد مصفوفةً من النوع [[JavaScript/Array|Array]].

=== الوصف ===
يبحث هذا التابع عن عناصر مصفوفة تتطابق مع الدالة المرشِّحة المعطاة ثمَّ يعيد هذه العناصر بطريقة لا تتأثر فيها المصفوفة الأصليَّة.

=== <code>jQuery.grep( array, function [, invert ] )‎</code> ===
أُضيفت مع الإصدار: 1.0.

==== <code>array</code> ====
كائنٌ شبيهٌ بمصفوفة (array-like object) يراد البحث ضمنه.

==== <code>function</code> ====
دالةٌ من الشكل <code>[[JavaScript/Function|Function]]( [[JavaScript/Object|Object]] elementOfArray, [[JavaScript/Number|Number]] indexInArray )‎</code> تعالج كل عنصر من عناصر الوسيط <code>array</code> المعطى. الوسيط الأول الممرَّر إلى هذه الدالة هو العنصر المراد معالجته، والوسيط الثاني هو فهرس هذا العنصر، ويجب أن تعيد قيمة منطقيَّة. يشير <code>this</code> ضمن الدالة إلى الكائن <code>window</code> العام.

==== <code>invert</code> ====
[[JavaScript/Boolean|قيمة منطقيَّة]] (Boolean). إن كانت <code>false</code> أو لم تعطَ مطلقًا، فستعاد مصفوفةً تحتوي على جميع العناصر التي أعادت الدالة <code>function</code> القيمة <code>true</code> لها. أمَّا إن كانت قيمة هذا الوسيط <code>true</code>، فستعاد مصفوفةً تحتوي على جميع العناصر التي أعادت الدالة <code>function</code> القيمة <code>false</code> لها.

تنتقي الدالة ‎<code>$.grep()‎</code> جميع العناصر التي تجتاز اختبارًا محدَّدًا من المصفوفة المعطاة. هذا الاختبار هو دالةٌ يمرَّر إليها العنصر الحالي من عناصر المصفوفة وفهرس موقعه ضمن تلك المصفوفة؛ وإن كانت نتيجة الاختبار الذي يخضع له العنصر آنذاك <code>true</code>، فسيدرج هذا العنصر ضمن المصفوفة الناتجة (يمكن انتقاء العناصر التي تحصل على النتيجة <code>false</code> عند خضوعها للاختبار مع تمرير القيمة <code>false</code> للوسيط <code>invert</code>).

=== أمثلة ===
ترشيح عناصر مصفوفة تحتوي على أعدادٍ بإبقاء الأعداد التي لا تساوي 5 وقيمة فهرسها أكبر من 4 ثمَّ إزالة العناصر التي قيمتها 9:<syntaxhighlight lang="html">
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>jQuery.grep مثالٌ عن استعمال التابع</title>
  <style>
  div {
    color: blue;
  }
  p {
    color: green;
    margin: 0;
  }
  span {
    color: red;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<div></div>
<p></p>
<span></span>
 
<script>
var arr = [ 1, 9, 3, 8, 6, 1, 5, 9, 4, 7, 3, 8, 6, 9, 1 ];
$( "div" ).text( arr.join( ", " ) );
 
arr = jQuery.grep(arr, function( n, i ) {
  return ( n !== 5 && i > 4 );
});
$( "p" ).text( arr.join( ", " ) );
 
arr = jQuery.grep(arr, function( a ) {
  return a !== 9;
});
 
$( "span" ).text( arr.join( ", " ) );
</script>
 
</body>
</html>

</syntaxhighlight>نتيجة تنفيذ المثال السابق هي:<syntaxhighlight lang="text">
1, 9, 3, 8, 6, 1, 5, 9, 4, 7, 3, 8, 6, 9, 1
1, 9, 4, 7, 3, 8, 6, 9, 1
1, 4, 7, 3, 8, 6, 1

</syntaxhighlight>ترشيح عناصر مصفوفة تحتوي على أعدادٍ عبر ترك العناصر التي قيمتها أكبر تمامًا من الصفر:<syntaxhighlight lang="javascript">
$.grep( [ 0, 1, 2 ], function( n, i ) {
 return n > 0;
});


</syntaxhighlight>سنحصل عند تنفيذ هذه الشيفرة على النتيجة التالية:<syntaxhighlight lang="text">
[ 1, 2 ]
</syntaxhighlight>ترشيح عناصر مصفوفة تحتوي على أعدادٍ عبر ترك العناصر التي قيمتها أصغر أو تساوي الصفر:<syntaxhighlight lang="javascript">
$.grep( [ 0, 1, 2 ], function( n, i ) {
   return n < 0;
}, true );


</syntaxhighlight>سنحصل عند تنفيذ هذه الشيفرة على النتيجة التالية:<syntaxhighlight lang="text">
[ 0 ]
</syntaxhighlight>

== مصادر ==
* [http://api.jquery.com/jQuery.grep/ صفحة التابع ()jQuery.grep في توثيق jQuery الرسمي.]
[[تصنيف:jQuery]]
[[تصنيف:jQuery Method]]
[[تصنيف:jQuery Utilities]]