Kotlin/Array

الدوال البانية

`<int>`

يعيد التابع Any()‎ نسخةً من الصنف Any والذي هو الجذر الرئيسيّ في الهرميّة العامّة لأيّ صنفٍ مُستخدَمٍ أثناء البرمجة في Kotlin؛ أي أنّ كلَّ صنفٍ سيكون له الصنف الأعلى (superclass)‏ Any.

الدوال

`size`

تعبِّر الخاصيّة size‎ عن عدد العناصر الموجودة في المصفوفة (array).

`iterator`

يعيد التابع Array.iterator()‎ عنصرًا تكراريًّا (iterator) بهدف تكرار بنيةٍ (block) برمجيةٍ على كافّة عناصر المصفوفة.

`get`

يعيد التابع Array.get()‎ قيمة العنصر في المصفوفة عند الفهرس (index) المُحدَّد، ويمكن أيضًا استدعاء هذا التابع باستخدام معامل الفهرسة (index operator) المتمثل بالقوسين [] بالشكل:

الدوال الموروثة

`equals`

تبين الدالة equals()‎ إذا ما كان الكائن المُمرّر إليها يساوي الكائن الذي استدعيت عبره.

`hashCode`

يعيد التابع hashCode()‎ قيمة الشيفرة hash code الخاصّة بالكائن الذي استُدعي عبره.

`toString`

يعيد التابع toString()‎ تمثيلًا نصيًا للكائن الذي يُستدعى عبره.

الخاصيات الإضافية (Extension Properties)

`indices`

تُستخدَم هذه الخاصيّة للحصول على الفهارس الصحيحة (valid indices) للمصفوفة أو المجموعة (collection).

`lastIndex`

تُستخدَم هذه الخاصيّة للحصول على الفهرس (index) الأخير للمصفوفة أو القائمة (list)، أو القيمة ‎-1 إن كانت المصفوفة أو القائمة فارغةً.

الدوال الإضافية (Extension Functions)

`all`

تُعيد الدالة all()‎ القيمة true إن كانت كافّة عناصر المصفوفة أو المجموعة (collection) التي استُدعيت عبرها تحقق العبارة المنطقية (predicate) المُحدَّدة، أو تعيد القيمة false بخلاف ذلك.

`any`

يختلف سلوك الدالة any()‎ بحسب طريقة استدعائها، وسنناقش هذه الحالات تباعًا.

`asIterable`

تُنشئ الدالة asIterable()‎نسخة تكرارية (Iterable instance) والتي تُغلّف المصفوفة الاصلية وتعيد عناصرها عندما تُستخدم في حلقات التكرار (مثلfor).

`asList`

تُعيد الدالة asList()‎ لائحة (list) والتي تُغلّف المصفوفة الاصلية التي استُدعيت عبرها.

`asSequence`

تُنشئ الدالة asSequence()‎ نسخة من الواجهة Sequence والتي تُغلّف المصفوفة الاصلية وتعيد عناصرها عندما تُستخدم في حلقات التكرار (مثلfor).

`associate`

تعيد الدالة associate()‎ قاموسًا (map) يحتوي أزواجًا "مفتاح-قيمة" ناتجة عن تمرير عناصر المصفوفة أو المجموعة (Collection) إلى الدالةtransform.

تعيد الدالة associateBy()‎ قاموسًا (map) يحتوي ناتج تمرير عناصر المصفوفة أو المجموعة (Collection) إلى الدالة valueTransformمُفهرسة بناتج تمرير عناصر المصفوفة أو المجموعة إلى الدالة keySelector.

`associateByTo`

تعيد الدالة associateByTo()‎ قاموسًا متغيرا (mutable map) يحتوي ناتج تمرير عناصر المصفوفة أو المجموعة (Collection) إلى الدالةvalueTransform مُفهرسة بناتج تمرير عناصر المصفوفة أو المجموعة إلى الدالة keySelector.

`associateTo`

تعيد الدالة associateTo()‎ قاموسًا متغيرا (mutable map) يحتوي ناتج تمرير عناصر المصفوفة أو المجموعة (Collection) إلى الدالةtransform.

`average`

تعيد الدالة average()‎ متوسط (average) عناصر المصفوفة أو المجموعة (Collection).

`binarySearch`

تبحث الدالة binarySearch()‎ عن عنصر في المجموعة أو مجال من المجموعة (Collection) التي استُدعيت عبرها باستخدام خوارزمية البحث الثنائي (binary search algorithm)، يُفترض أن تكون المجموعة مرتبة وفق المُقارِن comparatorوإلا فستكون النتيجة غير مُحدّدة.

`component1`

تعيد الدالة component1()‎ العنصر الأول من المصفوفة التي استُدعيت عبرها، وفي حال استُدعيت عبر قاموس فستعيد مركبة المفتاح (key component) الخاصة بمدخل القاموس (map entry)، وتسمح هذه الدالة باستخدام التصريحات التفكيكية (destructuring declarations) عند العمل على القواميس.

`contains`

تعيد الدالة contains()‎ القيمة true إن كانت المصفوفة أو المجموعة التي استُدعيت عبرها تحتوي العنصر الممرّر إليها، وفي حال استُدعيت عبر قاموس فتعيد true إن كان ذلك القاموس يحتوي ذلك العنصر كمفتاح (key)، وتعيد false خلاف ذلك.

`contentDeepEquals`

تعيد الدالة contentDeepEquals()‎ القيمة true إن كانت المصفوفتان المحددتان متساويتان بعُمق، أي أنهما تحتويان على نفس عدد العناصر ونفس العناصر بنفس الترتيب، وتعيد false خلاف ذلك.

`contentDeepHashCode`

تعيد الدالة contentDeepHashCode()‎التكويد (hash code) استنادًا إلى محتوى المصفوفة التي استُدعيت عبرها كما لو كانت لائحة، المصفوفاتالمُتشعبة تعامل كاللوائح هي كذلك.

`contentDeepToString`

تعيد الدالةcontentDeepToString()‎تمثيلًا نصيًا لمحتوى المصفوفة التي استُدعيت عبرها كما لو كانت لائحة، المصفوفات المُتشعبة تعامل كاللوائح هي كذلك.

`contentEquals`

تعيد الدالة contentEquals()‎ االقيمة true إن كانت المصفوفتان المحددتان متساويتان بنيويًا (structurally equal)، أي أنهما تحتويان على نفس عدد العناصر ونفس العناصر بنفس الترتيب، وتعيد false خلاف ذلك.

`contentHashCode`

تعيد الدالة contentHashCode()‎التكويد (hash code) استنادًا إلى محتوى المصفوفة التي استُدعيت عبرها كما لو كانت لائحة.

`contentToString`

تعيد الدالةcontentToString()‎تمثيلًا نصيًا لمحتوى المصفوفة التي استُدعيت عبرها كما لو كانت لائحة.

`copyOf`

تعيد الدالةcopyOf()‎ نسخة من المصفوفة التي استُدعيت عبرها. مع إمكانية تمرير newSize كمعامل (parameter) لتحديد حجم المصفوفة الناتجة.

`copyOfRange`

تعيد الدالةcopyOfRange()‎ مصفوفة جديدة، والتي هي نسخة من مجال (range) من المصفوفة التي استُدعيت عبرها.

`count`

تعيد الدالةcount()‎عدد عناصر المصفوفة أو المجموعة أو القاموس التي استُدعيت عبرها، مع إمكانية تمرير دالة منطقية (predicate) كمعامل (parameter)، وحينها ستعيد عدد العناصر التي تحقق الدالة المنطقية predicate.

`distinct`

تعيد الدالةdistinct()‎ لائحة تحتوي عناصر المصفوفة أو المجموعة التي استُدعيت عبرها بدون تكرار مع احترام ظهور تلك العناصر في المصفوفة أوالمجموعة.

`distinctBy`

تعيد الدالةdistinctBy()‎ لائحة تحتوي عناصر المصفوفة أو المجموعة التي استُدعيت عبرها والتي تختلف نتائج تطبيق الدالة (selector) عليها، ومع احترام ظهور تلك العناصر في المصفوفة أوالمجموعة.

`drop`

تعيد الدالةdrop()‎ لائحة تحتوي جميع عناصر المصفوفة أو المجموعة التي استُدعيت عبرها باستثناء العناصر الأولى المحددة بالمعامل المُمرّر n.

`dropLast`

تعيد الدالةdropLast()‎ لائحة تحتوي جميع عناصر المصفوفة أو المجموعة التي استُدعيت عبرها باستثناء العناصر الأخيرة المحددة بالمعامل المُمرّر n.

`dropLastWhile`

تعيد الدالةdropLastWhile()‎ لائحة تحتوي جميع عناصر المصفوفة أو المجموعة التي استُدعيت عبرها باستثناء العناصر الأخيرة التي تحقق الشرط المنطقي predicate المُمرّر إلى الدالة.

`dropWhile`

تعيد الدالةdropWhile()‎ لائحة تحتوي جميع عناصر المصفوفة أو المجموعة التي استُدعيت عبرها باستثناء العناصر الأولى التي تحقق الشرط المنطقيpredicate المُمرّر إلى الدالة.

`elementAt`

تعيد الدالةelementAt()‎ العنصر الموجود عند الفهرس (index) المحدد من المصفوفة أو المجموعة التي استُدعيت عبرها، وفي حال كان ذلك الفهرس خارج حدود المصفوفة أو المجموعة فستُطلق استثناءً IndexOutOfBoundsException.

`elementAtOrElse`

تعيد الدالةelementAtOrElse()‎ العنصر الموجود عند الفهرس (index) المحدد من المصفوفة أو المجموعة التي استُدعيت عبرها، وفي حال كان ذلك الفهرس خارج حدود المصفوفة أو المجموعة فستُعيد ناتج تطبيق الدالة المُمرّرة defaultValue()‎ على الفهرس.

`elementAtOrNull`

تعيد الدالةelementAtOrNull()‎ العنصر الموجود عند الفهرس (index) المحدد من المصفوفة أو المجموعة التي استُدعيت عبرها، وفي حال كان ذلك الفهرس خارج حدود المصفوفة أو المجموعة فستُعيد القيمة المعدومة null.

`fill`

تعيّن الدالةfill()‎ قيمة العناصر الموجودة في الفهارس المحددة للمصفوفة أو اللائحة التي استُدعيت عبرها وتعطيها القيمة الممررة إليها.

`filter`

تعيد الدالةfilter()‎ لائحة تحتوي عناصر المصفوفة أو المجموعة التي تحقق الشرط المنطقي predicate()‎ المُمرّر إلى الدالة. وفي حال استدعائها عبرقاموس فستعيد قاموسًا جديدًا مكونًا من كل الأزوج التي تحقق الشرط المنطقي predicate()‎ الممرر إلى الدالة، هذا القاموسالجديد يحافظ على ترتيب تكرار (entry iteration order) القاموسالأصلي.

`filterIndexed`

تعيد الدالةfilterIndexed()‎ لائحة تحتوي عناصر المصفوفة أو المجموعة التي تحقق الشرط المنطقي predicate()‎ المُمرّر إلى الدالة، الدالة المنطقية predicate()‎ تأخذ فهرس العنصر وقيمته كمعامل وتعيد قيمة منطقية.

`filterIndexedTo`

تضيف الدالةfilterIndexedTo()‎ إلى المعامل destination الممرّر إليها عناصرّ المجموعة المتغيرة (MutableCollection) التي استُدعيت عبرها والتي تحقق الشرط المنطقي predicate()‎ المُمرّر إلى الدالة، الدالة المنطقية predicate()‎ تأخذ فهرس العنصر وقيمته كمعاملَين وتعيد قيمة منطقية.

`filterIsInstance`

تعيد الدالةfilterIsInstance()‎ لائحة تحتوي عناصر المصفوفة أو المجموعة التي استُدعيت عبرها والتي هي نسخة (instance) من نوع (type) أوصنفٍ معيّن.

`filterIsInstanceTo`

تضيف الدالةfilterIsInstanceTo()‎ عناصر المصفوفة أو المجموعة التي استُدعيت عبرها و التي هي نسخة (instance) من نوع (type) أو صنفٍمعيّن إلى المجموعة المتغيرة destination المُمرّرة إليها.

`filterNot`

تعيد الدالةfilterNot()‎ لائحة تحتوي عناصر المصفوفة أو المجموعة التي لا تحقق الشرط المنطقي predicate()‎ المُمرّر إلى الدالة. وفي حال استدعائها عبر قاموس فستعيد قاموسًا جديدًا مكونًا من كل الأزوج التي لا تحقق الشرط المنطقي predicate()‎ الممرر إلى الدالة، هذا القاموسالجديد يحافظ على ترتيب تكرار (entry iteration order) القاموسالأصلي.

`filterNotNull`

تعيد الدالةfilterNotNull()‎ لائحة تحتوي عناصر المصفوفة أو المجموعة غير المعدومة، أي التي تخالف قيمتها null.

`filterNotNullTo`

تضيف الدالةfilterNotNullTo()‎ إلى المعامل destination الممرّر إليها عناصرّ المصفوفة أو المجموعة التي استُدعيت عبرها والتي تخالف قيمتها القيمة null. من الجدير بالذكر أنّ destination ينبغي أن تكون مجموعة قابلة للتغيير (MutableCollection).

`filterNotTo`

تضيف الدالةfilterNotTo()‎ إلى المعامل destination الممرّر إليها عناصرّ المصفوفة أو المجموعة التي استُدعيت عبرها والتي لا تحقق الشرط المنطقي predicate المُمرّر إليها. من الجدير بالذكر أنّ destination ينبغي أن تكون مجموعة قابلة للتغيير (MutableCollection).

في حال استدعائها عبر قاموس فستضيف كل الأزوج التي لا تحقق الشرط المنطقي predicate()‎ إلى القاموس destination الممرّر إليها. ومن الجدير بالذكر أنّ destination ينبغي أن تكون قاموسًا قابلا للتغيير (MutableMap).

`filterTo`

تضيف الدالةfilterTo()‎ إلى المعامل destination الممرّر إليها عناصرّ المصفوفة أو المجموعة التي استُدعيت عبرها والتي تحقق الشرط المنطقيpredicate المُمرّر إليها. من الجدير بالذكر أنّ destination ينبغي أن تكون مجموعة قابلة للتغيير (MutableCollection).

في حال استدعائها عبر قاموس فستضيف كل الأزوج التي تحقق الشرط المنطقي predicate()‎ إلى القاموس destination الممرّر إليها. ومن الجدير بالذكر أنّ destination ينبغي أن تكون قاموسًا قابلا للتغيير (MutableMap).

`find`

تعيد الدالةfind()‎ العنصر الأول من المصفوفة أو المجموعة التي استُدعيت عبرها والذي يحقق الشرط المنطقي predicate المُمرّر إليها. وإن لم يكن هناك أي عنصر يحقق ذلك فستعيد null.

`findLast`

تعيد الدالةfindLast()‎ العنصر الأخير من المصفوفة أو المجموعة التي استُدعيت عبرها والذي يحقق الشرط المنطقي predicate المُمرّر إليها. وإن لم يكن هناك أي عنصر يحقق ذلك فستعيد null.

`first`

تعيد الدالةfirst()‎ العنصر الأول من المصفوفة أو المجموعة التي استُدعيت عبرها، وفي حال تمرير دالة منطقية كمعامل فستعيد أول عنصر يحقق تلك الدالة.

إن كانت المصفوفة أو المجموعة التي استُدعيت الدالةfirst()‎عبرها فارغة أو لم يكن هناك أي عنصر يحقق الدالة المنطقية الممررة إليها فستطلق الدالة الاستثناء NoSuchElementException.