الدالة usort()‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎ في PHP

(PHP 4, PHP 5, PHP 7)

تُرتب الدالة usort()‎‎ مصفوفة حسب القيم باستخدام دالة مقارنة معرفة من قبل المستخدم.

الوصف

bool usort ( array &$array , callable $value_compare_func )

تُرتب هذه الدالة مصفوفة حسب القيم باستخدام دالة مقارنة معرفة من قبل المستخدم. ويجب عليك استخدام هذه الدالة إذا كانت المصفوفة التي ترغب في ترتيبها تحتاج إلى الترتيب حسب بعض المعايير غير البسيطة.

ملاحظة: إذا تساوت مقارنة عنصرين، فإن ترتيبهما النسبي في المصفوفة المُرتّبة يكون غير محدد.

ملاحظة: تُعيّن هذه الدالة مفاتيح جديدة للعناصر في المصفوف array. وستزيل أي مفاتيح موجودة قد سبق تعيينها، بدلاً من مجرد إعادة ترتيب المفاتيح.

المعاملات

array

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

value_compare_func

يجب أن تُعيد دالة المقارنة عدد صحيح أقل من أو يساوي أو أكبر من الصفر إذا كان الوسيط الأول يعتبر أقل من أو يساوي أو أكبر من الوسيط الثاني على التوالي. لاحظ أنه قبل PHP 7.0.0 كان يجب أن يكون هذا العدد الصحيح في النطاق من ‎-2147483648 إلى 2147483647.

int callback ( mixed $a, mixed $b )

تنبيه: ستؤدي إعادة قيم غير صحيحة من دالة المقارنة، مثل الأعداد العشرية float، إلى تحويلها داخليًا إلى أعداد صحيحة integer من قيمة رد النداء المعادة. وعلى هذا، ستُحوّل القيم مثل 0.99 و 0.1 إلى قيمة عددية صحيحة تساوي 0، والتي ستُقارن كقيم متساوية.

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

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

أمثلة

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

<?php
function cmp($a, $b)
{
    if ($a == $b) {
        return 0;
    }
    return ($a < $b) ? -1 : 1;
}

$a = array(3, 2, 5, 6, 1);

usort($a, "cmp");

foreach ($a as $key => $value) {
    echo "$key: $value\n";
}
?>

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

0: 1
1: 2
2: 3
3: 5
4: 6

ملاحظة: من الواضح في هذه الحالة البسيطة أن الدالة sort()‎‎ ستكون أكثر ملاءمة. المثال 2: مثال على الدالة usort()‎‎ باستخدام مصفوفة متعددة الأبعاد

<?php
function cmp($a, $b)
{
    return strcmp($a["fruit"], $b["fruit"]);
}

$fruits[0]["fruit"] = "lemons";
$fruits[1]["fruit"] = "apples";
$fruits[2]["fruit"] = "grapes";

usort($fruits, "cmp");

while (list($key, $value) = each($fruits)) {
    echo "\$fruits[$key]: " . $value["fruit"] . "\n";
}
?>

عند ترتيب مصفوفة متعددة الأبعاد، يحتوي كلًا من المتغيران ‎$a و ‎$‎b على مراجع إلى الفهرس الأول في المصفوفة. سوف تكون مُخرجات المثال أعلاه كالتالي:

$fruits[0]: apples
$fruits[1]: grapes
$fruits[2]: lemons

المثال 3: مثال على الدالة usort()‎‎ باستخدام دالة عضو في كائن

<?php
class TestObj {
   var $name;
   function TestObj($name)
   {
       $this->name = $name;
   }
    / * هذه هي وظيفة المقارنة الثابتة: * /
   static function cmp_obj($a, $b)
   {
       $al = strtolower($a->name);
       $bl = strtolower($b->name);
       if ($al == $bl) {
           return 0;
       }
       return ($al > $bl) ? + 1 : - 1 ;
   }
}
$a[] = new TestObj("c");
$a[] = new TestObj("b");
$a[] = new TestObj("d");
usort($a, array("TestObj", "cmp_obj"));
foreach ($a as $item) {
   echo $item->name . "\n";
}
?>

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

b
c
d

المثال 4: مثال على الدالة usort()‎‎ باستخدام دالة مجهولة closure لترتيب مصفوفة متعددة الأبعاد

<?php
$array[0] = array('key_a' => 'z', 'key_b' => 'c');
$array[1] = array('key_a' => 'x', 'key_b' => 'b');
$array[2] = array('key_a' => 'y', 'key_b' => 'a');

function build_sorter($key) {
    return function ($a, $b) use ($key) {
        return strnatcmp($a[$key], $b[$key]);
    };
}

usort($array, build_sorter('key_b'));

foreach ($array as $item) {
    echo $item['key_a'] . ', ' . $item['key_b'] . "\n";
}
?>

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

y, a
x, b
z, c

انظر أيضًا

• الدالةuasort()‎: ترتيب مصفوفة باستخدام دالة مقارنة معرفة من قبل المستخدم وتُحفاظ على ارتباط الفهارس بالقيم المقابلة.
• المقارنة بين دوال ترتيب المصفوفة.

مصادر

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