عرض مصدر Python/Connection/create collation

<noinclude>{{DISPLAYTITLE:التابع <code>Connection.create_collation()‎</code> في بايثون}}</noinclude>

ينشئ التابع مقارنة collation يحمل الاسم المعطى مع الكائن القابل للاستدعاء المعطى. 

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

<syntaxhighlight lang="python3">
create_collation(name, callable)
</syntaxhighlight>

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

=== <code>name</code> ===
اسم المقارنة المراد إنشاؤها.

=== <code>callable</code> ===

كائن قابل للاستدعاء.

سيُمرّر وسيطان نصّيان إلى الكائن القابل للاستدعاء، وسيعيد النتيجة ‎<code>-1</code> إن كان ترتيب الوسيط الأول أدنى من الوسيط الثاني، ويعيد <code>0</code> إن كان الوسيطان متساويين، ويعيد <code>1</code> إن كان ترتيب الوسيط الأول أعلى من الوسيط الثاني. 

لاحظ أنّ هذه المقارنة تتحكّم في عبارة ([[SQL/order by|ORDER BY]] في [[SQL]]) لكي لا تؤثّر عمليات المقارنة على عمليات [[SQL]] الأخرى.

لاحظ أيضًا أنّ الكائن القابل للاستدعاء سيتلقّى معاملاته على هيئة سلاسل بايتات نصية، والتي سترمّز في العادة إلى الترميز UTF-8.

== أمثلة ==

يبين المثال التالي مقارنة خاصة تعمل على ترتيب النتائج "هذه ليست الطريقة الصحيحة لترتيب النتائج":

<syntaxhighlight lang="python3">
import sqlite3

def collate_reverse(string1, string2):
    if string1 == string2:
        return 0
    elif string1 < string2:
        return 1
    else:
        return -1

con = sqlite3.connect(":memory:")
con.create_collation("reverse", collate_reverse)

cur = con.cursor()
cur.execute("create table test(x)")
cur.executemany("insert into test(x) values (?)", [("a",), ("b",)])
cur.execute("select x from test order by x collate reverse")
for row in cur:
    print(row)
con.close()

</syntaxhighlight>

يمكن استدعاء التابع <code>create_collation()‎</code> مع تمرير القيمة <code>None</code> للمعامل <code>callable</code> لحذف المقارنة الحالية:

<syntaxhighlight lang="python3">
con.create_collation("reverse", None)
</syntaxhighlight>

== انظر أيضًا ==
* [[Python/Connection/create_function|التابع <code>Connection.create_function()‎</code>]]:ينشئ التابع دالة معرفة من قبل المستخدم يمكن استعمالها لاحقًا ضمن جمل [[SQL|SQL]].
* [[Python/Connection/create_aggregate|التابع <code>Connection.create_aggregate()‎</code>]]:ينشئ التابع دالة تجميع aggregate function معرّفة من قبل المستخدم.

== مصادر ==
[https://docs.python.org/3/library/sqlite3.html#sqlite3.Connection.create_collation صفحة DB-API 2.0 interface for SQLite databases في توثيق بايثون الرسمي.]

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