Kotlin/ranges/until

تنشئ الدالة ‎until()‎ مجالًا (range) تصاعديًا يبدأ القيمة التي استُدعيت معها وحتى القيمة الممرّرة إليها (لا تدخل هذه القيمة ضمن المجال).

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

infix fun Int.until(to: Byte): IntRange 
infix fun Long.until(to: Byte): LongRange 
infix fun Byte.until(to: Byte): IntRange 
infix fun Short.until(to: Byte): IntRange 
infix fun Long.until(to: Int): LongRange 
infix fun Int.until(to: Short): IntRange 
infix fun Long.until(to: Short): LongRange 
infix fun Byte.until(to: Short): IntRange 
infix fun Short.until(to: Short): IntRange

تنشئ الدالة ‎until()‎ مجالًا تصاعديًا يبدأ من القيمة التي استُدعيت معها وينتهي عند القيمة to الممرّرة إليها (لا تدخل ضمن المجال). ينبغي أن تكون القيمة to المُمرَّرة أكبر من القيمة التي استُدعيت معها الدالة، وإلّا فستعيد الدالة مجالًا فارغًا.

infix fun Char.until(to: Char): CharRange

تنشئ الدالة ‎until()‎ مجالًا تصاعديًا من المحارف يبدأ من المحرف Char الذي استُدعي معها وينتهي عند المحرف to الممرّرة إليها (لا تدخل ضمن المجال). يجب أن يكون المحرف to المُمرّر أكبر من المحرف '‎\u0000' أو ستعيد الدالة مجالًا فارغًا.

infix fun Int.until(to: Int): IntRange 
infix fun Byte.until(to: Int): IntRange 
infix fun Short.until(to: Int): IntRange

تنشئ الدالة ‎until()‎ مجالًا تصاعديًا يبدأ من القيمة التي استُدعيت معها وينتهي عند القيمة to الممرّرة إليها (لا تدخل ضمن المجال). ينبغي أن تكون القيمة to الممرَّرة أكبر من القيمة Int.MIN_VALUE، وإلّا فستعيد الدالة مجالًا فارغًا.

infix fun Int.until(to: Long): LongRange 
infix fun Long.until(to: Long): LongRange 
infix fun Byte.until(to: Long): LongRange
infix fun Short.until(to: Long): LongRange

تنشئ الدالة ‎until()‎ مجالًا تصاعديًا يبدأ من القيمة التي استُدعيت معها وينتهي عند القيمة to الممرّرة إليها (لا تدخل ضمن المجال). ينبغي أن تكون القيمة الممرَّرة أكبر من القيمة Long.MIN_VALUE، وإلّا فستعيد الدالة مجالا فارغًا.

وجود الكلمة المفتاحية infix يدل على أنَّ هذه الدالة يمكن استدعاؤها بنمط التدوين الداخليّ (infix notation)؛ أي من خلال حذف المعامل .والأقواس () المُستخدَمَين في الاستدعاء عادةً.

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

يعاد مجالٌ تصاعديٌّ يبدأ من القيمة المعطاة وينتهي عند القيمة to المُمرَّرة ولا تدخل هذه القيمة ضمن المجال.

مثال

استعمال الدالة until()‎ لإنشاء مجال من الأعداد الصحيحة ومجال من الأحرف:

fun main(args: Array<String>) {    
    val x = 5
    val y = 'a'

    print(x.until(9)) // 5..8
    print(y.until('f')) // a..e
}

انظر أيضًا

• الدالة rangeTo()‎: تنشئ مجالًا يقع بين المحرف الذي استدعي معها والمحرف المُمرّر إليها.
• الدالةdownTo()‎ : تنشئ مجالًا متدرجًا (progression) يبدًأ من القيمة القصوى التي استُدعيت معها وينحدر تنازليًّا حتى يصل إلى القيمة الممرّرة إليها.
• الدالة compareTo()‎: توازن بين قيمة العنصر الذي استُدعيت معه والقيمة المُمرّرة إليه ثمَّ تعيد القيمة 0 إن كانا متساويين، أو قيمة سالبة إن كانت القيمة الأولى (قيمة العنصر الذي استُدعيت معه) أصغر من القيمة الثانية، أو قيمة موجبة إن كانت القيمة الأولى أكبر من القيمة الثانية.

مصادر

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