ECMAScript® 2024 Language Specification

Draft ECMA-262 / February 15, 2024

B.2 Additional Built-in Properties

When the ECMAScript host is a web browser the following additional properties of the standard built-in objects are defined.

B.2.1 Additional Properties of the Global Object

The entries in Table 97 are added to Table 6.

Table 97: Additional Well-known Intrinsic Objects
Intrinsic Name Global Name ECMAScript Language Association
%escape% escape The escape function (B.2.1.1)
%unescape% unescape The unescape function (B.2.1.2)

B.2.1.1 escape ( string )

This function is a property of the global object. It computes a new version of a String value in which certain code units have been replaced by a hexadecimal escape sequence.

When replacing a code unit of numeric value less than or equal to 0x00FF, a two-digit escape sequence of the form %xx is used. When replacing a code unit of numeric value strictly greater than 0x00FF, a four-digit escape sequence of the form %uxxxx is used.

It is the %escape% intrinsic object.

It performs the following steps when called:

  1. Set string to ? ToString(string).
  2. Let len be the length of string.
  3. Let R be the empty String.
  4. Let unescapedSet be the string-concatenation of the ASCII word characters and "@*+-./".
  5. Let k be 0.
  6. Repeat, while k < len,
    1. Let C be the code unit at index k within string.
    2. If unescapedSet contains C, then
      1. Let S be C.
    3. Else,
      1. Let n be the numeric value of C.
      2. If n < 256, then
        1. Let hex be the String representation of n, formatted as an uppercase hexadecimal number.
        2. Let S be the string-concatenation of "%" and StringPad(hex, 2, "0", start).
      3. Else,
        1. Let hex be the String representation of n, formatted as an uppercase hexadecimal number.
        2. Let S be the string-concatenation of "%u" and StringPad(hex, 4, "0", start).
    4. Set R to the string-concatenation of R and S.
    5. Set k to k + 1.
  7. Return R.
 Note

The encoding is partly based on the encoding described in RFC 1738, but the entire encoding specified in this standard is described above without regard to the contents of RFC 1738. This encoding does not reflect changes to RFC 1738 made by RFC 3986.

B.2.1.2 unescape ( string )

This function is a property of the global object. It computes a new version of a String value in which each escape sequence of the sort that might be introduced by the escape function is replaced with the code unit that it represents.

It is the %unescape% intrinsic object.

It performs the following steps when called:

  1. Set string to ? ToString(string).
  2. Let len be the length of string.
  3. Let R be the empty String.
  4. Let k be 0.
  5. Repeat, while k < len,
    1. Let C be the code unit at index k within string.
    2. If C is the code unit 0x0025 (PERCENT SIGN), then
      1. Let hexDigits be the empty String.
      2. Let optionalAdvance be 0.
      3. If k + 5 < len and the code unit at index k + 1 within string is the code unit 0x0075 (LATIN SMALL LETTER U), then
        1. Set hexDigits to the substring of string from k + 2 to k + 6.
        2. Set optionalAdvance to 5.
      4. Else if k + 3 ≤ len, then
        1. Set hexDigits to the substring of string from k + 1 to k + 3.
        2. Set optionalAdvance to 2.
      5. Let parseResult be ParseText(StringToCodePoints(hexDigits), HexDigits[~Sep]).
      6. If parseResult is a Parse Node, then
        1. Let n be the MV of parseResult.
        2. Set C to the code unit whose numeric value is n.
        3. Set k to k + optionalAdvance.
    3. Set R to the string-concatenation of R and C.
    4. Set k to k + 1.
  6. Return R.

B.2.2 Additional Properties of the String.prototype Object

B.2.2.1 String.prototype.substr ( start, length )

This method returns a substring of the result of converting the this value to a String, starting from index start and running for length code units (or through the end of the String if length is undefined). If start is negative, it is treated as sourceLength + start where sourceLength is the length of the String. The result is a String value, not a String object.

It performs the following steps when called:

  1. Let O be ? RequireObjectCoercible(this value).
  2. Let S be ? ToString(O).
  3. Let size be the length of S.
  4. Let intStart be ? ToIntegerOrInfinity(start).
  5. If intStart = -∞, set intStart to 0.
  6. Else if intStart < 0, set intStart to max(size + intStart, 0).
  7. Else, set intStart to min(intStart, size).
  8. If length is undefined, let intLength be size; otherwise let intLength be ? ToIntegerOrInfinity(length).
  9. Set intLength to the result of clamping intLength between 0 and size.
  10. Let intEnd be min(intStart + intLength, size).
  11. Return the substring of S from intStart to intEnd.
 Note

This method 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.

B.2.2.2 String.prototype.anchor ( name )

This method performs the following steps when called:

  1. Let S be the this value.
  2. Return ? CreateHTML(S, "a", "name", name).

B.2.2.2.1 CreateHTML ( string, tag, attribute, value )

The abstract operation CreateHTML takes arguments string (an ECMAScript language value), tag (a String), attribute (a String), and value (an ECMAScript language value) and returns either a normal completion containing a String or a throw completion. It performs the following steps when called:

  1. Let str be ? RequireObjectCoercible(string).
  2. Let S be ? ToString(str).
  3. Let p1 be the string-concatenation of "<" and tag.
  4. If attribute is not the empty String, then
    1. Let V be ? ToString(value).
    2. Let escapedV be the String value that is the same as V except that each occurrence of the code unit 0x0022 (QUOTATION MARK) in V has been replaced with the six code unit sequence "&quot;".
    3. Set p1 to the string-concatenation of:
      • p1
      • the code unit 0x0020 (SPACE)
      • attribute
      • the code unit 0x003D (EQUALS SIGN)
      • the code unit 0x0022 (QUOTATION MARK)
      • escapedV
      • the code unit 0x0022 (QUOTATION MARK)
  5. Let p2 be the string-concatenation of p1 and ">".
  6. Let p3 be the string-concatenation of p2 and S.
  7. Let p4 be the string-concatenation of p3, "</", tag, and ">".
  8. Return p4.

B.2.2.3 String.prototype.big ( )

This method performs the following steps when called:

  1. Let S be the this value.
  2. Return ? CreateHTML(S, "big", "", "").

B.2.2.4 String.prototype.blink ( )

This method performs the following steps when called:

  1. Let S be the this value.
  2. Return ? CreateHTML(S, "blink", "", "").

B.2.2.5 String.prototype.bold ( )

This method performs the following steps when called:

  1. Let S be the this value.
  2. Return ? CreateHTML(S, "b", "", "").

B.2.2.6 String.prototype.fixed ( )

This method performs the following steps when called:

  1. Let S be the this value.
  2. Return ? CreateHTML(S, "tt", "", "").

B.2.2.7 String.prototype.fontcolor ( color )

This method performs the following steps when called:

  1. Let S be the this value.
  2. Return ? CreateHTML(S, "font", "color", color).

B.2.2.8 String.prototype.fontsize ( size )

This method performs the following steps when called:

  1. Let S be the this value.
  2. Return ? CreateHTML(S, "font", "size", size).

B.2.2.9 String.prototype.italics ( )

This method performs the following steps when called:

  1. Let S be the this value.
  2. Return ? CreateHTML(S, "i", "", "").

B.2.2.10 String.prototype.link ( url )

This method performs the following steps when called:

  1. Let S be the this value.
  2. Return ? CreateHTML(S, "a", "href", url).

B.2.2.11 String.prototype.small ( )

This method performs the following steps when called:

  1. Let S be the this value.
  2. Return ? CreateHTML(S, "small", "", "").

B.2.2.12 String.prototype.strike ( )

This method performs the following steps when called:

  1. Let S be the this value.
  2. Return ? CreateHTML(S, "strike", "", "").

B.2.2.13 String.prototype.sub ( )

This method performs the following steps when called:

  1. Let S be the this value.
  2. Return ? CreateHTML(S, "sub", "", "").

B.2.2.14 String.prototype.sup ( )

This method performs the following steps when called:

  1. Let S be the this value.
  2. Return ? CreateHTML(S, "sup", "", "").

B.2.2.15 String.prototype.trimLeft ( )

Note

The property "trimStart" is preferred. The "trimLeft" property is provided principally for compatibility with old code. It is recommended that the "trimStart" property be used in new ECMAScript code.

The initial value of the "trimLeft" property is %String.prototype.trimStart%, defined in 22.1.3.34.

B.2.2.16 String.prototype.trimRight ( )

Note

The property "trimEnd" is preferred. The "trimRight" property is provided principally for compatibility with old code. It is recommended that the "trimEnd" property be used in new ECMAScript code.

The initial value of the "trimRight" property is %String.prototype.trimEnd%, defined in 22.1.3.33.

B.2.3 Additional Properties of the Date.prototype Object

B.2.3.1 Date.prototype.getYear ( )

Note

The getFullYear method is preferred for nearly all purposes, because it avoids the “year 2000 problem.”

This method performs the following steps when called:

  1. Let dateObject be the this value.
  2. Perform ? RequireInternalSlot(dateObject, [[DateValue]]).
  3. Let t be dateObject.[[DateValue]].
  4. If t is NaN, return NaN.
  5. Return YearFromTime(LocalTime(t)) - 1900𝔽.

B.2.3.2 Date.prototype.setYear ( year )

Note

The setFullYear method is preferred for nearly all purposes, because it avoids the “year 2000 problem.”

This method performs the following steps when called:

  1. Let dateObject be the this value.
  2. Perform ? RequireInternalSlot(dateObject, [[DateValue]]).
  3. Let t be dateObject.[[DateValue]].
  4. Let y be ? ToNumber(year).
  5. If t is NaN, set t to +0𝔽; otherwise, set t to LocalTime(t).
  6. Let yyyy be MakeFullYear(y).
  7. Let d be MakeDay(yyyy, MonthFromTime(t), DateFromTime(t)).
  8. Let date be MakeDate(d, TimeWithinDay(t)).
  9. Let u be TimeClip(UTC(date)).
  10. Set dateObject.[[DateValue]] to u.
  11. Return u.

B.2.3.3 Date.prototype.toGMTString ( )

Note

The toUTCString method is preferred. This method is provided principally for compatibility with old code.

The initial value of the "toGMTString" property is %Date.prototype.toUTCString%, defined in 21.4.4.43.

B.2.4 Additional Properties of the RegExp.prototype Object

B.2.4.1 RegExp.prototype.compile ( pattern, flags )

This method performs the following steps when called:

  1. Let O be the this value.
  2. Perform ? RequireInternalSlot(O, [[RegExpMatcher]]).
  3. If pattern is an Object and pattern has a [[RegExpMatcher]] internal slot, then
    1. If flags is not undefined, throw a TypeError exception.
    2. Let P be pattern.[[OriginalSource]].
    3. Let F be pattern.[[OriginalFlags]].
  4. Else,
    1. Let P be pattern.
    2. Let F be flags.
  5. Return ? RegExpInitialize(O, P, F).
 Note

This method completely reinitializes the this value RegExp with a new pattern and flags. An implementation may interpret use of this method as an assertion that the resulting RegExp object will be used multiple times and hence is a candidate for extra optimization.