array_map()‎

(PHP 4 >= 4.0.6, PHP 5, PHP 7)

تنفذ الدالة array_map()‎ دالةً أخرى يحددها المستخدم على كل عنصر موجود في المصفوفات المُمرََرَة.

الوصف

array array_map ( callable $callback , array $array1 [, array $... ] )

تعيد الدالة كل عناصر المصفوفة array1 بعد تنفيذ الدالة callback على كل عنصر من عناصرها. يجب أن يساوي عدد المعاملات التي تقبلها الدالة callback عدد المصفوفات المُمَرََرَة إلى الدالة array_map()‎.

المعاملات

callback

mixed callback (mixed $parameter1 [, mixed $...])

دالة يحددها المستخدم لتنفيذها على كل عنصر بالمصفوفة.

array1

مصفوفة تحتوي على العناصر التي ستمر الدالة عليها.

…

قائمة متغيرة من المصفوفات المُمرََرَة إلى الدالة.

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

تعيد الدالة مصفوفةً تحتوي على كل عناصر المصفوفة array1 بعد تنفيذ الدالة callback على كلٍ منها.

أمثلة

المثال 1: مثال بسيط عن استخدام الدالة array_map()‎

<?php
function cube($n)
{
    return($n * $n * $n);
}

$a = array(1, 2, 3, 4, 5);
$b = array_map("cube", $a);
print_r($b);
?>

هذا يجعل قيمة المتغير ‎$b:

Array
(
    [0] => 1
    [1] => 8
    [2] => 27
    [3] => 64
    [4] => 125
)

المثال 2: استخدام الدوال المجهولة (بدءًا من PHP 5.3.0)

<?php
$func = function($value) {
    return $value * 2;
};

print_r(array_map($func, range(1, 5)));
?>

ناتج المثال السابق:

Array
(
    [0] => 2
    [1] => 4
    [2] => 6
    [3] => 8
    [4] => 10
)

المثال 3: استخدام أكثر من مصفوفة

<?php
function show_Spanish($n, $m)
{
    return("The number $n is called $m in Spanish");
}

function map_Spanish($n, $m)
{
    return(array($n => $m));
}

$a = array(1, 2, 3, 4, 5);
$b = array("uno", "dos", "tres", "cuatro", "cinco");

$c = array_map("show_Spanish", $a, $b);
print_r($c);

$d = array_map("map_Spanish", $a , $b);
print_r($d);
?>

نتيجة المثال السابق:

// printout of $c
Array
(
    [0] => The number 1 is called uno in Spanish
    [1] => The number 2 is called dos in Spanish
    [2] => The number 3 is called tres in Spanish
    [3] => The number 4 is called cuatro in Spanish
    [4] => The number 5 is called cinco in Spanish
)

// printout of $d
Array
(
    [0] => Array
        (
            [1] => uno
        )

    [1] => Array
        (
            [2] => dos
        )

    [2] => Array
        (
            [3] => tres
        )

    [3] => Array
        (
            [4] => cuatro
        )

    [4] => Array
        (
            [5] => cinco
        )

)

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

توفر هذه الخاصية ميزة إنشاء مصفوفة من المصفوفات عن طريق تمرير NULL كقيمة للمعامل callback.

المثال 4: إنشاء مصفوفة من المصفوفات

<?php
$a = array(1, 2, 3, 4, 5);
$b = array("one", "two", "three", "four", "five");
$c = array("uno", "dos", "tres", "cuatro", "cinco");

$d = array_map(null, $a, $b, $c);
print_r($d);
?>

نتيجة المثال السابق:

Array
(
    [0] => Array
        (
            [0] => 1
            [1] => one
            [2] => uno
        )

    [1] => Array
        (
            [0] => 2
            [1] => two
            [2] => dos
        )

    [2] => Array
        (
            [0] => 3
            [1] => three
            [2] => tres
        )

    [3] => Array
        (
            [0] => 4
            [1] => four
            [2] => cuatro
        )

    [4] => Array
        (
            [0] => 5
            [1] => five
            [2] => cinco
        )

)

تحافظ المصفوفة المعادة على المفاتيح المرتبطة بالقيم إذا وفقط إذا كان عدد المصفوفات الممررة إلى الدالة مساويًا للواحد. فيما عدا ذلك، المصفوفة المعادة ستحتوي على متوالية من الأعداد الصحيحة كمفاتيح.

المثال 5: استخدام مفاتيح نصية:

<?php
$arr = array("stringkey" => "value");
function cb1($a) {
    return array ($a);
}
function cb2($a, $b) {
    return array ($a, $b);
}
var_dump(array_map("cb1", $arr));
var_dump(array_map("cb2", $arr, $arr));
var_dump(array_map(null,  $arr));
var_dump(array_map(null, $arr, $arr));
?>

نتيجة المثال السابق:

array(1) {
  ["stringkey"]=>
  array(1) {
    [0]=>
    string(5) "value"
  }
}
array(1) {
  [0]=>
  array(2) {
    [0]=>
    string(5) "value"
    [1]=>
    string(5) "value"
  }
}
array(1) {
  ["stringkey"]=>
  string(5) "value"
}
array(1) {
  [0]=>
  array(2) {
    [0]=>
    string(5) "value"
    [1]=>
    string(5) "value"
  }
}

انظر أيضًا

• الدالة array_filter()‎: ترشِّح عناصر المصفوفة باستخدام دالة يحددها المستخدم.
• الدالة array_map()‎: تنفِّذ الدالة التي يحددها المستخدم على كل عنصر من عناصر المصفوفة.
• الدالة array_reduce()‎: تختزل المصفوفة إلى قيمة واحدة باستخدام دالة يحددها المستخدم.
• الدالة array_walk()‎: تطبِّق الدالة على كل عنصر من المصفوفة.
• معلومات عن نوع الدالة callback.

مصادر

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