For AI agents: the complete documentation index is available at /tc39-atlas/en/llms.txt, the full documentation bundle is available at /tc39-atlas/en/llms-full.txt, and this page is available as Markdown at /tc39-atlas/en/proposals/string-prototype-at.md.
TC39 Atlas
  • English

      • String.prototype.at ?

      Proposal details
      Proposal overview

      This proposal defines a polyfill for String.prototype.at, which extracts the code point at a given position in a string, returning an empty string if out of bounds. It includes a step-by-step algorithm handling surrogate pairs. The proposal was not upstreamed and a later, different proposal with changed semantics was adopted.

      Note

      The README below comes from the upstream repository and may contain outdated stage or status metadata. Use the proposal details above as the current source of truth.

      Note: This proposal was not upstreamed into the ECMAScript specification! This repository is kept for historical purposes. Years later, in November 2020, a distinct proposal adds String.prototype.at with different semantics.

      ES6/ES7 String.prototype.at polyfill Build status

      A robust & optimized ES3-compatible polyfill for the String.prototype.at proposal for ECMAScript 6/7.

      Spec bug ticket: https://bugs.ecmascript.org/show_bug.cgi?id=2073

      Spec proposal for String.prototype.at(pos)

      NOTE: Returns a single-element String containing the code point at element position pos in the String value resulting from converting the this object to a String. If there is no element at that position, the result is the empty String. The result is a String value, not a String object.

      When the at method is called with one argument pos, the following steps are taken:

      1. Let O be RequireObjectCoercible(this value).
      2. Let S be ToString(O).
      3. ReturnIfAbrupt(S).
      4. Let position be ToInteger(pos).
      5. ReturnIfAbrupt(position).
      6. Let size be the number of elements in S.
      7. If position < 0 or position ≥ size, return the empty String.
      8. Let first be the code unit at index position in the String S.
      9. Let cuFirst be the code unit value of the element at index 0 in the String first.
      10. If cuFirst < 0xD800 or cuFirst > 0xDBFF or position + 1 = size, then return first.
      11. Let cuSecond be the code unit value of the element at index position + 1 in the String S.
      12. If cuSecond < 0xDC00 or cuSecond > 0xDFFF, then return first.
      13. Let second be the code unit at index position + 1 in the string S.
      14. Let cp be (first – 0xD800) × 0x400 + (second – 0xDC00) + 0x10000.
      15. Return the elements of the UTF-16 Encoding (clause 6) of cp.

      NOTE: The at function is intentionally generic; it does not require that its this value be a String object. Therefore it can be transferred to other kinds of objects for use as a method.

      Installation

      In a browser:

      <script src="at.js"></script>

      Via npm:

      npm install string.prototype.at

      Then, in Node.js:

      require('string.prototype.at');

// On Windows and on Mac systems with default settings, case doesn’t matter,
// which allows you to do this instead:
require('String.prototype.at');

      Notes

      Polyfills and test suites for String.fromCodePoint, String.prototype.codePointAt are available, too.

      Author

      twitter/mathias
      Mathias Bynens

      License

      This polyfill is available under the MIT license.