الدالة itertools.permutations()‎ في بايثون

تعيد الدّالة itertools.permutations()‎ تبادلات مُتتابعةً بطول مُعيّن من عناصر الكائن القابل للتّكرار المُعطى.

تُنتَج التّبادلات حسب الترتيب المُعجميّ (lexicographic). ما يعني بأنّ الصّفوف النّاتجة ستكون مُرتّبةً إن كان الكائن القابل للتّكرار المُعطى مُرتّبًا.

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

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

itertools.permutations(iterable, r=None)

المعاملات

iterable

الكائن القابل للتّكرار.

r

طول التّبادلات التي ستُنتَج. قيمته الافتراضيّة هي القيمة None إن لم تُمرّر له أيّة قيمة، فستكون قيمته هي طول الكائن iterable وستُولَّد جميع التّبادلات كاملة الطّول (full-length) المُمكنة.

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

صفوف بالطول المُعطى للمُعامل r تحتوي على تبادلات للعناصر المتواجدة في الكائن القابل للتّكرار المُعطى.

أمثلة

المثال التّالي يوضّح كيفيّة عمل هذه الدّالة:

>>> list(itertools.permutations('ABC', 2))
[('A', 'B'), ('A', 'C'), ('B', 'A'), ('B', 'C'), ('C', 'A'), ('C', 'B')]

ملاحظات

الدّالة مُكافئة لما يلي:

def permutations(iterable, r=None):
    # permutations('ABCD', 2) --> AB AC AD BA BC BD CA CB CD DA DB DC
    # permutations(range(3)) --> 012 021 102 120 201 210
    pool = tuple(iterable)
    n = len(pool)
    r = n if r is None else r
    if r > n:
        return
    indices = list(range(n))
    cycles = list(range(n, n-r, -1))
    yield tuple(pool[i] for i in indices[:r])
    while n:
        for i in reversed(range(r)):
            cycles[i] -= 1
            if cycles[i] == 0:
                indices[i:] = indices[i+1:] + indices[i:i+1]
                cycles[i] = n - i
            else:
                j = cycles[i]
                indices[i], indices[-j] = indices[-j], indices[i]
                yield tuple(pool[i] for i in indices[:r])
                break
        else:
            return

يُمكن كذلك تمثيل شيفرة الدّالة itertools.permutations()‎ كتسلسل فرعيّ للدّالة itertools.product بعد ترشيحها لإزالة الخانات التي تحتوي على عناصر مُكرَّرة (أي تلك التي لديها نفس الموقع في مسبح المُدخلات):

def permutations(iterable, r=None):
    pool = tuple(iterable)
    n = len(pool)
    r = n if r is None else r
    for indices in product(range(n), repeat=r):
        if len(set(indices)) == r:
            yield tuple(pool[i] for i in indices)

عدد العناصر المُعادة هو n! / r! / (n-r)!‎ عند 0 <= r <= n أو صفرًا عند r > n.

انظر أيضًا

• المكرِّرات Iterators في بايثون
• المولدات Generators في بايثون.
• itertools.product: تُعيد حاصل الضرب المباشر.

مصادر

• قسم الدالة itertools.permutations في توثيق Python الرسمي.