ECMAScript® 2024 Language Specification

Draft ECMA-262 / February 15, 2024

7.2 Testing and Comparison Operations

7.2.1 RequireObjectCoercible ( argument )

The abstract operation RequireObjectCoercible takes argument argument (an ECMAScript language value) and returns either a normal completion containing an ECMAScript language value or a throw completion. It throws an error if argument is a value that cannot be converted to an Object using ToObject. It is defined by Table 14:

Table 14: RequireObjectCoercible Results
Argument Type Result
Undefined Throw a TypeError exception.
Null Throw a TypeError exception.
Boolean Return argument.
Number Return argument.
String Return argument.
Symbol Return argument.
BigInt Return argument.
Object Return argument.

7.2.2 IsArray ( argument )

The abstract operation IsArray takes argument argument (an ECMAScript language value) and returns either a normal completion containing a Boolean or a throw completion. It performs the following steps when called:

  1. If argument is not an Object, return false.
  2. If argument is an Array exotic object, return true.
  3. If argument is a Proxy exotic object, then
    1. Perform ? ValidateNonRevokedProxy(argument).
    2. Let proxyTarget be argument.[[ProxyTarget]].
    3. Return ? IsArray(proxyTarget).
  4. Return false.

7.2.3 IsCallable ( argument )

The abstract operation IsCallable takes argument argument (an ECMAScript language value) and returns a Boolean. It determines if argument is a callable function with a [[Call]] internal method. It performs the following steps when called:

  1. If argument is not an Object, return false.
  2. If argument has a [[Call]] internal method, return true.
  3. Return false.

7.2.4 IsConstructor ( argument )

The abstract operation IsConstructor takes argument argument (an ECMAScript language value) and returns a Boolean. It determines if argument is a function object with a [[Construct]] internal method. It performs the following steps when called:

  1. If argument is not an Object, return false.
  2. If argument has a [[Construct]] internal method, return true.
  3. Return false.

7.2.5 IsExtensible ( O )

The abstract operation IsExtensible takes argument O (an Object) and returns either a normal completion containing a Boolean or a throw completion. It is used to determine whether additional properties can be added to O. It performs the following steps when called:

  1. Return ? O.[[IsExtensible]]().

7.2.6 IsIntegralNumber ( argument )

The abstract operation IsIntegralNumber takes argument argument (an ECMAScript language value) and returns a Boolean. It determines if argument is a finite integral Number value. It performs the following steps when called:

  1. If argument is not a Number, return false.
  2. If argument is not finite, return false.
  3. If truncate(ℝ(argument)) ≠ ℝ(argument), return false.
  4. Return true.

7.2.7 IsPropertyKey ( argument )

The abstract operation IsPropertyKey takes argument argument (an ECMAScript language value) and returns a Boolean. It determines if argument is a value that may be used as a property key. It performs the following steps when called:

  1. If argument is a String, return true.
  2. If argument is a Symbol, return true.
  3. Return false.

7.2.8 IsRegExp ( argument )

The abstract operation IsRegExp takes argument argument (an ECMAScript language value) and returns either a normal completion containing a Boolean or a throw completion. It performs the following steps when called:

  1. If argument is not an Object, return false.
  2. Let matcher be ? Get(argument, @@match).
  3. If matcher is not undefined, return ToBoolean(matcher).
  4. If argument has a [[RegExpMatcher]] internal slot, return true.
  5. Return false.

7.2.9 Static Semantics: IsStringWellFormedUnicode ( string )

The abstract operation IsStringWellFormedUnicode takes argument string (a String) and returns a Boolean. It interprets string as a sequence of UTF-16 encoded code points, as described in 6.1.4, and determines whether it is a well formed UTF-16 sequence. It performs the following steps when called:

  1. Let len be the length of string.
  2. Let k be 0.
  3. Repeat, while k < len,
    1. Let cp be CodePointAt(string, k).
    2. If cp.[[IsUnpairedSurrogate]] is true, return false.
    3. Set k to k + cp.[[CodeUnitCount]].
  4. Return true.

7.2.10 SameValue ( x, y )

The abstract operation SameValue takes arguments x (an ECMAScript language value) and y (an ECMAScript language value) and returns a Boolean. It determines whether or not the two arguments are the same value. It performs the following steps when called:

  1. If Type(x) is not Type(y), return false.
  2. If x is a Number, then
    1. Return Number::sameValue(x, y).
  3. Return SameValueNonNumber(x, y).
 Note

This algorithm differs from the IsStrictlyEqual Algorithm by treating all NaN values as equivalent and by differentiating +0𝔽 from -0𝔽.

7.2.11 SameValueZero ( x, y )

The abstract operation SameValueZero takes arguments x (an ECMAScript language value) and y (an ECMAScript language value) and returns a Boolean. It determines whether or not the two arguments are the same value (ignoring the difference between +0𝔽 and -0𝔽). It performs the following steps when called:

  1. If Type(x) is not Type(y), return false.
  2. If x is a Number, then
    1. Return Number::sameValueZero(x, y).
  3. Return SameValueNonNumber(x, y).
 Note

SameValueZero differs from SameValue only in that it treats +0𝔽 and -0𝔽 as equivalent.

7.2.12 SameValueNonNumber ( x, y )

The abstract operation SameValueNonNumber takes arguments x (an ECMAScript language value, but not a Number) and y (an ECMAScript language value, but not a Number) and returns a Boolean. It performs the following steps when called:

  1. Assert: Type(x) is Type(y).
  2. If x is either null or undefined, return true.
  3. If x is a BigInt, then
    1. Return BigInt::equal(x, y).
  4. If x is a String, then
    1. If x and y have the same length and the same code units in the same positions, return true; otherwise, return false.
  5. If x is a Boolean, then
    1. If x and y are both true or both false, return true; otherwise, return false.
  6. NOTE: All other ECMAScript language values are compared by identity.
  7. If x is y, return true; otherwise, return false.
 Note 1
For expository purposes, some cases are handled separately within this algorithm even if it is unnecessary to do so.
Note 2
The specifics of what "x is y" means are detailed in 5.2.7.

7.2.13 IsLessThan ( x, y, LeftFirst )

The abstract operation IsLessThan takes arguments x (an ECMAScript language value), y (an ECMAScript language value), and LeftFirst (a Boolean) and returns either a normal completion containing either a Boolean or undefined, or a throw completion. It provides the semantics for the comparison x < y, returning true, false, or undefined (which indicates that at least one operand is NaN). The LeftFirst flag is used to control the order in which operations with potentially visible side-effects are performed upon x and y. It is necessary because ECMAScript specifies left to right evaluation of expressions. If LeftFirst is true, the x parameter corresponds to an expression that occurs to the left of the y parameter's corresponding expression. If LeftFirst is false, the reverse is the case and operations must be performed upon y before x. It performs the following steps when called:

  1. If LeftFirst is true, then
    1. Let px be ? ToPrimitive(x, number).
    2. Let py be ? ToPrimitive(y, number).
  2. Else,
    1. NOTE: The order of evaluation needs to be reversed to preserve left to right evaluation.
    2. Let py be ? ToPrimitive(y, number).
    3. Let px be ? ToPrimitive(x, number).
  3. If px is a String and py is a String, then
    1. Let lx be the length of px.
    2. Let ly be the length of py.
    3. For each integer i such that 0 ≤ i < min(lx, ly), in ascending order, do
      1. Let cx be the numeric value of the code unit at index i within px.
      2. Let cy be the numeric value of the code unit at index i within py.
      3. If cx < cy, return true.
      4. If cx > cy, return false.
    4. If lx < ly, return true. Otherwise, return false.
  4. Else,
    1. If px is a BigInt and py is a String, then
      1. Let ny be StringToBigInt(py).
      2. If ny is undefined, return undefined.
      3. Return BigInt::lessThan(px, ny).
    2. If px is a String and py is a BigInt, then
      1. Let nx be StringToBigInt(px).
      2. If nx is undefined, return undefined.
      3. Return BigInt::lessThan(nx, py).
    3. NOTE: Because px and py are primitive values, evaluation order is not important.
    4. Let nx be ? ToNumeric(px).
    5. Let ny be ? ToNumeric(py).
    6. If Type(nx) is Type(ny), then
      1. If nx is a Number, then
        1. Return Number::lessThan(nx, ny).
      2. Else,
        1. Assert: nx is a BigInt.
        2. Return BigInt::lessThan(nx, ny).
    7. Assert: nx is a BigInt and ny is a Number, or nx is a Number and ny is a BigInt.
    8. If nx or ny is NaN, return undefined.
    9. If nx is -∞𝔽 or ny is +∞𝔽, return true.
    10. If nx is +∞𝔽 or ny is -∞𝔽, return false.
    11. If ℝ(nx) < ℝ(ny), return true; otherwise return false.
 Note 1

Step 3 differs from step 1.c in the algorithm that handles the addition operator + (13.15.3) by using the logical-and operation instead of the logical-or operation.

 Note 2

The comparison of Strings uses a simple lexicographic ordering on sequences of UTF-16 code unit values. There is no attempt to use the more complex, semantically oriented definitions of character or string equality and collating order defined in the Unicode specification. Therefore String values that are canonically equal according to the Unicode Standard but not in the same normalization form could test as unequal. Also note that lexicographic ordering by code unit differs from ordering by code point for Strings containing surrogate pairs.

7.2.14 IsLooselyEqual ( x, y )

The abstract operation IsLooselyEqual takes arguments x (an ECMAScript language value) and y (an ECMAScript language value) and returns either a normal completion containing a Boolean or a throw completion. It provides the semantics for the == operator. It performs the following steps when called:

  1. If Type(x) is Type(y), then
    1. Return IsStrictlyEqual(x, y).
  2. If x is null and y is undefined, return true.
  3. If x is undefined and y is null, return true.
  4. NOTE: This step is replaced in section B.3.6.2.
  5. If x is a Number and y is a String, return ! IsLooselyEqual(x, ! ToNumber(y)).
  6. If x is a String and y is a Number, return ! IsLooselyEqual(! ToNumber(x), y).
  7. If x is a BigInt and y is a String, then
    1. Let n be StringToBigInt(y).
    2. If n is undefined, return false.
    3. Return ! IsLooselyEqual(x, n).
  8. If x is a String and y is a BigInt, return ! IsLooselyEqual(y, x).
  9. If x is a Boolean, return ! IsLooselyEqual(! ToNumber(x), y).
  10. If y is a Boolean, return ! IsLooselyEqual(x, ! ToNumber(y)).
  11. If x is either a String, a Number, a BigInt, or a Symbol and y is an Object, return ! IsLooselyEqual(x, ? ToPrimitive(y)).
  12. If x is an Object and y is either a String, a Number, a BigInt, or a Symbol, return ! IsLooselyEqual(? ToPrimitive(x), y).
  13. If x is a BigInt and y is a Number, or if x is a Number and y is a BigInt, then
    1. If x is not finite or y is not finite, return false.
    2. If ℝ(x) = ℝ(y), return true; otherwise return false.
  14. Return false.

7.2.15 IsStrictlyEqual ( x, y )

The abstract operation IsStrictlyEqual takes arguments x (an ECMAScript language value) and y (an ECMAScript language value) and returns a Boolean. It provides the semantics for the === operator. It performs the following steps when called:

  1. If Type(x) is not Type(y), return false.
  2. If x is a Number, then
    1. Return Number::equal(x, y).
  3. Return SameValueNonNumber(x, y).
 Note

This algorithm differs from the SameValue Algorithm in its treatment of signed zeroes and NaNs.