PHP/array walk

(PHP 4, PHP 5, PHP 7)

تُطبّق الدالة array_walk()‎ الدالة المُقدمة من المستخدم على كل عنصر في المصفوفة.

الوصف

bool array_walk ( array &$array , callable $callback [, mixed $userdata = NULL ] )

تُطبّق الدالة array_walk()‎ الدالة callback المعرفة بواسطة المستخدم على كل عنصر من المصفوفة array.

ولا تتأثر الدالة array_walk()‎ بالمؤشر الداخلي للمصفوفة array. وسوف تُطبّق الدالة array_walk()‎ على المصفوفة بأكملها بغض النظر عن موضع المؤشر (pointer location).

المعاملات

array

المصفوفة المدخلة.

callback

تأخذ عادةً الدالة callback المُعرّفة من المستخدم معامليْن. الأول قيمة معامل المصفوفة array، والثاني المفتاح أو الفهرس.

ملاحظة:

إذا لزم أن تعمل الدالة callback مع القيم الفعلية للمصفوفة، فيجب تعيين أول معامل للدالة callback كمرجع. بعد ذلك، تُجرى أي تغييرات على هذه العناصر في المصفوفة الأصلية نفسها.

ملاحظة: تطلق العديد من الدوال الداخلية (على سبيل المثال strtolower()‎) تحذيرًا إذا مُرِّرَ عدد أكبر من العدد المتوقع من الوسائط والتي لا يمكن استخدامها مباشرة كدوال callback.

من المحتمل أن تتغير قيم array فقط؛ ولكن لا يمكن تغيير هيكلها، أي أن المبرمج لا يمكنه إضافة عناصر أو إلغاء تعيينها أو إعادة ترتيبها. وإذا لم تحترم دوال رد النداء callback هذا الشرط، فإن سلوك هذه الدالة سيكون غير محدد وغير قابل للتنبؤ.

userdata

إذا توافر المعامل userdata الاختياري، فسيمرر كمعامل ثالث إلى callback.

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

تُعيد الدالة array_walk()‎ القيمة TRUE عند نجاح عملها أو FALSE عند فشل تنفيذها.

الأخطاء والاستثناءات

بدءًا من PHP 7.1.0، سيُطلَق الخطأ ArgumentCountError إذا كانت دالة رد النداء callback تتطلب أكثر من معاملَيْن (القيمة والمفتاح لعنصر المصفوفة). في السابق، إذا تتطلبت دالة رد النداء callback أكثر من معاملَيْن، فسيتولد خطأٌ من المستوى E_WARNING في كل مرة تستدعي فيها الدالةُ array_walk()‎ الدالةَ callback.

أمثلة

المثال 1: مثال على الدالة array_walk()‎

<?php
$fruits = array("d" => "lemon", "a" => "orange", "b" => "banana", "c" => "apple");

function test_alter(&$item1, $key, $prefix)
{
    $item1 = "$prefix: $item1";
}

function test_print($item2, $key)
{
    echo "$key. $item2<br />\n";
}

echo "Before ...:\n";
array_walk($fruits, 'test_print');

array_walk($fruits, 'test_alter', 'fruit');
echo "... and after:\n";

array_walk($fruits, 'test_print');
?>

سوف تكون مُخرجات المثال أعلاه كالتالي:

Before ...:
d. lemon
a. orange
b. banana
c. apple
... and after:
d. fruit: lemon
a. fruit: orange
b. fruit: banana
c. fruit: apple

أنظر أيضًا

• الدالة ()‎array_walk_recursive: تطبيق دالة مستخدم تكراريًا على كل عنصر في المصفوفة.
• iterator_apply()‎: استدعاء دالة لكل عنصر في مُكرِّر.
• list()‎: تعيين المتغيرات كما لو كانت مصفوفة.
• each()‎: إعادة كل من المفتاح والقيمة المقابلة الحاليين من المصفوفة وتحريك مؤشرها.
• call_user_func_array()‎: استدعاء دالة callback مع مصفوفة من المعاملات.
• array_map()‎: تطبيق دالة callback على عناصر المصفوفات المٌدخلة.
• معلومات حول النوع callback.
• حلقة foreach

مصادر

• صفحة الدالة array_walk في توثيق PHP الرسمي.