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

تعيد الدالة 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.