الدوال والمصفوفات والنصوص

الوسائط المتغيرة (varargs)

15 دقيقة الدرس 4 من 14

الوسائط المتغيرة (varargs)

حتى الآن كنت تكتب توابع تعرف فيها عدد المعاملات المطلوب تحديدًا. لكن ماذا لو كان عدد القيم التي يريد المُستدعي تمريرها غير ثابت؟ تحلّ Java هذه المشكلة بأناقة عبر الوسائط المتغيرة، المعروفة اختصارًا بـ varargs. وهي تتيح لتابع واحد قبول أي عدد من الوسائط التي تنتمي إلى نفس النوع — صفر، أو واحد، أو أكثر — دون الحاجة إلى بناء مصفوفة قبل الاستدعاء.

صياغة ...

تُعلن عن معامل varargs بوضع ثلاث نقاط (...) بين النوع واسم المعامل:

public static int sum(int... numbers) {
    int total = 0;
    for (int n : numbers) {
        total += n;
    }
    return total;
}

داخل التابع، يتصرف numbers تمامًا كمصفوفة int[] عادية. يجمع وقت تشغيل Java تلقائيًا كل الوسائط التي يمررها المُستدعي ويحزمها في تلك المصفوفة نيابةً عنك.

وهذا مثال على طريقة استدعاء التابع أعلاه:

System.out.println(sum());               // 0  — صفر وسائط مسموح به
System.out.println(sum(5));              // 5
System.out.println(sum(1, 2, 3));        // 6
System.out.println(sum(10, 20, 30, 40)); // 100

ما يجري خلف الكواليس هو مصفوفة. حين تكتب sum(1, 2, 3)، يحوّلها المُترجم صامتًا إلى sum(new int[]{1, 2, 3}). بمعنى آخر، يمكنك أيضًا تمرير مصفوفة جاهزة مباشرةً: int[] vals = {4, 5, 6}; sum(vals);. كلا الأسلوبين يُترجم ويعمل بالطريقة ذاتها.

لماذا نستخدم varargs؟

تأمّل البديل من دون varargs. للسماح بعدد مرن من الوسائط ستحتاج إلى توابع متعددة متحمّلة (overloads)، أو إجبار كل مُستدعٍ على إنشاء مصفوفة:

// بدون varargs — توابع متحمّلة مُرهِقة
public static int sum(int a) { return a; }
public static int sum(int a, int b) { return a + b; }
public static int sum(int a, int b, int c) { return a + b + c; }
// وماذا عن أربع قيم؟ أو خمس؟ لا نهاية لذلك.

تستبدل varargs كل تلك التوابع بتابع واحد نظيف. تكتب المنطق مرة واحدة، ويحصل المُستدعون على صياغة طبيعية تُقرأ كوسائط عادية.

varargs مع المعاملات العادية

يمكن دمج معامل varargs مع معاملات عادية، لكن مع قاعدة صارمة واحدة: يجب دائمًا أن يكون معامل varargs في النهاية في قائمة المعاملات.

public static void printReport(String title, int... scores) {
    System.out.println("Report: " + title);
    int total = 0;
    for (int s : scores) {
        total += s;
    }
    System.out.println("Total score: " + total);
}

طريقة استدعاء هذا التابع:

printReport("Math Test", 85, 90, 78);
// الخرج:
// Report: Math Test
// Total score: 253

printReport("Empty Quiz");
// الخرج:
// Report: Empty Quiz
// Total score: 0

يرتبط الوسيط الأول دائمًا بـ title. كل ما يليه — بأي عدد من القيم — يتدفق إلى مصفوفة scores. إذا لم تُمرَّر قيم للدرجات، فإن scores تكون ببساطة مصفوفة فارغة (طولها 0)، وليست null.

تحقّق دائمًا من الطول لا من null. نظرًا لأن وقت التشغيل يضمن أن معامل varargs هو مصفوفة حقيقية غير فارغة (non-null)، يمكنك التكرار عليها بحلقة for-each حتى حين يمرر المُستدعي صفر وسائط. لست بحاجة أبدًا إلى فحص null.

نمط شائع في الواقع العملي: مساعدو تنسيق النصوص

تستخدم مكتبة Java القياسية varargs بكثافة. كلٌّ من String.format() وSystem.out.printf() وأطر تسجيل الأحداث الكثيرة تقبل سلسلة تنسيق يتبعها مصفوفة varargs من القيم:

// من المكتبة القياسية — توقيع مبسّط
public static String format(String format, Object... args)

// في الاستخدام
String msg = String.format("Hello %s, you scored %d out of %d.", "Alice", 42, 50);
System.out.println(msg);
// Hello Alice, you scored 42 out of 50.

فهم varargs يساعدك على قراءة مثل هذه الواجهات البرمجية واستخدامها بثقة.

القيود والأخطاء الشائعة

varargs واحدة فقط لكل تابع. لا يمكن كتابة void foo(int... a, String... b) — المُترجم يرفض ذلك.
يجب أن تكون الأخيرة. void foo(int... nums, String label) لا يُترجم.
غموض التحميل الزائد. إذا حمّلت تابعًا وكان أحد الإصدارات يستخدم varargs، فقد لا يعرف المُترجم أي إصدار يستدعي. احرص على أن تكون التوابع المتحمّلة لا لبس فيها.

varargs والأنواع العامة (generics) لا تتوافق بسلاسة. كتابة T... items يولّد تحذير مُترجم حول "تلوث الكومة" (heap pollution). تعرّف الآن أن هذا التحذير موجود؛ ويمكن إسكاته بـ @SafeVarargs على التوابع النهائية أو الثابتة. ستتعلم عن الأنواع العامة لاحقًا في المقرر.

الخلاصة

تتيح varargs (بصياغة type... name) كتابة تابع واحد يقبل أي عدد من الوسائط التي تنتمي إلى النوع ذاته. داخل التابع، يُعامَل المعامل كمصفوفة عادية. يجب أن يظهر معامل varargs دائمًا في آخر قائمة المعاملات. استخدم varargs حين يكون عدد المدخلات متغيرًا بالفعل، لكن آثر المعاملات العادية حين يكون العدد ثابتًا — ذلك يجعل الواجهة البرمجية أوضح ويتجنب الاستخدام الخاطئ غير المقصود.