> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kayanos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# دوال القوائم

> جميع دوال القوائم المسجلة، مع التواقيع والأمثلة للاختيارات والسجلات المرتبطة والإجماليات والنتائج المرتبة.

## متى تستخدم هذه الدوال؟

استخدم هذه الدوال عندما يعيد الحقل أو التعبير قائمة. اعتبر القائمة الفارغة حالة طبيعية وحدد بوضوح ما ينبغي أن يراه المستخدم عند غياب السجلات المرتبطة.

## طريقة الكتابة

استخدم الدالة بصيغة `sum($.fee_items)`. لا تكون كل دالة متاحة في كل مكان: دوال التحقق ودوال النموذج ودوال قالب المستند لها عقود سياق مختلفة. لا تفترض أن اقتراح المحرر يعني أن الدالة مدعومة وقت التشغيل.

## مرجع الدوال الكامل

### `at`

تعيد العنصر الموجود في الموضع المحدد من القائمة، أو قيمة فارغة إذا لم يوجد.

**التوقيع:** `at(arr, index)`

**مثال:**

```txt theme={null}
at([1, 2, 3], 1) // 2
```

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | at(...)`.

### `average`

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

**التوقيع:** `average(...args)`

**مثال:**

```txt theme={null}
average([1, 2, 3, 4]) // 2.5
```

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | average(...)`.

### `chunk`

تقسم القائمة إلى قوائم أصغر بالحجم المحدد.

**التوقيع:** `chunk(arr, size)`

**مثال:**

```txt theme={null}
chunk([1, 2, 3, 4, 5, 6], 2) // [[1, 2], [3, 4], [5, 6]]
```

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | chunk(...)`.

### `compact`

تزيل القيم الفارغة أو غير الصادقة من القائمة وفق تنفيذ الدالة.

**التوقيع:** `compact(arr)`

**مثال:**

```txt theme={null}
compact([0, 1, false, 2, "", 3]) // [1, 2, 3]
```

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | compact(...)`.

### `concat`

تضم قائمتين أو أكثر في قائمة واحدة.

**التوقيع:** `concat(...arrays)`

**مثال:**

```txt theme={null}
concat([1, 2], [3, 4]) // [1, 2, 3, 4]
```

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | concat(...)`.

### `countBy`

تجمع عناصر القائمة بعددها وفق مفتاح أو دالة تجميع معطاة.

**التوقيع:** `countBy(arr)`

**مثال:**

```txt theme={null}
countBy([1, 2, 2, 3]) // { '1': 1, '2': 2, '3': 1 }
```

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | countBy(...)`.

### `difference`

تعيد العناصر الموجودة في القائمة الأولى وغير الموجودة في القوائم الأخرى.

**التوقيع:** `difference(...arrays)`

**مثال:**

```txt theme={null}
difference([1, 2, 3], [2, 3]) // [1]
```

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | difference(...)`.

### `every`

تتحقق من أن كل عناصر القائمة تحقق الشرط أو الاختبار المعطى.

**التوقيع:** `every(arr)`

**مثال:**

```txt theme={null}
every([1, 2, 3]) // true
```

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | every(...)`.

### `fill`

تنشئ أو تعدل قائمة بملء نطاق منها بالقيمة المعطاة.

**التوقيع:** `fill(value, length)`

**مثال:**

```txt theme={null}
fill(0, 5) // [0, 0, 0, 0, 0]
```

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | fill(...)`.

### `first`

تعيد أول عنصر من القائمة.

**التوقيع:** `first(arr)`

**مثال:**

```txt theme={null}
first([1, 2, 3]) // 1
```

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | first(...)`.

### `flatten`

تسطح مستوى واحداً من قائمة متداخلة.

**التوقيع:** `flatten(arr)`

**مثال:**

```txt theme={null}
flatten([[1, 2], [3, 4]]) // [1, 2, 3, 4]
```

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | flatten(...)`.

### `flattenDeep`

تسطح كل مستويات القائمة المتداخلة.

**التوقيع:** `flattenDeep(arr)`

**مثال:**

```txt theme={null}
flattenDeep([[1, [2]], [3, 4]]) // [1, 2, 3, 4]
```

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | flattenDeep(...)`.

### `getByPath`

تقرأ قيمة متداخلة من كائن أو قائمة عبر مسار نصي آمن.

**التوقيع:** `getByPath(value, path)`

**مثال:**

```txt theme={null}
getByPath({user:{name:'John'}}, 'user.name') // 'John'
```

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | getByPath(...)`.

### `intersection`

تعيد العناصر المشتركة بين القوائم المعطاة.

**التوقيع:** `intersection(...arrays)`

**مثال:**

```txt theme={null}
intersection([1, 2, 3], [2, 3]) // [2, 3]
```

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | intersection(...)`.

### `join`

تضم عناصر القائمة في نص واحد باستخدام فاصل.

**التوقيع:** `join(arr, separator?)`

**مثال:**

```txt theme={null}
join([1, 2, 3], ", ") // "1, 2, 3"
```

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | join(...)`.

### `last`

تعيد آخر عنصر من القائمة.

**التوقيع:** `last(arr)`

**مثال:**

```txt theme={null}
last([1, 2, 3]) // 3
```

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | last(...)`.

### `max`

تعيد أكبر قيمة من قائمة أو من قيم متغيرة العدد. هذه هي صيغة القائمة الفعالة في التسجيل النهائي.

**التوقيع:** `max(values) or max(...values)`

**مثال:**

```txt theme={null}
max([$.inspection_fee, $.processing_fee])
```

**التوافر:** دالة عامة in shared builder and document-template runtimes; function and transform forms are available.

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | max(...)`.

### `min`

تعيد أصغر قيمة من قائمة أو من قيم متغيرة العدد. هذه هي صيغة القائمة الفعالة في التسجيل النهائي.

**التوقيع:** `min(values) or min(...values)`

**مثال:**

```txt theme={null}
min([$.first_quote, $.second_quote])
```

**التوافر:** دالة عامة in shared builder and document-template runtimes; function and transform forms are available.

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | min(...)`.

### `none`

تتحقق من عدم وجود أي عنصر يحقق الشرط أو الاختبار المعطى.

**التوقيع:** `none(arr)`

**مثال:**

```txt theme={null}
none([0, null, false]) // true
```

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | none(...)`.

### `range`

تنشئ قائمة أرقام ضمن نطاق البداية والنهاية والخطوة المعطاة.

**التوقيع:** `range(start, end, step?)`

**مثال:**

```txt theme={null}
range(1, 5) // [1, 2, 3, 4, 5]
```

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | range(...)`.

### `sample`

تعيد عنصراً عشوائياً واحداً من القائمة؛ لا تستخدمها في قرار أو قيمة يجب أن تثبت.

**التوقيع:** `sample(arr)`

**مثال:**

```txt theme={null}
sample([1, 2, 3]) // 2
```

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | sample(...)`.

### `sampleSize`

تعيد عينة عشوائية بالحجم المطلوب من القائمة؛ لا تستخدمها في قيمة عمل محفوظة.

**التوقيع:** `sampleSize(arr, size)`

**مثال:**

```txt theme={null}
sampleSize([1, 2, 3, 4], 2) // [2, 4]
```

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | sampleSize(...)`.

### `shuffle`

تعيد نسخة عشوائية الترتيب من القائمة؛ لا تستخدمها في رقم أو قرار يجب أن يثبت.

**التوقيع:** `shuffle(arr)`

**مثال:**

```txt theme={null}
shuffle([1, 2, 3]) // [2, 1, 3]
```

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | shuffle(...)`.

### `slice`

تعيد جزءاً من القائمة بين موضعي البداية والنهاية.

**التوقيع:** `slice(arr, start, end?)`

**مثال:**

```txt theme={null}
slice([1, 2, 3, 4, 5], 1, 3) // [2, 3]
```

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | slice(...)`.

### `some`

تتحقق من وجود عنصر واحد على الأقل يحقق الشرط أو الاختبار المعطى.

**التوقيع:** `some(arr)`

**مثال:**

```txt theme={null}
some([0, 1, 2]) // true
```

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | some(...)`.

### `sortAsc`

تعيد نسخة من القائمة مرتبة تصاعدياً.

**التوقيع:** `sortAsc(arr)`

**مثال:**

```txt theme={null}
sortAsc([3, 1, 4, 1, 5]) // [1, 1, 3, 4, 5]
```

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | sortAsc(...)`.

### `sortBy`

تعيد نسخة من قائمة الكائنات مرتبة حسب قيمة حقل محدد.

**التوقيع:** `sortBy(arr, field?, direction?)`

**مثال:**

```txt theme={null}
sortBy([{id:2},{id:1}], "id", "asc") // [{id:1},{id:2}]
```

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | sortBy(...)`.

### `sortDesc`

تعيد نسخة من القائمة مرتبة تنازلياً.

**التوقيع:** `sortDesc(arr)`

**مثال:**

```txt theme={null}
sortDesc([3, 1, 4, 1, 5]) // [5, 4, 3, 1, 1]
```

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | sortDesc(...)`.

### `sum`

تجمع قيماً رقمية في قائمة أو في مدخلات متغيرة العدد. هذه هي صيغة القائمة الفعالة في التسجيل النهائي.

**التوقيع:** `sum(values) or sum(...values)`

**مثال:**

```txt theme={null}
sum([$.base_fee, $.inspection_fee])
```

**التوافر:** دالة عامة in shared builder and document-template runtimes; function and transform forms are available.

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | sum(...)`.

### `union`

تضم القوائم المعطاة وتزيل التكرارات.

**التوقيع:** `union(...arrays)`

**مثال:**

```txt theme={null}
union([1, 2], [2, 3]) // [1, 2, 3]
```

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | union(...)`.

### `unique`

تزيل العناصر المكررة من القائمة مع الاحتفاظ بالعناصر المميزة.

**التوقيع:** `unique(arr)`

**مثال:**

```txt theme={null}
unique([1, 2, 2, 3, 3, 3]) // [1, 2, 3]
```

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | unique(...)`.

### `zip`

تجمع العناصر المتناظرة من قوائم متعددة في قائمة من الصفوف.

**التوقيع:** `zip(...arrays)`

**مثال:**

```txt theme={null}
zip([1, 2], [3, 4]) // [[1, 3], [2, 4]]
```

**ملاحظة:** يمكن أيضاً كتابتها كتحويل عندما تكون القيمة الأولى هي المدخل: `value | zip(...)`.

## قائمة تحقق قبل النشر

* ابدأ بقيمة معروفة وتحقق من النتيجة المتوقعة.
* تعامل صراحةً مع القيم الفارغة وnull والقوائم الفارغة.
* لا تضع أسراراً أو رموز وصول أو بيانات شخصية حساسة داخل تعبير.
* راجع [سياقات وتوافر التعبيرات](/ar/reference/expressions/contexts) قبل نسخ تعبير بين ميزتين.

![دوال القوائم في KayanOS](https://kayanos.app/docs-images/ar/reference/expressions-helpers-array.png)