String.prototype.toWellFormed()

Метод toWellFormed() значений String возвращает строку, в которой все одиночные суррогаты этой строки заменены символом замены Unicode U+FFFD.

Синтаксис

toWellFormed()

Параметры

Нет.

Возвращаемое значение

Новая строка, которая является копией текущей строки, в которой все одиночные суррогаты заменены символом замены Unicode U+FFFD. Если str является правильно сформированной, новая строка все равно возвращается (по сути, копия str).

Описание

Строки в JavaScript кодируются в UTF-16. Кодирование UTF-16 использует концепцию суррогатных пар, которая подробно представлена в разделе Символы UTF-16, кодовые точки Unicode и кластеры графем.

toWellFormed() перебирает кодовые единицы этой строки и заменяет все одиночные суррогаты на символ замены Unicode U+FFFD �. Это гарантирует, что возвращаемая строка является правильно сформированной и может использоваться в функциях, которые ожидают правильно сформированные строки, таких как encodeURI. По сравнению с пользовательской реализацией, toWellFormed() более эффективен, поскольку движки могут напрямую обращаться к внутреннему представлению строк.

Когда неправильно сформированные строки используются в определенных контекстах, например, в TextEncoder, они автоматически преобразуются в правильно сформированные строки с использованием того же символа замены. Когда одиночные суррогаты отображаются, они также отображаются как символ замены (ромб с вопросительным знаком внутри).

Примеры

Использование toWellFormed()

const strings = [
  // Lone leading surrogate
  "ab\uD800",
  "ab\uD800c",
  // Lone trailing surrogate
  "\uDFFFab",
  "c\uDFFFab",
  // Well-formed
  "abc",
  "ab\uD83D\uDE04c",
];

for (const str of strings) {
  console.log(str.toWellFormed());
}
// Logs:
// "ab�"
// "ab�c"
// "�ab"
// "c�ab"
// "abc"
// "ab😄c"

Предотвращение ошибок в encodeURI()

encodeURI генерирует ошибку, если переданная строка не является правильно сформированной. Этого можно избежать, используя toWellFormed() для предварительного преобразования строки в правильно сформированную строку.

const illFormed = "https://example.com/search?q=\uD800";

try {
  encodeURI(illFormed);
} catch (e) {
  console.log(e); // URIError: URI malformed
}

console.log(encodeURI(illFormed.toWellFormed())); // "https://example.com/search?q=%EF%BF%BD"

Спецификации

Совместимость с браузерами

Смотрите также

• Полифил String.prototype.toWellFormed в core-js
• Полифил es-shims для String.prototype.toWellFormed
• String.prototype.isWellFormed()
• String.prototype.normalize()