الدوال في C#: المعاملات والقيم المعادة وparams والتحميل الزائد وMain

الدالة (method) كتلة شيفرة مسمّاة تأخذ مدخلات (معاملات)، وتؤدي عملها، ويمكنها إعادة نتيجة (القيمة المعادة). في C# تعيش كل دالة داخل نوع؛ لا توجد دوال قائمة بذاتها.

using System;

class Program
{
    static decimal PriceWithTax(decimal net, decimal taxRate)
    {
        decimal tax = net * taxRate;
        return net + tax;
    }

    static void PrintReceipt(string item, decimal price)
    {
        Console.WriteLine($"{item,-10}{price,8:F2}");
    }

    static void Main()
    {
        decimal total = PriceWithTax(40m, 0.2m);
        PrintReceipt("Headphones", total);
        PrintReceipt("Cable", PriceWithTax(9.5m, 0.2m));
    }
}

المخرجات:

Headphones   48.00
Cable        11.40

تشريح الدالة

public static decimal PriceWithTax(decimal net, decimal taxRate)
{
    return net * (1 + taxRate);
}

• معدّل الوصول (public وprivate و...): من يُسمح له باستدعائها. إن حُذف تكون الدالة private لنوعها.
• static: تنتمي الدالة إلى النوع لا إلى كائن. المزيد عن ذلك أدناه.
• نوع الإرجاع: نوع القيمة التي تعيدها، أو void حين لا تعيد شيئًا.
• الاسم: PascalCase عُرفًا، وعادة فعل (Calculate وSendEmail وTryParse).
• قائمة المعاملات: صفر أو أكثر من أزواج type name. كل معامل متغيّر محلي يُهيّأ من وسيط المستدعي.
• الجسم: العبارات بين القوسين المعقوصين.

الاسم مع أنواع المعاملات (وأي معدّلات ref أو out أو in) يكوّن توقيع الدالة. نوع الإرجاع ليس جزءًا منه، وهذا مهم للتحميل الزائد.

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

تنهي return الدالة فورًا وتعيد قيمة. يجب على الدالة ذات نوع الإرجاع أن تعيد قيمة من ذلك النوع في كل مسار فيها:

static string Grade(int score)
{
    if (score >= 50)
        return "pass";
}   // error CS0161: 'Program.Grade(int)': not all code paths return a value

يفحص المترجم كل فرع. أضف return "fail"; الناقصة، أو throw إن كان بلوغ تلك النقطة خطأً برمجيًا.

الدالة void لا تعيد شيئًا. لكنها ما زالت تستطيع استخدام return; مجردة للمغادرة مبكرًا:

using System;

class Program
{
    static void Notify(string email, bool subscribed)
    {
        if (!subscribed)
        {
            Console.WriteLine($"{email}: not subscribed, skipped");
            return;
        }
        Console.WriteLine($"{email}: newsletter sent");
    }

    static bool IsStrongPassword(string pw)
    {
        if (pw.Length < 8) return false;
        foreach (char c in pw)
        {
            if (char.IsDigit(c)) return true;
        }
        return false;
    }

    static void Main()
    {
        Notify("ana@mail.com", true);
        Notify("ben@mail.com", false);
        Console.WriteLine(IsStrongPassword("sunshine"));
        Console.WriteLine(IsStrongPassword("sunshine42"));
    }
}

المخرجات:

ana@mail.com: newsletter sent
ben@mail.com: not subscribed, skipped
False
True

الدوال بجسم تعبيري

حين يكون جسم الدالة تعبيرًا واحدًا تحلّ => محل الأقواس المعقوصة وreturn:

static decimal Discount(decimal price) => price * 0.1m;
static bool IsAdult(int age) => age >= 18;
static void Log(string message) => Console.WriteLine($"[log] {message}");

هذه الدالة نفسها، مكتوبة بشكل أقصر. تعمل مع دوال void أيضًا، ما دام الجسم تعبيرًا واحدًا (استدعاء أو إسناد).

المعاملات نُسخ

تُمرَّر الوسائط بالقيمة افتراضيًا: يستقبل المعامل نسخة من الوسيط. الإسناد إلى المعامل داخل الدالة لا يؤثر في متغيّر المستدعي:

using System;
using System.Collections.Generic;

class Program
{
    static void Double(int n)
    {
        n = n * 2;
        Console.WriteLine($"inside: {n}");
    }

    static void AddBonus(List<int> scores)
    {
        scores.Add(100);
    }

    static void Main()
    {
        int points = 21;
        Double(points);
        Console.WriteLine($"after:  {points}");

        var scores = new List<int> { 70, 85 };
        AddBonus(scores);
        Console.WriteLine($"scores: {string.Join(", ", scores)}");
    }
}

المخرجات:

inside: 42
after:  21
scores: 70, 85, 100

تغيّرت List لأن القيمة المنسوخة في النوع المرجعي هي المرجع: تشير الدالة والمستدعي إلى كائن القائمة نفسه. إعادة الإسناد scores = new List<int>() داخل الدالة لن تؤثر في المستدعي. ولتسمح لدالة بالإسناد إلى متغيّر المستدعي استخدم ref أو out؛ ولإعطاء المعاملات قيمًا افتراضية واستدعائها بالاسم استخدم المعاملات الاختيارية والوسائط المسمّاة.

إعادة عدة قيم بصف

منذ C# 7.0 يمكن للدالة إعادة صف بعناصر مسمّاة، ويمكن للمستدعي تفكيكه إلى متغيّرات منفصلة:

using System;

class Program
{
    static (int Min, int Max, double Average) Stats(int[] values)
    {
        int min = values[0], max = values[0], sum = 0;
        foreach (int v in values)
        {
            if (v < min) min = v;
            if (v > max) max = v;
            sum += v;
        }
        return (min, max, (double)sum / values.Length);
    }

    static void Main()
    {
        int[] temps = { 18, 24, 21, 15, 27 };

        var stats = Stats(temps);
        Console.WriteLine($"min {stats.Min}, max {stats.Max}, avg {stats.Average:F1}");

        var (lo, hi, _) = Stats(temps);
        Console.WriteLine($"range {hi - lo}");
    }
}

المخرجات:

min 15, max 27, avg 21.0
range 12

يُهمل _ العنصر الذي لا تحتاجه. وللنتائج المستخدمة في أماكن كثيرة يوثّق صنف صغير أو سجل بخصائص مسمّاة الشكل أفضل من الصف.

التحميل الزائد

يمكن لعدة دوال أن تتشارك اسمًا إن اختلفت قوائم معاملاتها في العدد أو الأنواع أو ترتيب الأنواع. يختار المترجم أفضل تطابق لكل استدعاء:

using System;

class Program
{
    static double Area(double radius) => Math.PI * radius * radius;
    static double Area(double width, double height) => width * height;
    static int Area(int side) => side * side;

    static void Main()
    {
        Console.WriteLine(Area(2.0).ToString("F2"));
        Console.WriteLine(Area(3.0, 4.5).ToString("F2"));
        Console.WriteLine(Area(5));
    }
}

المخرجات:

12.57
13.50
25

تختار Area(5) نسخة int لأنها تطابق تام؛ وتختار Area(2.0) نسخة double. لا يمكن أن تختلف الدوال فقط في نوع الإرجاع: دالتا Area(int) تعيدان int وdouble هما الخطأ CS0111، Type 'Program' already defines a member called 'Area' with the same parameter types، لأن استدعاءً مثل Area(5) لن يستطيع التمييز بينهما.

والاستدعاء الذي لا يقبله أي شكل يفشل وقت الترجمة أيضًا: Area(1, 2, 3) هو CS1501، No overload for method 'Area' takes 3 arguments، وArea("big") هو CS1503، Argument 1: cannot convert from 'string' to 'double'.

params: عدد متغيّر من الوسائط

يقبل معامل مصفوفة params أي عدد من الوسائط، بما في ذلك لا شيء. يبني المترجم المصفوفة عنك:

using System;

class Program
{
    static decimal Total(string label, params decimal[] prices)
    {
        decimal sum = 0m;
        foreach (decimal p in prices) sum += p;
        Console.WriteLine($"{label}: {prices.Length} item(s), {sum}");
        return sum;
    }

    static void Main()
    {
        Total("empty cart");
        Total("one item", 9.99m);
        Total("three items", 4.50m, 12.00m, 3.25m);

        decimal[] saved = { 20m, 30m };
        Total("from array", saved);
    }
}

المخرجات:

empty cart: 0 item(s), 0
one item: 1 item(s), 9.99
three items: 3 item(s), 19.75
from array: 2 item(s), 50

القواعد: يجب أن يكون params المعامل الأخير (وإلا CS0231)، وللدالة واحد على الأكثر، وتمرير مصفوفة موجودة يسلّم تلك المصفوفة كما هي. الدالتان Console.WriteLine("{0} and {1}", a, b) وstring.Format من نوع params object[]. وسّعت C# 13 params لتشمل أنواع مجموعات أخرى مثل List<T> وReadOnlySpan<T>؛ وقبل ذلك لم يُسمح إلا بالمصفوفات.

الدوال الساكنة ودوال المثيل

تنتمي الدالة static إلى النوع وتُستدعى على اسم النوع: Math.Max(3, 7) وProgram.Total(...). أما دالة المثيل فتنتمي إلى كائن ويمكنها استخدام حقوله:

using System;

class Counter
{
    private int count;

    public void Increment() => count++;          // instance: uses this object's field
    public int Value() => count;

    public static Counter StartingAt(int n)       // static: no object needed to call it
    {
        var c = new Counter();
        c.count = n;
        return c;
    }
}

class Program
{
    static void Main()
    {
        Counter visits = Counter.StartingAt(10);
        visits.Increment();
        visits.Increment();
        Console.WriteLine(visits.Value());
    }
}

المخرجات:

12

استدعاء دالة مثيل من دالة ساكنة دون كائن هو أشيع خطأ للمبتدئين في C#:

class Program
{
    void Greet() => Console.WriteLine("hi");

    static void Main()
    {
        Greet();
        // error CS0120: An object reference is required for the non-static field, method, or property 'Program.Greet()'
    }
}

علّم Greet بـ static، أو أنشئ كائنًا واستدعها عليه: new Program().Greet();. تغطي صفحة static الأعضاء الساكنة والأصناف الساكنة بعمق أكبر.

الدالة Main

Main هي حيث يبدأ البرنامج. يجب أن تكون static، وهذه التواقيع صالحة:

static void Main() { }
static void Main(string[] args) { }            // command-line arguments
static int Main(string[] args) { return 0; }   // exit code for the shell
static async Task Main() { }                    // C# 7.1 and later

يتيح الشكل async Task Main لنقطة الدخول استخدام await مباشرة (راجع async وawait). ومنذ C# 9 يمكن للملف بدلًا من ذلك أن يحتوي على عبارات عالية المستوى: شيفرة بلا صنف ولا Main إطلاقًا، كما في مشروع dotnet new console جديد. يولّد المترجم الصنف والدالة Main حولها، فهي الشيء نفسه بشكل أقصر؛ وما زالت args متاحة.

الاستدعاء الذاتي

يمكن للدالة أن تستدعي نفسها. يحصل كل استدعاء على معاملاته ومتغيّراته المحلية الخاصة، ويجب أن توقف حالة أساس السلسلة:

using System;

class Program
{
    static long Factorial(int n)
    {
        if (n <= 1) return 1;            // base case
        return n * Factorial(n - 1);
    }

    static int DigitSum(int n) => n < 10 ? n : n % 10 + DigitSum(n / 10);

    static void Main()
    {
        Console.WriteLine(Factorial(5));
        Console.WriteLine(Factorial(20));
        Console.WriteLine(DigitSum(98765));
    }
}

المخرجات:

120
2432902008176640000
35

دون حالة أساس، أو مع مدخلات عميقة جدًا، يضيف كل استدعاء إطارًا إلى المكدّس حتى يموت البرنامج بـ StackOverflowException. لا يمكن التقاط هذا الاستثناء، فللمدخلات مجهولة العمق أعد كتابة الاستدعاء الذاتي كحلقة.

الدوال المحلية

قدّمت C# 7.0 الدوال المحلية: دوال مصرّح بها داخل دالة أخرى، ومرئية هناك فقط. يمكنها استخدام متغيّرات الدالة المحيطة:

// C# 7.0 and later
static int CountValid(string[] codes)
{
    int count = 0;
    foreach (string code in codes)
    {
        if (IsValid(code)) count++;
    }
    return count;

    bool IsValid(string c) => c.Length == 6 && char.IsLetter(c[0]);
}

تبقي الدالة المساعدة بجانب مستدعيها الوحيد دون كشفها لبقية الصنف. ومنذ C# 8 يمكن تعليمها بـ static لمنع التقاط المتغيّرات الخارجية. وحيث لا تتوفر دالة محلية تؤدي دالة ساكنة خاصة في الصنف نفسه المهمة نفسها، كما في الأمثلة الأخرى في هذه الصفحة.