الوسائط المتغيرة (Varargs) في جافا: دوال تقبل أي عدد من الوسائط

دالة واحدة، أي عدد من الوسائط

أحيانًا لا تعرف مسبقًا كم وسيطًا تحتاج إليه دالة. قد ترغب في max(3, 9) في لحظة، ثم max(1, 7, 4, 2, 8) في اللحظة التالية. بدون الوسائط المتغيرة، عليك كتابة حِمل زائد (overload) لكل عدد أو إجبار المستدعي على بناء مصفوفة. تتيح الوسائط المتغيرة - اختصارًا لـ variable arguments - لدالة واحدة أن تقبل صفرًا أو واحدة أو عدة قيم من النوع نفسه.

تُعرّفها بوضع ثلاث نقاط (...) بعد نوع المعامل:

public class Main {
    static int sum(int... numbers) {
        int total = 0;
        for (int n : numbers) {   // numbers مجرد int[]
            total += n;
        }
        return total;
    }

    public static void main(String[] args) {
        System.out.println(sum(1, 2, 3));        // 6
        System.out.println(sum(10, 20));         // 30
        System.out.println(sum());               // 0 - يُسمح بصفر وسائط
        System.out.println(sum(4, 8, 15, 16));   // 43
    }
}

يمرّر المستدعي قيمًا متفرقة؛ وداخل الدالة يكون numbers مصفوفة حقيقية. هذه هي الفكرة كلها - فالمصرّف يحزم الوسائط في مصفوفة نيابةً عنك.

الوسائط المتغيرة ما هي إلا مصفوفة

لا سحر وقت التشغيل. المعامل المُعرّف على أنه int... numbers هو بالضبط int[] بمجرد أن تصبح داخل الدالة. يمكنك الاستعلام عن length الخاص به، والوصول إليه بالفهرس، والمرور عليه بحلقة كأي مصفوفة أخرى.

public class Main {
    static String join(String separator, String... parts) {
        if (parts.length == 0) {
            return "";
        }
        StringBuilder sb = new StringBuilder(parts[0]);
        for (int i = 1; i < parts.length; i++) {
            sb.append(separator).append(parts[i]);
        }
        return sb.toString();
    }

    public static void main(String[] args) {
        System.out.println(join("-", "2026", "06", "04"));  // 2026-06-04
        System.out.println(join(", ", "alone"));            // alone
    }
}

ولأنها مصفوفة حقيقية، يمكنك أيضًا أن تسلّم دالة الوسائط المتغيرة مصفوفة تملكها بالفعل - فهي تقبل كلا الشكلين:

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

    public static void main(String[] args) {
        int[] data = {5, 10, 15};
        System.out.println(sum(data));        // مرّر مصفوفة موجودة مسبقًا
        System.out.println(sum(1, 2, 3, 4));  // أو قيمًا متفرقة
    }
}

القواعد: الأخير وواحد فقط

قاعدتان تُبقيان الوسائط المتغيرة بلا التباس، والمصرّف يفرضهما معًا:

1. يجب أن يكون معامل الوسائط المتغيرة الأخير. تأتي المعاملات العادية أولًا، ثم يمتص معامل ... كل ما تبقّى.
2. يمكن للدالة أن تحتوي على معامل varargs واحد على الأكثر. وجود اثنين يجعل من المستحيل معرفة أين ينتهي أحدهما ويبدأ التالي.

public class Main {
    // سليم: معامل عادي أولًا، ثم الوسائط المتغيرة في النهاية
    static void log(String level, Object... values) {
        System.out.print("[" + level + "] ");
        for (Object v : values) {
            System.out.print(v + " ");
        }
        System.out.println();
    }

    public static void main(String[] args) {
        log("INFO", "user", 42, true);
        log("WARN");   // يمكن أن يكون جزء الوسائط المتغيرة فارغًا
    }
}

هذا يُصرَّف بنجاح. لكن وضع الوسائط المتغيرة أولًا - static void log(Object... values, String level) - خطأ تصريف: varargs parameter must be the last. المعامل الإلزامي level يسبق دائمًا الـ ....

أين تستخدم الوسائط المتغيرة بالفعل

لقد كنت تستدعي دوال الوسائط المتغيرة طوال الوقت. System.out.printf وString.format هما المثالان الكلاسيكيان - معاملهما الثاني هو Object... args:

public class Main {
    public static void main(String[] args) {
        System.out.printf("%s scored %d points (%.1f%%)%n", "Ada", 95, 95.0);

        String row = String.format("%-8s | %5d", "banana", 30);
        System.out.println(row);
    }
}

كما أن List.of(...) وArrays.asList(...) والكثير من واجهات البرمجة بنمط الباني (builder) تستخدم الوسائط المتغيرة أيضًا. لهذا يمكنك تمرير أي عدد من العناصر إليها دون أن تلفّ أي شيء في مصفوفة بنفسك.

الوسائط المتغيرة والتحميل الزائد

تتفاعل الوسائط المتغيرة والتحميل الزائد بطريقة مفاجئة واحدة. عندما يمكن لحِمل زائد عادي وحِمل زائد بالوسائط المتغيرة أن يطابقا كلاهما استدعاءً، تفضّل جافا الأكثر تحديدًا - فتفوز الدالة ذات العدد الثابت من الوسائط:

public class Main {
    static String pick(int a, int b) {
        return "two-arg version";
    }

    static String pick(int... nums) {
        return "varargs version";
    }

    public static void main(String[] args) {
        System.out.println(pick(1, 2));      // two-arg version (الأكثر تحديدًا)
        System.out.println(pick(1, 2, 3));   // varargs version
        System.out.println(pick());          // varargs version
    }
}

يطابق pick(1, 2) كليهما، لكن جافا تختار الحِمل الزائد غير المتغير لأنه الأقرب ملاءمةً. لا تُنفَّذ دالة الوسائط المتغيرة إلا حين لا يطابق أي حِمل زائد ذي عدد ثابت من الوسائط. هذا عادةً ما تريده، لكنه يعني أن إضافة حِمل زائد بالوسائط المتغيرة قد تغيّر بصمت أيّ دالة يُحَلّ إليها الاستدعاء.

انتبه للاستدعاءات الفارغة واستدعاءات null

مزلقان يوقعان الناس في الخطأ. الأول: استدعاء دالة وسائط متغيرة بلا وسائط يسلّم الدالة مصفوفة فارغة، لا null - لذا يكون numbers.length يساوي 0 ولا تفعل الحلقة شيئًا. لا تحتاج إلى فحص null لحالة عدم وجود وسائط:

public class Main {
    static int count(Object... items) {
        return items.length;   // 0 عند count()، ولن يحدث NPE أبدًا
    }

    public static void main(String[] args) {
        System.out.println(count());            // 0
        System.out.println(count("a", "b"));    // 2
    }
}

الثاني: تمرير null حرفيًا أمر ملتبس وخطير: قد تفسّر جافا count(null) على أنه "مصفوفة الوسائط المتغيرة كلها null" بدلًا من "عنصر null واحد"، مما يطرح حينها NullPointerException عند قراءة length الخاص بها. إن كنت تقصد فعلًا عنصر null واحدًا، فكن صريحًا بكتابة count((Object) null).

التالي: الأصناف (Classes)

تُكمل الوسائط المتغيرة ما يمكنك فعله بمعاملات الدوال - قوائم وسائط مرنة فوق التحميل الزائد. حتى الآن كانت الدوال موضوعة بشكل متفكك داخل صنف باستخدام static. بعد ذلك سترى كيف تعمل الأصناف حقًا: تجميع البيانات (الحقول) والسلوك (الدوال) في أنواعك الخاصة، وهو جوهر البرمجة الكائنية التوجّه في جافا.