عرض مصدر Kotlin/multi declarations

<noinclude>{{DISPLAYTITLE:التصريحات بالتفكيك (Destructuring Declarations) في لغة Kotlin}}</noinclude>
== التصريح بالتفكيك ==
قد تحتاج في بعض الأحيان لتفكيك الكائن (object) إلى عددٍ من المتغيِّرات، مثل:<syntaxhighlight lang="kotlin">
val (name, age) = person 
</syntaxhighlight>تٌسمَّى الصيغة السابقة بالتصريح بالتفكيك والذي يُنشِئ أكثر من متغيِّر بنفس الوقت (وهما المتغيِّران<code>name</code> و <code>age</code>) حيث يُسمح باستخدامهما بشكلٍ مستقلٍ تمامًا كما في الشيفرة الآتية:<syntaxhighlight lang="kotlin">
println(name)
println(age)
</syntaxhighlight>إذ يُترجَم التصريح بالتفكيك كما يلي:<syntaxhighlight lang="kotlin">
val name = person.component1()
val age = person.component2()
</syntaxhighlight>حيث تُعدُّ الدالتان <code>component1()</code>‎ و <code>component2()</code>‎ مثالًا عن الاصطلاحات الأساسيّة المُستخدَمة في لغة Kotlin (راجع المُعامِلات مثل <code>+</code> و <code>*</code> وحلقات <code>for</code> و... إلخ.)، ويُسمَح بوجود أيّ كائنٍ في الجانب الأيمن من التصريح بالتفكيك طالما أمكن استدعاء العدد المطلوب من دوال الأجزاء (component functions) عبره (قد تكون بالأسماء  <code>component3()</code>‎ و <code>component4()</code>‎ وهكذا) والتي يجب أن تُحدَّد بالكلمة المفتاحيّة <code>operator</code> للسماح باستخدامها في هذا التصريح.

كما ويُستفاد من التصريح بالتفكيك في حلقة <code>for</code> بالشكل:<syntaxhighlight lang="kotlin">
for ((a, b) in collection) { ... }
</syntaxhighlight>حيث تحصل المتغيِّرات<code>a</code> و <code>b</code> على القيم من استدعاء الدالتين  <code>component1()</code>‎ و <code>component2()</code>‎ في عناصر المجموعة (collection).

== تطبيقٌ عمليٌّ: إعادة قيمتين من الدالة ==
عند الحاجة إلى إعادة عنصرين من الدالة (لنقل مثلًا إعادة كائن النتيجة وحالةٍ ما) فإن الطريقة المُتَّفق عليها للقيام بذلك هي إنشاء [[Kotlin/data classes|صنفٍ للبيانات (data class)]] وإعادة كائنٍ منه، كما في الشيفرة الآتية:<syntaxhighlight lang="kotlin">
data class Result(val result: Int, val status: Status)
fun function(...): Result {
    // بعض الحسابات
    
    return Result(result, status)
}

// الآن.. استخدام الدالة
val (result, status) = function(...)
</syntaxhighlight>ويُسمَح باستخدام التصريح بالتفكيك هنا لأنّ أصناف البيانات تعرِّف دوال الأجزاء <code>componentN()‎</code> تلقائيًا.

'''ملاحظة:''' يمكن استخدام الصنف القياسي <code>Pair</code> لتعيد الدالة <code>function()</code>‎ النوع <code>Pair<Int, Status></code>‎، ولكن من الأفضل تسميةُ البيانات بما يتناسب مع استخدامها.

== تطبيقٌ عمليٌّ: التصريحات بالتفكيك و Maps ==
إنّ الطريقة الأنسب للمرور بعناصر map هي كما في الشيفرة الآتية:<syntaxhighlight lang="kotlin">
for ((key, value) in map) {
   // القيام بالتعليمات استنادًا إلى القيمة والمفتاح
}
</syntaxhighlight>وهنا يجب التقيد بما يلي:
* تمثيل كائن map كتسلسلٍ (sequence) من القيم من خلال الدالة <code>iterator()‎</code>
* تمثيل كلٍّ من العناصر كزوجٍ (pair) من خلال الدالتين ‎<code>component1()</code>‎ و <code>component2()</code>‎‎
إذ تزوِّد المكتبة القياسية بمثل هذه الإضافات:<syntaxhighlight lang="kotlin">
operator fun <K, V> Map<K, V>.iterator(): Iterator<Map.Entry<K, V>> = entrySet().iterator()
operator fun <K, V> Map.Entry<K, V>.component1() = getKey()
operator fun <K, V> Map.Entry<K, V>.component2() = getValue()
</syntaxhighlight>مما يجعل من السهل استخدام التصريحات بالتفكيك في حلقات <code>for</code> بالاعتماد على maps (وكذلك كائنات مجموعات أصناف البيانات [collections of data class instances] وما يماثلها).

== استخدام الشرطة السفليّة (_) للمتغيرات غير المُستخدَمة (بدءًا من الإصدار 1.1) ==
إن لم يكن هناك حاجةٌ للمتغيِّر في التصريح بالتفكيك فيمكن الاستغناءُ عن اسمه بالشرطة السفليّة مثل:<syntaxhighlight lang="kotlin">
val (_, status) = getResult()
</syntaxhighlight>وبهذه الطريقة لن تُستدعَى دالة الجزء (component function) الموافقةِ له.

== التفكيك في lambdas (بدءًا من الإصدار 1.1) ==
تُستخدَم صيغةُ التصريحات بالتفكيك في معاملات lambda أيضًا، وإذا كان معامل lambda من النوع <code>Pair</code> (أو من النوع <code>Map.Entry</code> أو أي نوعٍ آخر يحتوي على دالة جزءٍ [component function] مناسبةٍ) فيُمكن حينئذٍ استخدام أكثر من معامل (تُحاط المعاملات بالأقواس <code>()</code>)، كما في الشيفرة الآتية:<syntaxhighlight lang="kotlin">
map.mapValues { entry -> "${entry.value}!" }
map.mapValues { (key, value) -> "$value!" }
</syntaxhighlight>ويتَّضِح الفرق بين التصريح عن معاملين والتصريح عنهما بالتفكيك، كما يلي:<syntaxhighlight lang="kotlin">
{ a -> ... } // معامل واحد
{ a, b -> ... } // معاملان
{ (a, b) -> ... } // تصريح مفكك بمتغيرين
{ (a, b), c -> ... } // تصريح مفكك بمتغيرين ومعامل ثالث مستقل
</syntaxhighlight>فإن كان أحد أجزاء التصريح بالتفكيك غير مستخدمٍ يُستعاض عنه بالشرطة السفليّة دون الحاجة لتسميته، مثل:<syntaxhighlight lang="kotlin">
map.mapValues { (_, value) -> "$value!" }
</syntaxhighlight>كما ويمكن تحديد النوع الإجماليّ لمعاملات التصريح بالتفكيك أو لمعاملٍ واحدٍ منها بشكلٍ منفصلٍ كما في الشيفرة الآتية:<syntaxhighlight lang="kotlin">
map.mapValues { (_, value): Map.Entry<Int, String> -> "$value!" }

map.mapValues { (_, value: String) -> "$value!" }
</syntaxhighlight>

== مصادر ==
* [https://kotlinlang.org/docs/reference/multi-declarations.html صفحة التصريح بالتفكيك في التوثيق الرسميّ للغة Kotlin]
[[تصنيف:Kotlin]]
[[تصنيف:Kotlin Objects]]
[[تصنيف:Kotlin Maps]]
[[تصنيف:Kotlin Lambdas]]
[[تصنيف:Kotlin Function]]