عرض مصدر Python/heapq/merge

<noinclude>{{DISPLAYTITLE:الدالة <code>heapq.merge()‎</code> في بايثون}}</noinclude>

تدمج الدالة عدة مدخلات مفروزة في مخرج مفرد مفروز . (على سبيل المثال: دمج عناصر ذات ختم زمني من ملفات تسجيل متعددة).

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

<syntaxhighlight lang="python3">
heapq.merge(*iterables, key=None, reverse=False)
</syntaxhighlight>

== المعاملات ==

=== ‎<code>*iterables</code> ===
يجب أن تكون جميع المُكرَّرات <code>iterables</code> مفروزة من الأكبر إلى الأصغر.

=== <code>key</code> ===
معامل اختياري يجب تعيينه كمعامل مفتاحي، يحدّد هذا المعامل دالة مفتاحية <code>key function</code> ذات معامل واحد تستخدم في استخلاص مفتاح مقارنة من كل عنصر في مدخلات الدالة. القيمة الافتراضية لهذا المعامل هي <code>None</code> وتجرى مقارنة العناصر على نحو مباشر حينئذٍ.

=== <code>reverse</code> ===
معامل اختياري يجب تعيينه كمعامل مفتاحي، ويحمل قيمة منطقية. إن أخذ المعامل القيمة <code>True</code>، فإنّ عناصر المدخلات تُدمج كما لو أنّ كل مقارنة كانت معكوسة. للحصول على سلوك مشابه للدالة <code>sorted(itertools.chain(*iterables), reverse=True)</code>‎ يجب أن تكون جميع المكرِّرات مفروزة من الأكبر إلى الأصغر.

ملاحظة: أضيف المعاملان الاختياريان <code>key</code> و <code>reverse</code> إلى الدالة في الإصدار 3.5 من اللغة.

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

تعيد الدالة كائن تكرار <code>iterator</code> يمكن استخدامه للمرور على القيم المفروزة.

هذه الدالة مشابهة للدالة <code>sorted(itertools.chain(*iterables))</code>‎ ولكنّها تعيد كائن تكرار، ولا تدفع البيانات إلى الذاكرة دفعة واحدة، وتفترض أن كل المدخلات مفروزة أصلًا (من الأصغر إلى الأكبر).

== أمثلة ==

يبين المثال التالي آلية عمل التابع:

<syntaxhighlight lang="python3">
>>> import heapq
>>> l1 = [1, 3, 4, 5]
>>> l2 = [3, 5, 7, 9]
>>> l3 = heapq.merge(l1, l2)
>>> print(l3)
>>> print(list(l3))
[1, 3, 3, 4, 5, 5, 7, 9]
>>> l3 = heapq.merge(l1, l2, reverse=True)
>>> print(list(l3))
[3, 5, 7, 9, 1, 3, 4, 5]

</syntaxhighlight>

== انظر أيضًا ==
* الدالة [[Python/heapq/nlargest|<code>nlargest</code>()‎]]: تعيد الدالة قائمة تضمّ العدد المحدّد من أكبر العناصر في مجموعة البيانات dataset المعرّفة بواسطة كائن التكرار المعطى.
* الدالة [[Python/heapq/nsmallest|<code>nsmallest</code>()‎]]: تعيد الدالة قائمة تضمّ العدد المحدّد من أصغر العناصر في مجموعة البيانات dataset المعرّفة بواسطة  كائن التكرار المعطى.

== مصادر ==
[https://docs.python.org/3/library/heapq.html#heapq.merge صفحة General calendar-related functions في توثيق بايثون الرسمي.]

[[تصنيف:Python]]
[[تصنيف:Python Modules]]