⚙️ الدوال (Functions) في لغة نفطه

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

This file demonstrates how to define functions in the Naftah programming language, including detailed explanation of typed parameters, return types, and how to call functions. It also covers optional parameters, default values, and void functions.

📋 جدول الدوال المضمنة مع الوصف والأمثلة

وأيضًا هناك دوال مدمجة أخرى يمكن توسيعها أو إضافتها حسب الحاجة لتناسب متطلبات البرنامج.

✅ أمثلة عملية لاستخدام الدوال

---* عمليات الجمع *---
--- جمع عدد صحيح 8-بت (127) مع 1، الناتج 128 يتعدى حدود 8-بت
إجمع(127 ، 1)

--- جمع عدد صحيح 16-بت (32767) مع 1، الناتج 32768 يتعدى الحد الأعلى
إجمع(32767 ، 1)

--- جمع عدد صحيح 32-بت (2147483647) مع 1، الناتج يتجاوز الحد الأعلى
إجمع(2147483647 ، 1)

--- جمع عدد صحيح 64-بت (9223372036854775807) مع 1، الناتج يتعدى الحد الأعلى
إجمع(9223372036854775807 ، 1)

--- جمع عدد عشري ضخم مع 1، لاختبار دعم الأعداد الكبيرة
إجمع(340282346638528859811704183484516925440,000000 ، 1)

--- جمع أكبر عدد عشري ممكن (Float 128 تقريبًا) مع 1، للتحقق من الاستقرار العددي
إجمع(179769313486231570000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000,000000 ، 1)

---* عمليات الطرح *---
--- طرح 1 من 32768، للتحقق من الرجوع لداخل النطاق
إطرح(32768 ، 1)

--- طرح 1 من 2147483648 (32-بت + 1)
إطرح(2147483648 ، 1)

--- طرح 1 من 9223372036854775808 (64-بت + 1)
إطرح(9223372036854775808 ، 1)

--- طرح 1 من عدد عشري كبير
إطرح(340282346638528859811704183484516925441,000000 ، 1)

--- طرح 1 من عدد عشري كبير جدًا
إطرح(179769313486231570000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001,000000 ، 1)

---* عمليات الضرب *---
--- ضرب 127 * 2، الناتج 254 وهو ضمن حدود 8-بت
إضرب(127 ، 2)

--- ضرب 32767 * 2، الناتج 65534 وهو ضمن حدود 16-بت
إضرب(32767 ، 2)

--- ضرب 2147483647 * 2، قد يسبب تجاوز في 32-بت
إضرب(2147483647 ، 2)

--- ضرب 9223372036854775807 * 2، يتعدى 64-بت
إضرب(9223372036854775807 ، 2)

--- ضرب عدد عشري ضخم * 2
إضرب(340282346638528859811704183484516925440,000000 ، 2)

--- ضرب عدد عشري كبير جدًا * 2
إضرب(179769313486231570000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001,000000 ، 2)

---* عمليات القسمة *---
--- محاولة القسمة على صفر (خطأ رياضي)
حاول(إقسم(127 ، 0)) {
    نجاح(أ) -> إطبع(أ)
    فشل(ب) إفعل إطبع(ب)
}

--- قسمة صحيحة 254 / 2 = 127
إقسم(254 ، 2)

--- اختبار حدود 16-بت
إقسم(65534 ، 2)

--- اختبار حدود 32-بت
إقسم(4294967294 ، 2)

--- اختبار حدود 64-بت
إقسم(18446744073709551614 ، 2)

--- قسمة عدد عشري كبير على 2
إقسم(680564693277057719623408366969033850880,000000 ، 2)

--- قسمة أكبر عدد عشري ممكن
إقسم(179769313486231570000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001,000000 ، 2)

---* باقي القسمة *---
--- باقي قسمة على صفر (خطأ)
حاول(باقي_القسمة(127 ، 0)) {
    نجاح(أ) -> إطبع(أ)
    فشل(ب) إفعل إطبع(ب)
}

--- باقي قسمة 254 على 2، الناتج 0
باقي_القسمة(254 ، 2)

--- اختبار باقي قسمة لحدود 16-بت
باقي_القسمة(65534 ، 2)

--- حدود 32-بت
باقي_القسمة(4294967294 ، 2)

--- حدود 64-بت
باقي_القسمة(18446744073709551614 ، 2)

--- عدد عشري كبير
باقي_القسمة(680564693277057719623408366969033850880,000000 ، 2)

--- أقصى عدد عشري
باقي_القسمة(179769313486231570000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001,000000 ، 2)

---* المقارنات: الأكبر، الأصغر *---
--- إرجاع الأكبر بين 1 و 2 (2)
الأكبر(1 ، 2)

--- إرجاع الأصغر بين 1 و 2 (1)
الأكبر(2 ، 1)

--- إرجاع الأكبر بين -1 و 2
الأكبر(-1 ، 2)

--- إرجاع الأكبر بين -1 و 2
الأكبر(1 ، -2)

--- الأصغر بين 1 و 2
الأصغر(1 ، 2)
الأصغر(2 ، 1)

--- الأصغر بين -1 و 2
الأصغر(-1 ، 2)
الأصغر(1 ، -2)

---* الأسس *---
--- رفع 6 للأس 3 = 216
إرفع(6 ، 3)

--- رفع 200 للأس 2 = 40000
إرفع(200 ، 2)

--- رفع عدد كبير للأس صغير
إرفع(50000 ، 2)
إرفع(10000000 ، 3)

--- رفع عدد عشري كبير للأس 18
إرفع(10،0 ، 18)

--- رفع 10 لأس 309، قد يؤدي لتجاوز
إرفع(10،0 ، 309)

---* التقريب والرياضيات الأساسية *---
--- تقريب لأقرب عدد صحيح (3)
تقريب(2،5)

--- تقريب = 2
تقريب(2،3)

--- تقريب للعدد السالب (-2)
تقريب(-2،5)

--- تقريب = 2-
تقريب(-2،3)

--- الأرضي = 3
أرضي(3،7)

--- الأرضي = 3
أرضي(3،0)

--- الأرضي = -4
أرضي(-3،7)

--- الأرضي = -3
أرضي(-3،0)

--- سقف = 4
سقف(3،7)

--- سقف = 4
سقف(3،0)

--- سقف = 4
سقف(-3،7)

--- سقف = 4
سقف(-3،0)

---* دوال عددية أخرى *---
--- عكس الإشارة = 127
إنفي(-127)
--- عكس الإشارة = 32767
إنفي(-32767)
--- عكس الإشارة = 2147483647
إنفي(-2147483647)
--- عكس الإشارة = 9223372036854775807
إنفي(-9223372036854775807)
--- عكس الإشارة لعدد عشري كبير
إنفي(-340282346638528859811704183484516925440,000000)
--- عكس الإشارة لعدد عشري كبير
إنفي(-179769313486231570000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000,000000)

--- الجذر التربيعي
جذر(127)
جذر(32767)
جذر(2147483647)
جذر(9223372036854775807)
جذر(340282346638528859811704183484516925440,000000)
جذر(179769313486231570000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000,000000)

القيمة_المطلقة(2)

--- نزع الإشارة = 2
القيمة_المطلقة(-2)

القيمة_المطلقة(2،0)

--- نزع الإشارة = 2.0
القيمة_المطلقة(-2،0)

--- تُرجع -1 أو 1 أو 0
إشارة(2)
إشارة(0)
إشارة(-2)
إشارة(2،0)
إشارة(0،0)
إشارة(-2،0)

--- هل القيمة صفر؟
--- تتحقق مما إذا كانت القيمة 2 تساوي صفر. يجب أن تُرجع: خاطئ
هل_صفر(2)

--- تتحقق مما إذا كانت القيمة 0 تساوي صفر. يجب أن تُرجع: صحيح
هل_صفر(0)

--- تتحقق مما إذا كانت القيمة -2 تساوي صفر. يجب أن تُرجع: خاطئ
هل_صفر(-2)

--- تتحقق مما إذا كانت أي من القيمتين 2 و 0 تساوي صفر. يجب أن تُرجع: صحيح
هل_صفر(2،0)

--- تتحقق مما إذا كانت كلا القيمتين 0 و 0 تساوي صفر. يجب أن تُرجع: صحيح
هل_صفر(0،0)

--- تتحقق مما إذا كانت أي من القيمتين -2 و 0 تساوي صفر. يجب أن تُرجع: صحيح
هل_صفر(-2،0)

--- المقارنة: يساوي
--- تتحقق من تطابق القيمتين 2 و 2. يجب أن تُرجع: صحيح
هل_يساوي(2 ، 2)

--- تتحقق من تطابق -2 و 2. يجب أن تُرجع: خاطئ
هل_يساوي(-2 ، 2)

--- تتحقق من تطابق 2 و -2. يجب أن تُرجع: خاطئ
هل_يساوي(2 ، -2)

--- تتحقق من تطابق 1 و 2. يجب أن تُرجع: خاطئ
هل_يساوي(1 ، 2)

--- المقارنة: لا يساوي
--- تتحقق مما إذا كانت 2 لا تساوي 2. يجب أن تُرجع: خاطئ
هل_لا_يساوي(2 ، 2)

--- تتحقق مما إذا كانت -2 لا تساوي 2. يجب أن تُرجع: صحيح
هل_لا_يساوي(-2 ، 2)

--- تتحقق مما إذا كانت 2 لا تساوي -2. يجب أن تُرجع: صحيح
هل_لا_يساوي(2 ، -2)

--- تتحقق مما إذا كانت 1 لا تساوي 2. يجب أن تُرجع: صحيح
هل_لا_يساوي(1 ، 2)

--- أصغر من
--- تتحقق مما إذا كانت 1 أصغر من 2. يجب أن تُرجع: صحيح
هل_أصغر_من(1 ، 2)

--- تتحقق مما إذا كانت 2 أصغر من 1. يجب أن تُرجع: خاطئ
هل_أصغر_من(2 ، 1)

--- تتحقق مما إذا كانت 2 أصغر من -2. يجب أن تُرجع: خاطئ
هل_أصغر_من(2 ، -2)

--- تتحقق مما إذا كانت -2 أصغر من 2. يجب أن تُرجع: صحيح
هل_أصغر_من(-2 ، 2)

--- تتحقق مما إذا كانت 2 أصغر من 2. يجب أن تُرجع: خاطئ
هل_أصغر_من(2 ، 2)

--- أصغر أو يساوي
--- تتحقق مما إذا كانت 1 أصغر أو تساوي 2. يجب أن تُرجع: صحيح
هل_أصغر_أو_يساوي(1 ، 2)

--- تتحقق مما إذا كانت 2 أصغر أو تساوي 1. يجب أن تُرجع: خاطئ
هل_أصغر_أو_يساوي(2 ، 1)

--- تتحقق مما إذا كانت 2 أصغر أو تساوي -2. يجب أن تُرجع: خاطئ
هل_أصغر_أو_يساوي(2 ، -2)

--- تتحقق مما إذا كانت -2 أصغر أو تساوي 2. يجب أن تُرجع: صحيح
هل_أصغر_أو_يساوي(-2 ، 2)

--- تتحقق مما إذا كانت 2 أصغر أو تساوي 2. يجب أن تُرجع: صحيح
هل_أصغر_أو_يساوي(2 ، 2)

--- أكبر من
--- تتحقق مما إذا كانت 1 أكبر من 2. يجب أن تُرجع: خاطئ
هل_أكبر_من(1 ، 2)

--- تتحقق مما إذا كانت 2 أكبر من 1. يجب أن تُرجع: صحيح
هل_أكبر_من(2 ، 1)

--- تتحقق مما إذا كانت 2 أكبر من -2. يجب أن تُرجع: صحيح
هل_أكبر_من(2 ، -2)

--- تتحقق مما إذا كانت -2 أكبر من 2. يجب أن تُرجع: خاطئ
هل_أكبر_من(-2 ، 2)

--- تتحقق مما إذا كانت 2 أكبر من 2. يجب أن تُرجع: خاطئ
هل_أكبر_من(2 ، 2)

--- أكبر أو يساوي
--- تتحقق مما إذا كانت 1 أكبر أو تساوي 2. يجب أن تُرجع: خاطئ
هل_أكبر_أو_يساوي(1 ، 2)

--- تتحقق مما إذا كانت 2 أكبر أو تساوي 1. يجب أن تُرجع: صحيح
هل_أكبر_أو_يساوي(2 ، 1)

--- تتحقق مما إذا كانت 2 أكبر أو تساوي -2. يجب أن تُرجع: صحيح
هل_أكبر_أو_يساوي(2 ، -2)

--- تتحقق مما إذا كانت -2 أكبر أو تساوي 2. يجب أن تُرجع: خاطئ
هل_أكبر_أو_يساوي(-2 ، 2)

--- تتحقق مما إذا كانت 2 أكبر أو تساوي 2. يجب أن تُرجع: صحيح
هل_أكبر_أو_يساوي(2 ، 2)

--- العملية البتية: AND (و_بتي)
--- اختبار العملية AND بين 6 و 3. النتيجة: 2 (بِتِّيًا)
و_بتي(6 ، 3)

--- اختبار AND بين 0 و 2. النتيجة: 0
و_بتي(0 ، 2)

--- AND بين خاطئ و خاطئ. النتيجة: خاطئ (False)
و_بتي(خاطئ ، خاطئ)

--- AND بين خاطئ و صحيح. النتيجة: خاطئ
و_بتي(خاطئ ، صحيح)

--- AND بين صحيح و صحيح. النتيجة: صحيح (True)
و_بتي(صحيح ، صحيح)

--- العملية البتية: OR (أو_بتي)
--- OR بين 6 و 3. النتيجة: 7 (بِتِّيًا)
أو_بتي(6 ، 3)

--- OR بين 0 و 2. النتيجة: 2
أو_بتي(0 ، 2)

--- OR بين خاطئ و خاطئ. النتيجة: خاطئ
أو_بتي(خاطئ ، خاطئ)

--- OR بين خاطئ و صحيح. النتيجة: صحيح
أو_بتي(خاطئ ، صحيح)

--- OR بين صحيح و صحيح. النتيجة: صحيح
أو_بتي(صحيح ، صحيح)

--- العملية البتية: XOR (حصري_أو_بتي)
--- XOR بين 6 و 3. النتيجة: 5 (بِتِّيًا)
حصري_أو_بتي(6 ، 3)

--- XOR بين 0 و 2. النتيجة: 2
حصري_أو_بتي(0 ، 2)

--- XOR بين خاطئ و خاطئ. النتيجة: خاطئ
حصري_أو_بتي(خاطئ ، خاطئ)

--- XOR بين خاطئ و صحيح. النتيجة: صحيح
حصري_أو_بتي(خاطئ ، صحيح)

--- XOR بين صحيح و صحيح. النتيجة: خاطئ
حصري_أو_بتي(صحيح ، صحيح)

--- العملية البتية: NOT (ليس_بتي)
--- النفي البتي للقيمة 6. النتيجة: -7 (اعتمادًا على نظام التمثيل)
ليس_بتي(6)

--- النفي البتي للقيمة خاطئ. النتيجة: صحيح
ليس_بتي(خاطئ)

--- النفي البتي للقيمة صحيح. النتيجة: خاطئ
ليس_بتي(صحيح)

--- النفي البتي للقيمة 3. النتيجة: -4
ليس_بتي(3)

--- إزاحة إلى اليسار (Shift Left)
--- إزاحة 64 لليسار بمقدار 2 بت. النتيجة: 256
إزاحة_إلى_اليسار(64 ، 2)

--- إزاحة 1073741824 لليسار بمقدار 2 بت.
إزاحة_إلى_اليسار(1073741824 ، 2)

--- إزاحة 4611686018427387904 لليسار بمقدار 2 بت.
إزاحة_إلى_اليسار(4611686018427387904 ، 2)

--- إزاحة 1 لليسار بمقدار 100 بت (عادة تعطي 0 أو خطأ حسب النظام)
إزاحة_إلى_اليسار(1 ، 100)

--- إزاحة رقم عائم كبير جدًا لليسار بمقدار 2 بت
حاول(إزاحة_إلى_اليسار(340282346638528859811704183484516925440,000000 ، 2)) {
    نجاح(أ) -> إطبع(أ)
    فشل(ب) إفعل إطبع(ب)
}

--- إزاحة رقم أكبر لليسار بمقدار 2 بت
حاول(إزاحة_إلى_اليسار(179769313486231570000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000,000000 ، 2)) {
    نجاح(أ) -> إطبع(أ)
    فشل(ب) إفعل إطبع(ب)
}

--- إزاحة إلى اليمين (Shift Right)
--- إزاحة 128 لليمين بمقدار 2 بت. النتيجة: 32
إزاحة_إلى_اليمين(128 ، 2)

--- إزاحة 32768 لليمين بمقدار 2 بت.
إزاحة_إلى_اليمين(32768 ، 2)

--- إزاحة 2147483648 لليمين بمقدار 2 بت.
إزاحة_إلى_اليمين(2147483648 ، 2)

--- إزاحة 9223372036854775808 لليمين بمقدار 2 بت.
إزاحة_إلى_اليمين(9223372036854775808 ، 2)

--- إزاحة رقم عائم كبير جدًا لليمين بمقدار 2 بت
حاول(إزاحة_إلى_اليمين(340282346638528859811704183484516925441,000000 ، 2)) {
    نجاح(أ) -> إطبع(أ)
    فشل(ب) إفعل إطبع(ب)
}

--- إزاحة رقم أكبر لليمين بمقدار 2 بت
حاول(إزاحة_إلى_اليمين(179769313486231570000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001,000000 ، 2)) {
    نجاح(أ) -> إطبع(أ)
    فشل(ب) إفعل إطبع(ب)
}

--- إزاحة إلى اليمين غير موقعة (Unsigned Shift Right)
--- نفس القيم السابقة لكن مع إزاحة بدون اعتبار إشارة الرقم
إزاحة_إلى_اليمين_غير_موقعة(128 ، 2)
إزاحة_إلى_اليمين_غير_موقعة(32768 ، 2)
إزاحة_إلى_اليمين_غير_موقعة(2147483648 ، 2)
إزاحة_إلى_اليمين_غير_موقعة(9223372036854775808 ، 2)
حاول(إزاحة_إلى_اليمين_غير_موقعة(340282346638528859811704183484516925441,000000 ، 2)) {
    نجاح(أ) -> إطبع(أ)
    فشل(ب) إفعل إطبع(ب)
}
حاول(إزاحة_إلى_اليمين_غير_موقعة(179769313486231570000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001,000000 ، 2)) {
    نجاح(أ) -> إطبع(أ)
    فشل(ب) إفعل إطبع(ب)
}

--- زيادة قبلية (Pre-increment)
--- زيادة 127 قبل استخدامه، النتيجة: 128
زيادة_قبلية(127)

--- زيادة 32767 قبل استخدامه
زيادة_قبلية(32767)

--- زيادة 2147483647 قبل استخدامه
زيادة_قبلية(2147483647)

--- زيادة 9223372036854775807 قبل استخدامه
زيادة_قبلية(9223372036854775807)

--- زيادة رقم عائم كبير جدًا قبل استخدامه
زيادة_قبلية(340282346638528859811704183484516925440,000000)

--- زيادة رقم أكبر قبل استخدامه
زيادة_قبلية(179769313486231570000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000,000000)

--- زيادة بعدية (Post-increment)
--- زيادة 127 بعد استخدامه، النتيجة الأصلية: 127، بعدها تصبح 128
زيادة_بعدية(127)

--- زيادة 32767 بعد استخدامه
زيادة_بعدية(32767)

--- زيادة 2147483647 بعد استخدامه
زيادة_بعدية(2147483647)

--- زيادة 9223372036854775807 بعد استخدامه
زيادة_بعدية(9223372036854775807)

--- زيادة رقم عائم كبير جدًا بعد استخدامه
زيادة_بعدية(340282346638528859811704183484516925440,000000)

--- زيادة رقم أكبر بعد استخدامه
زيادة_بعدية(179769313486231570000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000,000000)

--- نقصان قبلي (Pre-decrement)
--- نقصان 128 قبل استخدامه، النتيجة: 127
نقصان_قبلي(128)

--- نقصان 32768 قبل استخدامه
نقصان_قبلي(32768)

--- نقصان 2147483648 قبل استخدامه
نقصان_قبلي(2147483648)

--- نقصان 9223372036854775808 قبل استخدامه
نقصان_قبلي(9223372036854775808)

--- نقصان رقم عائم كبير جدًا قبل استخدامه
نقصان_قبلي(340282346638528859811704183484516925441,000000)

--- نقصان رقم أكبر قبل استخدامه
نقصان_قبلي(179769313486231570000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001,000000)

--- نقصان بعدي (Post-decrement)
--- نقصان 127 بعد استخدامه، النتيجة الأصلية: 127، بعدها تصبح 126
نقصان_بعدي(127)

--- نقصان 32767 بعد استخدامه
نقصان_بعدي(32767)

--- نقصان 2147483647 بعد استخدامه
نقصان_بعدي(2147483647)

--- نقصان 9223372036854775807 بعد استخدامه
نقصان_بعدي(9223372036854775807)

--- نقصان رقم عائم كبير جدًا بعد استخدامه
نقصان_بعدي(340282346638528859811704183484516925440,000000)

--- نقصان رقم أكبر بعد استخدامه
نقصان_بعدي(179769313486231570000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000,000000)

🧩 تعريف دالة بسيطة

--- تعريف دالة باسم دالة_وهمية مع عدة معلمات، منها معلمات ثابتة (ثوابت) مع قيم افتراضية
دالة دالة_وهمية(ثابت معلمة_وهمية_1 :أي_نوع تعيين 1، ثابت معلمة_وهمية_2 : تسلسل_أحرف = «أي نص وهمي مع ش = ${ش}»، معلمة_وهمية_3 ، معلمة_وهمية_4 : عدد_عائم_طويل ، معلمة_وهمية_5 : عدد_عائم_طويل_جدا =١٣٤٤٥٦،٦٦٦ ) {
    ارجع معلمة_وهمية_1 + معلمة_وهمية_2 + معلمة_وهمية_3 + معلمة_وهمية_4 + معلمة_وهمية_5
}

🎯 استدعاء الدالة

--- استدعاء الدالة مع تمرير قيمتين فقط، الباقي يأخذ القيم الافتراضية
دالة_وهمية(٧٦٧٤٫٩٥٥ ، ٦٤٤٥٦٬٦٦٦٨)

--- استدعاء الدالة مع تمرير قيمة رقمية ونص فقط، باقي المعلمات تأخذ الافتراضية أو غير معروفة حسب الترتيب
دالة_وهمية(٧٦٧٤٫٩٥٥ ، «أي نص وهمي»)

--- استدعاء الدالة مع تحديد أسماء المعلمات بشكل صريح (مثل تمرير كائن إعدادات)
دالة_وهمية(معلمة_وهمية_1 تعيين 1، معلمة_وهمية_2 = «أي نص وهمي مع ش = ${ش}»، معلمة_وهمية_3 = ٦٤٤٥٦٬٦٦٦٨، معلمة_وهمية_4 = «أي نص وهمي»، معلمة_وهمية_5 =١٣٤٤٥٦،٦٦٦)

--- استدعاء مختلط مع تمرير بعض المعلمات بالترتيب وبعضها باستخدام أسماء معلمات
دالة_وهمية(معلمة_وهمية_1 تعيين 1، معلمة_وهمية_2 = «أي نص وهمي مع ش = ${ش}»، «أي نص وهمي» ، ٧٦٧٤٫٩٥٥ ، معلمة_وهمية_5 =١٣٤٤٥٦،٦٦٦)

✅ دوال بمعاملات اختيارية وقيم افتراضية

--- دالة ترحيب تقبل اسم مع معامل اختياري مع قيمة افتراضية
دالة ترحيب(اسم : تسلسل_رموز, تحية : تسلسل_رموز = "السلام عليكم") : تسلسل_رموز
    ارجع "${تحية}، ${اسم}!"
نهاية

--- استدعاء الدالة بدون تمرير المعامل الاختياري
ارجع ترحيب("علي")

--- استدعاء الدالة مع تمرير كلا المعاملين
ارجع ترحيب("علي", "مرحباً")

🔄 دوال بدون قيمة مرجعة (Void)

--- دالة تطبع رسالة على الشاشة بدون إرجاع قيمة
دالة اطبع_رسالة(نص : تسلسل_رموز)
    اطبع(نص) 
نهاية

--- استدعاء الدالة
اطبع_رسالة("مرحباً بك في لغة نفطه!")

🧩 إنشاء دوال مخصصة باستخدام الدوال المضمنة

--- دالة للتحقق مما إذا كان الرقم زوجيًا
دالة هل_زوجي(رقم) {
    إرجع هل_يساوي(باقي_القسمة(رقم, 2), 0)
}

--- اختبار الدالة
ثابت اختبار = هل_زوجي(10)  --- اختبار = صحيح
ثابت اختبار2 = هل_زوجي(7)  --- اختبار2 = خاطئ

🔄 العودية (Recursion) في البرمجة

الـ العودية هي تقنية برمجية حيث تقوم الدالة باستدعاء نفسها ضمن تعريفها. تُستخدم العودية لحل مشاكل يمكن تقسيمها إلى أجزاء أصغر تشبه المشكلة الأصلية.

كيف تعمل العودية؟

• حالة التوقف (Base Case): شرط يوقف الاستدعاءات العودية لمنع الحلقات اللانهائية.
• الاستدعاء العودي (Recursive Call): الدالة تستدعي نفسها على نسخة مبسطة أو أصغر من المشكلة.

لماذا نستخدم العودية؟

• تسهل كتابة الحلول لبعض المشاكل المعقدة مثل التعامل مع الهياكل الشجرية، والحسابات المتكررة، والتجميعات.
• تجعل الكود أكثر وضوحًا وأقرب إلى التفكير الرياضي أو المنطقي.

🧩 مثال: دالة المضروب (العامل) باستخدام العودية

--- دالة تحسب المضروب لعدد باستخدام العودية، مع قيمة افتراضية ١٠
دالة دالة_المضروب(عدد_مضروب تعيين 10) : عدد_طويل {
    --- شرط التوقف: إذا كان العدد ≤ ١، أرجع ١
    إذا عدد_مضروب أصغر_أو_يساوي ١ إذن {
        ارجع ١
    }
    أنهي

    --- الاستدعاء العودي: العدد × المضروب للعدد ناقص ١
    ارجع عدد_مضروب ضارب دالة_المضروب(عدد_مضروب ناقص ١)
}

🎯 استدعاءات الدالة مع شرح

دالة_المضروب(5)  --- تحسب 5 × 4 × 3 × 2 × 1 = 120

دالة_المضروب(1)  --- حالة التوقف، تعيد 1 مباشرة

دالة_المضروب()   --- تستخدم القيمة الافتراضية 10 وتحسب 10! = 3628800

جميع الدوال المضمنة مع الوصف 📋

مزوّد دوال مدمجة

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

دوال الخيوط

يحتوي هذا الموفر على دوال للتعامل مع الخيوط (Threads)
والمهام غير المتزامنة (Tasks)، بما يشمل:
• الحصول على الخيط الحالي
• تغيير اسم الخيط
• تغيير الأولوية
• التحقق من المقاطعة
• تشغيل مهام غير متزامنة
• الانتظار لنتائج المهام وإلغائها

دوال النظام

يحتوي هذا الموفر على دوال مدمجة مأخوذة من Java System class، مثل الوقت الحالي وقراءة متغيرات البيئة.

دوال التشغيل

يحتوي هذا الموفر على دوال مدمجة مأخوذة من Java Runtime class، مثل إدارة الذاكرة وإنهاء البرنامج وجمع القمامة.

دوال الحزم

يحتوي هذا الموفر على دوال لمعالجة المصفوفات، القوائم، والمجموعات (Collections).
تشمل العمليات الثنائية والفردية، الوصول للعناصر، واستبدالها.

دوال الزمن

يحتوي هذا الموفر على دوال مدمجة للتعامل مع الفترات، المدد، والنقاط الزمنية ضمن لغة نفطه بدقة وكفاءة.

🧠 ملاحظات

• أسماء الدوال في نفطه عربية مع إمكانيات استخدامها مع الأرقام الصحيحة والعشرية.
• العمليات الحسابية والمنطقية تدعم الأعداد بمختلف أحجامها (8-بت، 16-بت، 32-بت، 64-بت، والأعداد العشرية).
• الدوال المضمنة تسهل كتابة كود واضح وقابل للقراءة بالعربية.
• الدوال تبدأ بكلمة دالة وتنتهي بـ نهاية.
• يمكن تحديد أنواع المعاملات باستخدام : النوع.
• يمكن تحديد نوع القيمة المرجعة بعد القوسين باستخدام : نوع_القيمة.
• المعاملات يمكن أن تكون اختيارية مع قيم افتراضية.
• الدوال التي لا ترجع قيمة لا تحتاج إلى تحديد نوع إرجاع أو يمكن اعتبارها void.