عرض مصدر Kotlin/operator overloading

<noinclude>{{DISPLAYTITLE:التحميل الزائد للمعاملات (Operator Overloading) في لغة Kotlin}}</noinclude>
تُتيح لغة Kotlin إجراءَ مجموعةٍ مُعرَّفة مسبقًا من العمليات على أنواع البيانات المختلفة وذلك باستخدام رموزٍ ثابتةٍ تعتمدها لغة Kotlin مثل الرمز <code>+</code> أو الرمز <code>*</code> وتختلف فيما بينها بالأولويّة (precedence)، حيث توجد دالةٌ (إما [[Kotlin/functions|دالة من الصنف [member]]] أو [[Kotlin/extensions|دالة إضافيّة [extension]]]) باسمٍ ثابتٍ لكلّ معاملٍ مُعرَّف بحسب النوع (نوعٌ يساريٌّ للعمليات الثنائيّة [binary operations] ونوع متحولاتٍ [argument type] للعمليات الأحاديّة [unary operations])، ويجب تحديد الدوال التي تحتوي على تحميلٍ زائدٍ للمعاملات بالمُحدَّد <code>operator</code>، تناقش الصفحة الاصطلاحات (conventions) التي تنظِّم التحميل الزائد لمختلف المعاملات.

== العمليات الأحادية (Unary Operations) ==

=== المعاملات الأحادية البادئة (Unary Prefix Operators) ===
{| class="wikitable"
!التعبير
!يُترجَم إلى
|-
|<code>a+</code>
|<code>a.unaryPlus()‎</code>
|-
|<code>a-</code>
|<code>a.unaryMinus()‎</code>
|-
|<code>a!</code>
|<code>a.not()‎</code>
|}
يقوم المُترجِم (compiler) بالخطوات الآتية عند إجراء إحدى العمليات السابقة ولتكن <code>a+</code> :
* تحديد نوع المتحول <code>a</code> وليكن <code>T</code>
* البحث عن الدالة <code>unaryPlus()</code>‎ المسبوقة بالمُحدِّد <code>operator</code> والتي لا تحتوي أيّة متحولات للمستقبِل <code>T</code>  (إما دالة من الصنف [member] أو دالة إضافيّة [extension]) 
* إن لم تكن الدالة موجودةً أو كانت غامضةً فسينتُج خطأٌ بالترجمة (compilation error)
* إذا وُجدت الدالة وكان نوعها المُعاد <code>R</code> فسيكون للتعبير <code>a+</code> النوع <code>R</code> أيضًا
وتُتاح هذه العمليات (بالإضافة لعملياتٍ أخرى) [[Kotlin/basic types|للأنواع الأساسيّة]] في لغة Kotlin ولا تتطلَّب استدعاء الدوال، فيمكن مثلًا استخدام التحميل الزائد للمعامل الأحاديّ <code>-</code> بالشكل:<syntaxhighlight lang="kotlin">
data class Point(val x: Int, val y: Int)

operator fun Point.unaryMinus() = Point(-x, -y)

val point = Point(10, 20)
println(-point)  // "(-10, -20)" سيظهر
</syntaxhighlight>

=== معاملات الزيادة والنقصان ===
{| class="wikitable"
!التعبير
!يُترجَم إلى
|-
|<code>++a</code>
|<code>a.inc()‎</code>
|-
|<code>--a</code>
|<code>a.dec()‎</code>
|}
إذ ستُسنَد القيمة التي تعيدها الدالة <code>inc()‎</code> أو <code>dec()</code>‎ إلى المتحول الذي يُلحَق به المعامل <code>++</code> أو <code>--</code> دون أن تغيّر الدالةُ الكائنَ الذي استُدعيت من خلاله. يقوم المترجم بالخطوات الآتية لتنفيذ العملية اللاحقة (postfix) ولتكن <code>++a</code> مثلًا:
* تحديد نوع المتحول <code>a</code> وليكن النوع <code>T</code>

* البحث عن الدالة <code>inc()</code>‎ والمُعرَّفة بالمُحدِّد <code>operator</code> وتكون بدون متحولاتٍ وقابلةً للتطبيق على النوع <code>T</code>
* التحقُّق من أنّ النوع المُعاد من هذه الدالة هو نوعٌ فرعيٌّ للنوع <code>T</code>
وينتُج عن حساب التعبير:
* تخزين القيمة الابتدائيّة (initial value) للمتحول <code>a</code> في متحول مؤقت <code>a0</code>
* إسناد قيمة نتيجة الدالة <code>inc()‎</code> إلى المتحول السابق <code>a</code>
* إعادة المتحول <code>a0</code> كنتيجةٍ للتعبير
وتماثل خطوات تنفيذ العملية <code>--a</code> الخطوات السابقة.

أمّا معاملات الزيادة والنقصان بصيغتها البادئة (prefix) بالشكل: <code>a++</code> و <code>a--</code> فهي تعمل بالطريقة السابقة ذاتها وتكون النتيجة:
* إسناد نتيجة الدالة <code>a.inc()</code>‎ إلى المتحول <code>a</code>
* إعادة القيمة الجديدة للمتحول <code>a</code> كنتيجةٍ للتعبير

== العمليات الثنائيّة (Binary Operations) ==

=== المعاملات الحسابيّة (Arithmetic Operators) ===
{| class="wikitable"
!التعبير
!يُترجم إلى
|-
|<code>a + b</code>
|<code>a.plus(b)‎</code>
|-
|<code>a - b</code>
|<code>a.minus(b)‎</code>
|-
|<code>a * b</code>
|<code>a.times(b)‎</code>
|-
|<code>a / b</code>
|<code>a.div(b)‎</code>
|-
|<code>a % b</code>
|<code>a.rem(b)‎</code> و <code>a.mod(b)</code>‎ (مُستبعدة)
|-
|<code>a..b</code>
|<code>a.rangeTo(b)‎</code>
|}
تدعم Kotlin المعامل <code>rem</code> بدءًا من الإصدار Kotlin 1.1 ليحل محلّ <code>mod</code> في الإصدار Kotlin 1.0 (مُستبعد في الإصدار الحاليّ).

'''مثال'''

يبدأ الصنف <code>Counter</code> الآتي بقيمةٍ ابتدائيّةٍ من الممكن زيادتها باستخدام التحميل الزائد للمعامل <code>+</code> بالشكل:<syntaxhighlight lang="kotlin">
data class Counter(val dayIndex: Int) {
    operator fun plus(increment: Int): Counter {
        return Counter(dayIndex + increment)
    }
}
</syntaxhighlight>

=== المعامل <code>in</code> ===
{| class="wikitable"
!التعبير
!يُترجَم إلى
|-
|<code>a in b</code>
|<code>b.contains(a)‎</code>
|-
|<code>a !in b</code>
|<code>‎!b.contains(a)‎</code>
|}
وتكون الإجراءات نفسها في المعاملين حيث يُعكَس ترتيب المتحولات فقط.

=== معاملات الوصول المفهرس (Indexed Access Operators) ===
{| class="wikitable"
!التعبير
!يُترجَم إلى
|-
|<code>a[i]‎</code>
|<code>a.get(i)‎</code>
|-
|<code>a[i,j]‎</code>
|<code>a.get(i, j)‎</code>
|-
|<code>a[i_1, ..., i_n]‎</code>
|<code>(a.get(i_1, ..., i_n</code>
|-
|<code>a[i] = b</code>
|<code>a.set(i, b)‎</code>
|-
|<code>a[i, j] = b</code>
|<code>a.set(i, j, b)‎</code>
|-
|<code>a[i_1, ..., i_n] = b</code>
|<code>a.set(i_1, ..., i_n, b)‎</code>
|}
إذ تُترجَم الأقواس <code>[]</code> إلى استدعاء الدالة <code>get</code> أو <code>set</code> بما يتناسب مع عدد المتحولات.

=== معاملات الاستدعاء (Invoke Operators) ===
{| class="wikitable"
!التعبير
!يُترجَم إلى
|-
|<code>a()‎</code>
|<code>a.invoke()‎</code>
|-
|<code>a(i)‎</code>
|<code>a.invoke(i)‎</code>
|-
|<code>a(i,j)‎</code>
|<code>a.invoke(i,j)‎</code>
|-
|<code>a(i_1, ..., i_n)‎</code>
|<code>a.invoke(i_1, ..., i_n)‎</code>
|}
إذ تُترجَم الأقواس <code>()</code> إلى استدعاءات للدالة <code>invoke</code> بالعدد المناسب من المتحولات.

=== عمليات الإسناد المُحسَّنة (Augmented Assignments) ===
{| class="wikitable"
!التعبير
!يُترجَم إلى
|-
|<code>a += b</code>
|<code>a.plusِAssign(b)‎</code>
|-
|<code>a -= b</code>
|<code>a.minusAssign(b)‎</code>
|-
|<code>a *= b</code>
|<code>a.timesAssign(b)‎</code>
|-
|<code>a /= b</code>
|<code>a.divAssign(b)‎</code>
|-
|<code>a %= b</code>
|<code>a.remAssign(b)‎</code> و <code>a.modAssign(b)</code>‎ (مُستبعدة)
|}
إذ يقوم المُترجِم (compiler) بالخطوات الآتية لعمليات الإسناد، ولتكن العملية <code>a += b</code> مثلًا:
* إن كانت الدالة متاحةً:
** إن كانت الدالة الثنائيّة الموافقة لها (مثل الدالة <code>plus()‎</code> بالنسبة للدالة <code>plusAssign()</code>‎) متاحةً أيضًا  فيجب الإعلام بخطأ الالتباس (ambiguity)
** التأكّد من أنّ النوع المُعاد هو <code>Unit</code> والإعلام بالخطأ خلاف ذلك
** توليد الشيفرة المناسبة للدالة <code>a.plusِAssign(b)</code>‎
* إن لم تكن الدالة متاحةً: يحاول توليد الشيفرة <code>a = a + b</code> وهذا يتضمَّن التحقُّق من النوع؛ أي أن يكون نوع التعبير <code>a + b</code> نوعًا فرعيًا (subtype) من <code>a</code>
ولا تُعدُّ عمليات الإسنادا تعابيرًا (expressions) في Kotlin.

=== معاملات المساواة (Equality) والاختلاف (Inequality) ===
{| class="wikitable"
!التعبير
!يُترجَم إلى
|-
|<code>a == b</code>
|<code>a?.equals(b) ?: (b === null)‎‎</code>
|-
|<code>a != b</code>
|<code>‎!(a?.equals(b) ?: (b === null))‎</code>
|}
ويكون معاملا التحقُّق من المرجعيّة (<code>===</code> و <code>==!</code>) غير قابلين للتحميل الزائد (not overloadable) وبالتالي ما من استخدامٍ اصطلاحيٍّ لهما.

ويتميز المعامل <code>==</code> بأنه يُترجَم إلى تعبيرٍ معقَّدٍ يُضمِر القيمة <code>null</code> أي تكون نتيجة العملية <code>null == null</code> صحيحةً دائمًا، وتكون قيمة <code>x == null</code> خاطئةً دائمًا إن كان المتحول <code>x</code> متحولًا  nullable (أي لا يقبل القيمة الفارغة <code>null</code>) ولن تُستدعَى بذلك الدالة <code>x.equals()‎</code>.

=== معاملات المقارنة (Comparison Operators) ===
{| class="wikitable"
!التعبير
!يُترجم إلى
|-
|<code>a > b</code>
|<code>a.compareTo(b) > 0</code>
|-
|<code>a < b</code>
|<code>a.compareTo(b) < 0</code>
|-
|<code>a >= b</code>
|<code>a.compareTo(b) >= 0</code>
|-
|<code>a <= b</code>
|<code>a.compareTo(b) <= 0</code>
|}
إذ تُترجَم كافّة عمليات المقارنة إلى استدعاءاتٍ للدالة <code>compareTo</code> التي تعيد النوع <code>Int</code>.

=== معاملات تعميم الخاصّيّات (Property Delegation Operators) ===
وهي الدوال <code>provideDelegate</code> و <code>getValue</code> و <code>setValue</code> ولمزيدٍ من المعلومات راجع [[Kotlin/delegated properties|الخاصّيّات المُعمَّمة (delegated properties)]].

== استدعاء الدوال المسماة بالصيغة الضمنيّة (Infix) ==
تمكن محاكاة العمليّات بالصيغة الضمنيّة (infix) بالاعتماد على [[Kotlin/functions|استدعاءات الدوال الضمنيّة]].

== مصادر<span> </span> ==
* [https://kotlinlang.org/docs/reference/operator-overloading.html صفحة التحميل الزائد للمعاملات في التوثيق الرسميّ للغة Kotlin]
[[تصنيف:Kotlin]]
[[تصنيف:Kotlin Operators]]
[[تصنيف:Kotlin Functions]]