النصوص في Kotlin

دول للاستعمال مع النصوص والتعابير النمطية.

الأنواع

MatchGroup

تمثل نتيجة من مجموعة مطابقة داخل  MatchResult الخاصة بالصنف Regex.

MatchGroupCollection

تمثل MatchGroupCollection مجموعة من الفئات المرصودة (captured groups) في إحدى مطابقات تعبير نمطي ما.

MatchNamedGroupCollection

تمدد  MatchGroupCollection عبر تقديم طريقة للحصول على الفئات المُطابَقة (matched groups) بأسمائها، عندما تكون regex  مدعومة.

MatchResult

تمثل نتيجة مطابقة واحدة لتعبير نمطي.

Regex

يمثل تعبيرًا نمطيا قابلا للتعديل (immutable regular expression).

RegexOption

يوفّر قيما مُرقّمة (enumeration values) لاستخدامها في تعيين خيارات التعابير النمطية.

Typography

تعرّف أسماء لرموز اليونيكود المستخدمة في الطباعة الخاصة.

تمديدات لأصناف خارجية

java.lang.Appendable

تمديد للصنف java.lang.Appendable.

java.util.regex.Pattern

تمديد للصنف java.util.regex.Pattern.

الخاصيات

category

تعيد category قيمة تبيّن الفئة العامة للحرف.

directionality

تعيد directionality اتجاه الحرف (Unicode directionality property) الذي استُدعيت عبره.

indices

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

lastIndex

تُستخدَم هذه الخاصيّة للحصول على فهرس الحرف الأخير في سلسلة الحروف التي استُدعيت عبرها، أو تعيد ‎-1 إن كانت فارغة.

size

هذه الخاصية صارت مُتجاوزة، استخدم الخاصية length بدلًا منها.

الدوال

Regex_0

هذه الدالة صارت مُتجاوزة. إذ تنشئ تعبيرًا نمطيًا (regular expression) انطلاقًا من السلسلة النصية المُمرّرة.

Regex_1

هذه الدالة صارت مُتجاوزة. إذ تنشئ تعبيرًا نمطيًا (regular expression) انطلاقًا من السلسلة النصية المُمرّرة.

String

يختلف سلوك الدالة String()‎ بحسب نوع وعدد الوسائط المُمررة، انظر فقرة البنية العامة.

all

تعيد الدالة all()‎ القيمة true إن كانت كل الحروف تحقق الشرط المنطقي المُمرّر predicate.

any

تعيد الدالة any()‎ القيمة true إن كان هناك حرف واحد على الأقل يحقق الشرط المنطقي المُمرّر predicate.

append

تضم الدالة append()‎ الوسائط المُمرّرة إلى الكائن الذي استُدعيت عبره، والذي ينبغي أن يكون من الصنف Appendable.

asIterable

تنشئ الدالة asIterable()‎ كائنًا من الصنف Iterable والذي يُغلّف سلسلة الحروف التي استُدعيت عبرها، لأجل استعمالها في الحلقات التكرارية.

asSequence

تنشئ الدالة asSequence()‎ كائنًا من الصنف Sequence والذي يُغلّف سلسلة الحروف التي استُدعيت عبرها، لأجل استعمالها في الحلقات التكرارية.

associate

تعيد الدالة associate()‎ قاموسًا (map) يحتوي أزواجًا من "مفتاح/قيمة" ناتجة عن تمرير عناصر سلسلة الحروف التي استُدعيت عبرها.

associateBy

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

associateByTo

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

associateTo

تملأ الدالة associateTo()‎ القاموس المتغير destination بأزواج من "مفتاح/قيمة"، حيث القيمة هي عناصر سلسلة الحروف التي استُدعيت عبرها، والمفتاح هو الناتج المعاد من تمرير تلك العناصر إلى الدالة transform.

buildString

تبني الدالة buildString()‎ سلسلة نصية عبر ملأ الكائن من نوع StringBuilder المُنشأ حديثَا باستخدام الدالة المُمرّرة builderAction‎ ثم تُحولها إلى سلسلة نصية. في حال تمرير وسيط capacity من نوع Int فإنّ الكائن StringBuilder سيأخذ قيمه الابتدائية انطلاقا منcapacity.

capitalize

تعيد الدالة capitalize()‎ نسخة من السلسلة النصية التي استُدعيت عبرها، مع جعل الحرف الأول كبيرًا (uppercase).

charset

تعيد الدالة charset()‎ مجموعة المحارف المُسمّاة (named charset) ذات الاسم المُمرّر charsetName.

chunked

تُقسّم الدالة chunked()‎ سلسلة الحروف التي استُدعيت عبرها إلى لوائح تحتوي سلاسل نصية، بحيث لا يتجاوز تعدادها العدد المُمرّر size.

chunkedSequence

تُقسّم الدالة chunkedSequence()‎ سلسلة الحروف التي استُدعيت عبرها إلى سلسلاتتحتوي سلاسل نصية، بحيث لا يتجاوز تعدادها العدد المُمرّرsize.

codePointAt

تعيد الدالة codePointAt()‎ كود اليونيكود (Unicode code point) للحرف الموجود في الفهرس المُحدّد.

codePointBefore

تعيد الدالة codePointBefore()‎ كود اليونيكود (Unicode code point) للحرف الموجود قبل الفهرس المُحدّد.

codePointCount

تعيد الدالة codePointCount()‎ عدد أكواد اليونيكود (Unicode code point) في المجال المُحدّد من النص.

commonPrefixWith

تعيد الدالة commonPrefixWith()‎ أكبر سابقة (prefix) مُشتركة بين سلسلة الحروف التي استُدعيت عبرها وسلسلة الحروف المُمرّرة، وفي حال إعطاء القيمة true للوسيط ignoreCase فستتجاهل الدالة حالة الحروف (لن تفرّق بين الحروف الكبيرة والصغيرة). الدالة أيضًا لا تُقسّم الأزواج البديلة (surrogate pairs)، وإن لم تكن بينهما سابقة مشتركة فستعيد سلسلة نصية فارغة. 

commonSuffixWith

تعيد الدالة commonSuffixWith()‎ أكبر لاحقة (suffix) مُشتركة بين سلسلة الحروف التي استُدعيت عبرها وسلسلة الحروف المُمرّرة، وفي حال إعطاء القيمة true للوسيط ignoreCase فستتجاهل الدالة حالة الحروف (لن تفرّق بين الحروف الكبيرة والصغيرة). الدالة أيضًا لا تُقسّم الأزواج البديلة (surrogate pairs)، وإن لم تكن بينهما لاحقة مشتركة فستعيد سلسلة نصية فارغة.

compareTo

تقارن الدالة compareTo()‎ بين سلسلتين نصيتين، مع إمكانية تجاهل حالة الأحرف عبر إعطاء القيمة true للوسيط ignoreCase.

concat

تضم الدالة concat()‎ السلسلة النصية التي استُدعيت عبرها إلى السلسلة النصية المُمرّرة وتعيد السلسلة النصية الناتجة.

contains

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

contentEquals

تعيد الدالة contentEquals()‎ القيمة true إن كانت السلسلة النصية التي استُدعيت عبرها تساوي سلسلة الحروف أو الكائن (StringBuffer) المُمرّر.

count

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

decapitalize

تعيد الدالة decapitalize()‎ نسخة من السلسلة النصية التي استُدعيت عبرها، مع جعل الحرف الأول صغيرا (lowercase).

drop

تعيد الدالة drop()‎ جزءًا من السلسلة النصية أو سلسلة الحروف التي استُدعيت عبرها مع حذف أول n حرفًا.

dropLast

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

dropLastWhile

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

dropWhile

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

elementAt

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

elementAtOrElse

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

elementAtOrNull

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

endsWith

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

equals

تعيد الدالة equals()‎ القيمة true في حال كان الحرف أو السلسلة النصية التي استُدعيت عبرها مساوية للحرف أو السلسلة النصية المُمرّرة إليها. في حال تمرير الوسيط ignoreCase وإعطائه القيمة true فإنّ الدالة لن تفرق بين الحروف الصغيرة والكبيرة. القيمة الابتدائية للوسيط ignoreCase هيfalse.

filter

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

filterIndexed

تعيد الدالة filterIndexed()‎ كل الحروف من سلسلة الحروف التي استُدعيت عبرها والتي تحقق الشرط المنطقي. يمرَّر فهرس كل عنصر وقيمته إلى الدالة predicate()‎ ثم تعيد بدورها قيمة منطقيَّة.

filterIndexedTo

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

filterNot

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

filterNotTo

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

filterTo

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

find

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

findAnyOf

تبحث الدالة findAnyOf()‎ عن أول ظهور لأي واحدة من السلاسل النصية الموجودة في الوسيط المُمرّر strings في سلسلة الحروف التي استُدعيت عبرها بداية من الفهرس startIndex، وفي حال إعطاء القيمة true للوسيط ignoreCase فستتجاهل الدالة حالة الحروف.

findLast

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

findLastAnyOf

تبحث الدالة findLastAnyOf()‎ عن آخر ظهور لأي واحدة من السلاسل النصية الموجودة في الوسيط المُمرّر strings في سلسلة الحروف التي استُدعيت عبرها بداية من الفهرس startIndex، وفي حال إعطاء القيمة true للوسيط ignoreCase فستتجاهل الدالة حالة الحروف.

first

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

firstOrNull

تعيد الدالة firstOrNull()‎ الحرف الأول من سلسلة الحروف التي استُدعيت عبرها، وفي حال تمرير دالة منطقية predicate كوسيط فستعيد الحرفالأول الذي يحقق الشرط المنطقي predicate.

flatMap

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

flatMapTo

تضيف الدالةflatMapTo()‎ إلى اللائحة المُتغيرة‎ (MutableCollection‎) ‎destinationالمُمرّرة إليها ناتج تطبيق الدالة transform()‎ على عناصر  سلسلة الحروف التي استُدعيت عبرها.

fold

تُراكِم الدالةfold()‎ القيم بدءًا من القيمة المُمرّرة initial وتطبّق العملية operation من اليسار إلى اليمين على القيمة الراهنة وعلى الحرف الموالي في  سلسلة الحروف التي استُدعيت عبرها. ثم تُعيد القيمة النهائية.

foldIndexed

تُراكِم الدالةfoldIndexed()‎ القيم بدءًا من القيمة المُمرّرة initial وتطبّق العملية operation من اليسار إلى اليمين على القيمة الراهنة وعلى الحرف الموالي في  سلسلة الحروف التي استُدعيت عبرها وكذلك فهرسه. ثم تُعيد القيمة النهائية.

foldRight

تُراكِم الدالةfoldRight()‎ القيم بدءًا من القيمة المُمرّرة initial وتطبّق العملية operation من اليمين إلى اليسار على القيمة الراهنة وعلى الحرف الموالي في  سلسلة الحروف التي استُدعيت عبرها. ثم تُعيد القيمة النهائية.

foldRightIndexed

تُراكِم الدالةfoldRightIndexed()‎ القيم بدءًا من القيمة المُمرّرة initial وتطبّق العملية operation من اليمين إلى اليسار على القيمة الراهنة وعلى الحرف الموالي في  سلسلة الحروف التي استُدعيت عبرها وكذلك فهرسه. ثم تُعيد القيمة النهائية.

forEach

تنفّذ الدالةُforEach()‎ الدالةَ المُمرّرة action على عناصر سلسلة الحروف التي استُدعيت عبرها.

forEachIndexed

تنفّذ الدالةُforEachIndexed()‎ الدالةَ المُمرّرة action على عناصر سلسلة الحروف التي استُدعيت عبرها وعلى فهارسها.

format

يختلف سلوك حسب نوع وعدد الوسائط المُمرّرة إليها (انظر فقرة البنية العامة).

get

تعيد الدالةget()‎ كائنا من النوع MatchGroup إن كانت المجموعة التي تحمل الإسم المُمرّر name مطابقَة، وإلا فستعيد null. المجموعات مفهرسة من 1 وحتى عدد المجموعات في التعبير النمطي، المجموعة ذات الفهرس 0 تقابل المطابقة الكلية.

getOrElse

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

getOrNull

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

groupBy

تعيد الدالةgroupBy()‎ قاموسًا يُجمّع حروف سلسلة الحروف التي استُدعيت عبرها حيث مفاتيحه تعيدها الدالة المُمرّرة keySelector وقيمه لوائحُ تضم عناصر سلسلة الحروف (أو ناتج تمرير عناصرها على الدالة valueTransform في حال تمريرها).

groupByTo

تجمّع الدالةgroupByTo()‎ عناصر  سلسلة الحروف التي استُدعيت عبرها وتضيفها إلى القاموس المُمرّر destination حيث مفاتيحه تعيدها الدالة الممرّرة keySelector()‎ مُطبّقة على كل عناصر  سلسلة الحروف، وقيمُه لوائح تضم العناصر المقابلة، وفي حال تمرير معامل ثالث valueTransform فإنّ القيم ستكون لوائح تضم ناتج تطبيق الدالة valueTransform على العناصر المقابلة . ثم تعيد القاموسdestination.

groupingBy

تُنشئ الدالةgroupingBy()‎ كائنًا من النوع Grouping من  سلسلة الحروف التي استُدعيت عبرها لاستخدامه لاحقًا مع عمليات المجموعات (group-and-fold operations)، وذلك باستخدام الدالة المُمرّرة keySelector لاستخلاص مفتاح من كل عنصر .

hasSurrogatePairAt

تعيد الدالةhasSurrogatePairAt()‎ القيمة true إن كان لدى سلسلة الحروف التي استُدعيت عبرها زوج يونيكود بديل (Unicode surrogate pair) عند الفهرس المُحدّد.

indexOf

تعيد الدالة indexOf()‎ فهرس أول ظهور للحرف أو السلسلة النصية المُمرّرة إليها في سلسلة الحروف التي استُدعيت عبرها بداية من الفهرس المُمرّرstartIndex، في حال كان ذلك الحرف غير موجود فستعيد العدد ‎-1.

indexOfAny

تعيد الدالة indexOfAny()‎ فهرس أول ظهور لأيّ من الحروف أو السلاسل النصية الواردة في الوسيط المُمرّر (chars أو strings)، 

indexOfFirst

تعيد الدالة indexOfFirst()‎ فهرس ظهور أول حرف في سلسلة الحروف التي استُدعيت عبرها والذي يحقق الشرط المنطقي predicate، وفي حال كان ذلك الحرف غير موجود فستعيد العدد ‎-1.

indexOfLast

تعيد الدالة indexOfLast()‎ فهرس ظهور آخر حرف في سلسلة الحروف التي استُدعيت عبرها والذي يحقق الشرط المنطقي predicate، وفي حال كان ذلك الحرف غير موجود فستعيد العدد ‎-1. 

intern

تعيد الدالة intern()‎ تمثيلا قانونيا للسلسلة النصية التي استُدعيت عبرها.

isBlank

تعيد الدالة isBlank()‎ القيمة true في حال كانت سلسلة الحروف التي استٌدعيت عبرها فارغة أو مكونة حصريا من المسافات البيضاء (whitespace characters).

isDefined

تعيد الدالة isDefined()‎ القيمة true في حال كان كود الحرف (Unicode code point) الذي استٌدعيت عبره مُعرّفًا في اليونيكود (Unicode).

isDigit

تعيد الدالة isDigit()‎ القيمة true في حال كان الحرف الذي استٌدعيت عبره رقمًا.

isEmpty

تعيد الدالة isEmpty()‎ القيمة true في حال كانت سلسلة الحروف التي استٌدعيت عبرها فارغة.

isHighSurrogate

تعيد الدالة isHighSurrogate()‎ القيمة true في حال كان الحرف الذي استٌدعيت عبره بديلًا علويًا (Unicode high-surrogate code unit).

isISOControl

تعيد الدالة isISOControl()‎ القيمة true في حال كان الحرف الذي استٌدعيت عبره من حروف الضبط ISO ‎‎‏ ‎ISO control character)‎‎‎).

isIdentifierIgnorable

تعيد الدالة isIdentifierIgnorable()‎ القيمة true في حال كان الحرف الذي استٌدعيت عبره يجب أن يُهمل في مُعرِّفات جافا (Java identifier) أو اليونيكود.