String.prototype.localeCompare()‎

الدالة String.prototype.localeCompare()‎ تُعيد رقمًا يُشير إذا ما كانت السلسلة النصية المُشار إليها تأتي قبل أو بعد أو بنفس ترتيب السلسلة النصية المُعطاة في ترتيبٍ معيّن.

الوسيطان الجديدان locales و options يسمحان للتطبيقات بتحديد اللغة التي سيُستخدَم الترتيب الخاص بها وتخصيص سلوك هذه الدالة؛ أما الإصدارات القيمة من هذه الدالة فستتجاهل الوسيطين locales و options وسيكون المحليّة (locale) والترتيب (sort) معتمدين تمامًا على المتصفح ونظام التشغيل.

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

referenceStr.localeCompare(compareString[, locales[, options]])

انظر إلى قسم دعم المتصفحات لتعرف ما هي المتصفحات التي تدعم الوسيطين locales و options.

compareString

السلاسل النصية التي نريد البحث مقارنتها مع السلسلة النصية المرجعية.

locales

وسيطٌ اختياريٌ، وهو سلسلة نصيةٌ تحتوي على رمز اللغة وفقًا لمعيار BCP 47، أو مصفوفة من تلك الرموز. يمكن استخدام مفاتيح يونيكود الآتية مع رمز اللغة:

co

القيم الممكنة هي "big5han" و "dict" و "direct" و "ducet" و "gb2312" و "phonebk" و "phonetic" و "pinyin" و "reformed" و "searchjl" و "stroke" و "trad" و "unihan". القيمتان "standard" و "search" سيتم تجاهلهما، إذ تُستعمَل الخاصية usage في الوسيط options بدلًا منها (انظر أدناه).

kn

تحديد هل سيُستخدم الترتيب الرقمي، أي أنَّ ‎"1" < "2" < "10"‎، القيم الممكنة هي "true" و "false"، ويمكن ضبط هذا الخيار عبر الخاصية options أو عبر مفتاح يونيكود، وإذا وّفرنا قيمةً لكليهما، فستؤخذ قيمة الخاصية options بالحسبان.

kf

تحديد إذا كانت ستأتي الحروف ذات الحالة الكبيرة أولًا أم الصغيرة أولًا، والقيم الممكنة هي "upper" أو "lower" أو "false" (أي استخدام القيمة الافتراضية). يمكن ضبط هذا الخيار عبر الخاصية options أو عبر مفتاح يونيكود، وإذا وّفرنا قيمةً لكليهما، فستؤخذ قيمة الخاصية options بالحسبان.

options

وسيطٌ اختياريٌ، وهو كائنٌ له بعض (أو كل) الخاصيات الآتية:

localeMatcher

تحديد خوارزمية مُطابقة المحليّة (locale) التي ستُستخدَم. القيم الممكنة هي "lookup" و "best fit"؛ والقيمة الافتراضية هي "best fit".

usage

تحديد إذا كانت المقارنة ستُستخدَم للترتيب أو للبحث عن مطابقات لسلاسل نصية. القيم الممكنة هي "sort" و "search" والقيمة الافتراضية هي "sort".

sensitivity

ما هي الاختلافات بين السلسلتين النصيتين التي ستؤدي إلى قيم غير صفرية، القيم الممكنة هي:

• "base": ستختلف السلاسل النصية في أساس الحرف فقط، مثلًا: a ≠ b, a = á, a = A.
• "accent": ستختلف السلاسل النصية إذا اختلف أساس الحرف والحركات، مثلًا: a ≠ b, a ≠ á, a = A.
• "case": ستختلف السلاسل النصية إذا اختلف أساس الحرف وحالته. مثلًا: a ≠ b, a = á, a ≠ A.
• "variant": ستختلف السلاسل النصية إذا اختلف أساس الحرف وحالته والحركة. مثلًا: a ≠ b, a ≠ á, a ≠ A.

القيمة الافتراضية هي "variant" إذا كان الاستخدام (usage) هو "sort"، وستعتمد على ضبط المحليّة (locale) إذا كان الاستخدام هو "search".

ignorePunctuation

تحديد إذا كان سيتم تجاهل علامات الترقيم، والقيم الممكنة هي true و false، والقيمة الافتراضية هي false.

numeric

تحديد هل سيُستخدم الترتيب الرقمي، أي أنَّ ‎"1" < "2" < "10"‎، القيم الممكنة هي "true" و "false"، ويمكن ضبط هذا الخيار عبر الخاصية options أو عبر مفتاح يونيكود، وإذا وّفرنا قيمةً لكليهما، فستؤخذ قيمة الخاصية options بالحسبان.

caseFirst

تحديد إذا كانت ستأتي الحروف ذات الحالة الكبيرة أولًا أم الصغيرة أولًا، والقيم الممكنة هي "upper" أو "lower" أو "false" (أي استخدام القيمة الافتراضية). يمكن ضبط هذا الخيار عبر الخاصية options أو عبر مفتاح يونيكود، وإذا وّفرنا قيمةً لكليهما، فستؤخذ قيمة الخاصية options بالحسبان.

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

عدد سالب إذا كانت السلسلة النصية المرجعية تقع قبل السلسلة النصية التي تجري المقارنة معها، وعددٌ موجب إذا كانت تقع السلسلة النصية المرجعية بعد السلسلة النصية التي تجري المقارنة معها، و 0 إذا كانتا متساويتين.

الوصف

تُعيد هذه الدالة عددًا صحيحًا يُشير إذا ما كانت السلسلة النصية referenceStr تأتي قبل أو بعد أو تكافئ السلسلة النصية compareStr.

• عدد سالب عندما تأتي referenceStr قبل compareStr
• عدد موجب عندما تأتي referenceStr بعد compareStr
• 0 عندما تكون السلاستان النصيتان متكافئتين.

لا تعتمد على القيم -1 و 1، فالقيم الموجبة والسالبة المُعادة من هذه الدالة تختلف بين المتصفحات (وحتى بين إصدارات المتصفح نفسه)، ذلك لأنَّ مواصفة W3C قالت أنَّ القيمة يجب أن تكون سالبة أو موجبة، ولم تُحدِّد القيمة الدقيقة لها، لذا قد تُعيد بعض المتصفحات القيمة -2 أو 2 أو غيرها.

أمثلة

استخدام localeCompare()‎

الحرف "a" يقع قبل الحرف "c"، لذا ستنتج قيمة سالبة (-2 أو -1 أو قيمة سالبة أخرى):

'a'.localeCompare('c'); // -1

الكلمة "check" تقع -هجائيًا- بعد الكلمة "against" مما يُنتِج عددًا موجبًا:

'check'.localeCompare('against'); // 1

الحرف "a" يكافئ الحرف "a"، مما يُنتِج القيمة 0:

'a'.localeCompare('a'); // 0

ترتيب مصفوفة

تسمح الدالة localeCompare بترتيب المصفوفات دون أخذ حالة الأحرف بالحسبان. راجع صفحة الدالة sort والدوال السهمية لمزيدٍ من المعلومات:

var items = ['réservé', 'premier', 'cliché', 'communiqué', 'café', 'adieu'];
items.sort((a, b) => a.localeCompare(b)); // ['adieu', 'café', 'cliché', 'communiqué', 'premier', 'réservé']

التحقق من دعم الوسيطين locales و options

الوسيطان locales و options أصبحا مدعومين حديثًا؛ وللتحقق إن كان المتصفح يدعمها فيمكننا استخدام كتلة try...catch، إذ إنَّ رموز اللغات غير الصالحة ستُرفضَ من هذه الدالة وستؤدي إلى رمي الاستثناء RangeError:

function localeCompareSupportsLocales() {
  try {
    'foo'.localeCompare('bar', 'i');
  } catch (e) {
    return e.name === 'RangeError';
  }
  return false;
}

استخدام الوسيط locales

النتائج التي توفِّرها الدالة localeCompare تختلف بين اللغات، ولضمان استخدام اللغة التي نشاء، فاحرص على تحديد تلك اللغة باستخدام الوسيط locales:

console.log('ä'.localeCompare('z', 'de')); // قيمة سالبة في الألمانية
console.log('ä'.localeCompare('z', 'sv')); // قيمة موجبة في السويدية

استخدام الوسيط options

يمكن تخصيص النتائج التي توفِّرها الدالة localeCompare باستخدام الوسيط options. مثلًا، المحرفان a و ä لهما نفس الأساس في الألمانية، بينما يكونان منفصلين تمامًا في السويدية:

// الألمانية
console.log('ä'.localeCompare('a', 'de', { sensitivity: 'base' })); // 0

// السويدية
console.log('ä'.localeCompare('a', 'sv', { sensitivity: 'base' })); // قيمة موجبة

دعم المتصفحات

الميزة	Chrome	Firefox	Internet Explorer	Opera	Safari
الدعم الأساسي	نعم	نعم	نعم	نعم	نعم

مصادر ومواصفات

• مسودة ECMAScript Internationalization API 4.0.
• معيار ECMAScript Internationalization API 2.0.
• معيار ECMAScript Internationalization API 1.0. عرّف هذا المعيار الوسيطين locales و options.
• مسودة المعيار ECMAScript Latest Draft.
• معيار ECMAScript 2015 (6th Edition)‎.
• معيار ECMAScript 5.1.
• معيار ECMAScript 3rd Edition .