Kotlin/collections/fold

تجمع الدالة fold()‎ تراكميًّا ناتج تطبيق عملية معينة على قيمة كل عنصر من عناصر الكائن المستدعى معها والقيمة التراكمية الحالية بالإضافة إلى قيمة أولية إن أعطيت، ويختلف سلوكها بحسب نوع الكائنات المستدعاة معها والمعاملات المُمرّرة إليها (انظر قسم "البنية العامة").

البنية العامة

تجمع الدالة fold()‎ بشكل تراكمي ناتج تطبيق عملية معينة على قيمة كل عنصر من عناصر المصفوفة أو المجموعة (من اليسار إلى اليمين) المستدعاة معها والقيمة التراكمية الحالية بالإضافة إلى القيمة الأولية إن أعطيت. 

inline fun <T, R> Array<out T>.fold(
    initial: R, 
    operation: (acc: R, T) -> R
): R 
inline fun <R> ByteArray.fold(
    initial: R, 
    operation: (acc: R, Byte) -> R
): R 
inline fun <R> ShortArray.fold(
    initial: R, 
    operation: (acc: R, Short) -> R
): R 
inline fun <R> IntArray.fold(
    initial: R, 
    operation: (acc: R, Int) -> R
): R 
inline fun <R> LongArray.fold(
    initial: R, 
    operation: (acc: R, Long) -> R
): R 
inline fun <R> FloatArray.fold(
    initial: R, 
    operation: (acc: R, Float) -> R
): R 
inline fun <R> DoubleArray.fold(
    initial: R, 
    operation: (acc: R, Double) -> R
): R 
inline fun <R> BooleanArray.fold(
    initial: R, 
    operation: (acc: R, Boolean) -> R
): R 
inline fun <R> CharArray.fold(
    initial: R, 
    operation: (acc: R, Char) -> R
): R 
inline fun <T, R> Iterable<T>.fold(
    initial: R, 
    operation: (acc: R, T) -> R
): R

الإصدار المطلوب: Kotlin 1.1. تُجمِّع الدالة fold()‎ العناصر من المصدر Grouping في مجموعات بحسب المفاتيح (keys) ثمَّ تطبّق العملية operation على عناصر كل مجموعة بشكل متتابع، إذ تُمرّر القيمة المتراكمة الراهنة والعنصر الراهن كوسيطين وتخزّن النتائج في خريطة جديدة. توفّر الدالة initialValueSelector قيمة أولية لكل مجموعة.

inline fun <T, K, R> Grouping<T, K>.fold(
    initialValueSelector: (key: K, element: T) -> R, 
    operation: (key: K, accumulator: R, element: T) -> R
): Map<K, R>

الإصدار المطلوب: Kotlin 1.1 تُجمّع الدالة fold()‎ العناصر من المصدر Grouping في مجموعات بحسب المفاتيح (keys) ثمَّ تطبّق العملية operation على عناصر كل مجموعة بشكل متتابع، إذ تُمرّر القيمة المتراكمة الراهنة والعنصر الراهن كوسيطين وتخزّن النتائج في خريطة جديدة. تعطى القيمة الأولية عبر تمرير قيمة للوسيط initialValue.

inline fun <T, K, R> Grouping<T, K>.fold(
    initialValue: R, 
    operation: (accumulator: R, element: T) -> R
): Map<K, R>

وجود الكلمة المفتاحية inline يدل على أنَّ هذه الدالة مباشرة (للمزيد من التفاصيل، راجع صفحة الدوال المباشرة (inline functions)).

المعاملات

initial

قيمة أولية يراد إضافتها مع ناتج تطبيق الدالة operation على أول عنصر من عناصر الكائن المعطى لبدء عملية التجميع.

operation

دالةٌ تمثل العملية المراد تطبيقها على كل عنصر من عناصر الكائن المعطى، إذ يمرَّر إليها القيمة المجمعة الحالية accumulator وقيمة كل عنصر element، وتعيد القيمة المجمَّعة التالية accumulator. 

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

تُعاد خريطةٌ تربط بين مفاتيح كل مجموعة مع نتيجة جمع جميع عناصرها بشكل تراكمي.

أمثلة

تعرف الشيفرة الآتية مصفوفة باسم array باستخدام الدالة ()arrayOf، ثمَّ تستخدم الدالة ()fold معها لجمع عناصرها بشكل تراكمي:

fun main(args: Array<String>) {
    val array = arrayOf(1, 2, 3, 4, 5, 6)

    val acc = array.fold(0) { sum, element -> sum + element }
    print(acc) // 21
}

انظر أيضًا

• الدالة foldRight()‎: تجمع بشكل تراكمي ناتج تطبيق عملية معيَّنة على قيمة كل عنصر من عناصر المصفوفة أو المجموعة (بدءًا من اليمين إلى اليسار) المستدعاة معها والقيمة التراكمية الحالية بالإضافة إلى القيمة الأولية إن أعطيت. 
• الدالة foldIndexed()‎: تجمع ناتج تطبيق عملية معينة على قيمة كل عنصر من عناصر المصفوفة أو المجموعة (بدءًا من اليسار إلى اليمين) المستدعاة معها وفهرس ذلك العنصر بشكل تراكمي بالإضافة إلى القيمة الأولية إن أعطيت.

• الدالة foldRightIndexed()‎: تجمع ناتج تطبيق عملية معينة على قيمة كل عنصر من عناصر المصفوفة أو المجموعة (بدءًا من اليمين إلى اليسار) المستدعاة معها وفهرس ذلك العنصر بشكل تراكمي بالإضافة إلى القيمة الأولية إن أعطيت.  
• الدالة reduce()‎: تجمع ناتج تطبيق عملية معينة على قيمة كل عنصر من عناصر الكائن المستدعى معها والقيمة المتراكمة الحالية.

مصادر

• صفحة الدالة fold()‎ في التوثيق الرسميّ للمكتبة القياسيّة في لغة Kotlin.