JavaScript/String/fromCodePoint

الدالة String.fromCodePoint()‎ الساكنة (static) تُعيد سلسلةً نصيةً مُنشَأةً باستخدام سلسلة من قيم المحارف (code points).

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

String.fromCodePoint(num1[, ...[, numN]])

num1, ..., numN

سلسلة من الأرقام التي تُمثِّل قيم المحارف (code points).

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

سلسلة نصية تحتوي على محارف ترتبط بقيم المحارف المُمرَّرة إلى الدالة.

الاستثناءات

سيرمى الاستثناء RangeError إذا مُرِّرَ قيمة محرف يونيكود غير صالحة (مثلًا: "RangeError: NaN is not a valid code point").

الوصف

هذه الدالة تُعيد سلسلةً نصيةً أوليّةً ولا تُعيد كائن String.

لمّا كانت الدالة fromCodePoint هي دالةٌ ساكنة (static method) تابعةٌ للكائن String، فيجب عليك استخدامها دومًا بالشكل String.fromCodePoint()‎، إذ لا تستطيع استخدامها كجزء من كائن String خاص بك.

أمثلة

الأمثلة الآتية تُبيّن استخدام الدالة fromCodePoint()‎:

String.fromCodePoint(42);       // "*"
String.fromCodePoint(65, 90);   // "AZ"
String.fromCodePoint(0x404);    // "\u0404"
String.fromCodePoint(0x2F804);  // "\uD87E\uDC04"
String.fromCodePoint(194564);   // "\uD87E\uDC04"
String.fromCodePoint(0x1D306, 0x61, 0x1D307) // "\uD834\uDF06a\uD834\uDF07"

String.fromCodePoint('_');      // RangeError
String.fromCodePoint(Infinity); // RangeError
String.fromCodePoint(-1);       // RangeError
String.fromCodePoint(3.14);     // RangeError
String.fromCodePoint(3e-2);     // RangeError
String.fromCodePoint(NaN);      // RangeError

الدالة String.fromCharCode()‎ لا يمكنها الحصول على المحارف التي تكون قيمها أكبر من الحد الأقصى، أما المثال الآتية فسيُعيد محرفًا بطول 4-بايت، إضافةً إلى محرفين بطول 2-بايت (أي أنها ستُعيد محرفًا واحدًا الذي يُمثِّل سلسلةً نصيةً طولها 2 بدلًا من 1):

console.log(String.fromCodePoint(0x2F804));

تعويض نقص دعم المتصفحات

الدالة String.fromCodePoint أُضيفَت في معيار ECMAScript 2015 (أي ES6)، وليست مدعومةً في جميع المتصفحات بعد، لذا يمكن استخدام الشيفرة الآتية لتعريفها:

/*! http://mths.be/fromcodepoint v0.1.0 by @mathias */
if (!String.fromCodePoint) {
  (function() {
    var defineProperty = (function() {
      // IE 8 only supports `Object.defineProperty` on DOM elements
      try {
        var object = {};
        var $defineProperty = Object.defineProperty;
        var result = $defineProperty(object, object, object) && $defineProperty;
      } catch(error) {}
      return result;
    }());
    var stringFromCharCode = String.fromCharCode;
    var floor = Math.floor;
    var fromCodePoint = function() {
      var MAX_SIZE = 0x4000;
      var codeUnits = [];
      var highSurrogate;
      var lowSurrogate;
      var index = -1;
      var length = arguments.length;
      if (!length) {
        return '';
      }
      var result = '';
      while (++index < length) {
        var codePoint = Number(arguments[index]);
        if (
          !isFinite(codePoint) ||       // `NaN`, `+Infinity`, or `-Infinity`
          codePoint < 0 ||              // not a valid Unicode code point
          codePoint > 0x10FFFF ||       // not a valid Unicode code point
          floor(codePoint) != codePoint // not an integer
        ) {
          throw RangeError('Invalid code point: ' + codePoint);
        }
        if (codePoint <= 0xFFFF) { // BMP code point
          codeUnits.push(codePoint);
        } else { // Astral code point; split in surrogate halves
          // http://mathiasbynens.be/notes/javascript-encoding#surrogate-formulae
          codePoint -= 0x10000;
          highSurrogate = (codePoint >> 10) + 0xD800;
          lowSurrogate = (codePoint % 0x400) + 0xDC00;
          codeUnits.push(highSurrogate, lowSurrogate);
        }
        if (index + 1 == length || codeUnits.length > MAX_SIZE) {
          result += stringFromCharCode.apply(null, codeUnits);
          codeUnits.length = 0;
        }
      }
      return result;
    };
    if (defineProperty) {
      defineProperty(String, 'fromCodePoint', {
        'value': fromCodePoint,
        'configurable': true,
        'writable': true
      });
    } else {
      String.fromCodePoint = fromCodePoint;
    }
  }());
}

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

الميزة	Chrome	Firefox	Internet Explorer	Opera	Safari
الدعم الأساسي	41	29	غير مدعومة	28	10

على النقيض من متصفح IE، يدعم متصفح Edge هذه الميزة.

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

• مسودة المعيار ECMAScript Latest Draft.
• معيار ECMAScript 2015 (6th Edition)‎.