Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

CKTIS / JavaScript

String.prototype.codePointAt — odczyt punktu kodowego

Metoda codePointAt(pos) zwraca liczbową wartość punktu kodowego zaczynającego się pod wskazanym indeksem UTF-16. Rozpoznaje pary surogatów, ale indeks nadal oznacza jednostkę kodową, a nie kolejny znak widoczny na ekranie.

Wersja: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Składnia

string.codePointAt(pos)

String.prototype.codePointAt odczytuje punkt kodowy od indeksu pos liczonego od zera. Zwraca Number z zakresu 0–0x10FFFF albo undefined, gdy indeks jest poza napisem. Nie zmienia napisu.

Indeksy oraz length dotyczą jednostek kodowych UTF-16. Jeśli pod indeksem zaczyna się poprawna para surogatów, metoda łączy jej dwie jednostki w jeden punkt kodowy. W przeciwnym razie zwraca wartość pojedynczej jednostki, także izolowanego surogatu. Wywołanie na drugim elemencie pary zwraca wartość dolnego surogatu; nie cofa się do początku pary. Natomiast charCodeAt zawsze odczytuje jedną jednostkę i poza zakresem zwraca NaN.

Przed sprawdzeniem zakresu metoda przekształca argument pos przez ToIntegerOrInfinity: pominięcie argumentu lub NaN oznacza 0, a część ułamkowa jest odrzucana w stronę zera. Wynikowy indeks ujemny, nieskończony albo nie mniejszy niż length daje undefined. W pustym napisie każdy indeks uzyskany po udanym przekształceniu jest poza zakresem. Jeśli jednak przekształcenie zgłosi wyjątek, metoda go przekazuje nawet dla pustego napisu: na przykład "".codePointAt(0n) zgłasza TypeError.

Nie traktuj zwiększania indeksu o jeden jako przechodzenia po punktach kodowych: można w ten sposób wejść w środek pary. Punkt kodowy nie musi też odpowiadać całemu znakowi widocznemu na ekranie. Jest to metoda ECMAScript, nie API przeglądarki; sam standard nie potwierdza obsługi w konkretnej przeglądarce.

Przykłady

const text = "A\u{1F600}B";
console.log(text.length);
console.log(text.codePointAt(1));
console.log(text.charCodeAt(1));
console.log(text.codePointAt(2));
console.log(text.codePointAt(4));

Wynik

4
128512
55357
56832
undefined

Wyświetlony kod i zadeklarowany wynik zweryfikowano w odizolowanym środowisku metodą zapisaną w dowodzie weryfikacji tej dokładnej wersji.

Źródła