Editorial: Introduce ToClampedIndex for relative-to-start-or-end inde…

…x values
tc39 · Sep 28, 2022 · 56b6a38 · 56b6a38
1 parent eb5d031
commit 56b6a38
Showing 1 changed file with 52 additions and 123 deletions.
diff --git a/spec.html b/spec.html
@@ -5783,6 +5783,29 @@ <h1>
           1. Return _integer_.
       </emu-alg>
     </emu-clause>
+
+    <emu-clause id="sec-toclampedindex" type="abstract operation">
+      <h1>
+        ToClampedIndex (
+          _value_: an ECMAScript language value,
+          _length_: a non-negative integer,
+          optional _lowerBound_: an integer,
+          optional _upperBound_: an integer,
+        ): either a normal completion containing an integer or a throw completion
+      </h1>
+      <dl class="header">
+        <dt>description</dt>
+        <dd>It converts _value_ to an integer (interpreting negative values relative to _length_) and clamps the result to the inclusive interval from _lowerBound_ to _upperBound_ (respectively defaulting to 0 and _length_).</dd>
+      </dl>
+      <emu-alg>
+        1. If _lowerBound_ is not present, set _lowerBound_ to 0.
+        1. If _upperBound_ is not present, set _upperBound_ to _length_.
+        1. Assert: _lowerBound_ &le; _upperBound_.
+        1. Let _integer_ be ? ToIntegerOrInfinity(_value_).
+        1. If _integer_ is finite and _integer_ &lt; 0, set _integer_ to _length_ + _integer_.
+        1. Return the result of clamping _integer_ between _lowerBound_ and _upperBound_.
+      </emu-alg>
+    </emu-clause>
   </emu-clause>
 
   <emu-clause id="sec-testing-and-comparison-operations">
@@ -33517,11 +33540,7 @@ <h1>String.prototype.at ( _index_ )</h1>
           1. Let _O_ be ? RequireObjectCoercible(*this* value).
           1. Let _S_ be ? ToString(_O_).
           1. Let _len_ be the length of _S_.
-          1. Let _relativeIndex_ be ? ToIntegerOrInfinity(_index_).
-          1. If _relativeIndex_ &ge; 0, then
-            1. Let _k_ be _relativeIndex_.
-          1. Else,
-            1. Let _k_ be _len_ + _relativeIndex_.
+          1. Let _k_ be ? ToClampedIndex(_index_, _len_, -1).
           1. If _k_ &lt; 0 or _k_ &ge; _len_, return *undefined*.
           1. Return the substring of _S_ from _k_ to _k_ + 1.
         </emu-alg>
@@ -34084,14 +34103,8 @@ <h1>String.prototype.slice ( _start_, _end_ )</h1>
           1. Let _O_ be ? RequireObjectCoercible(*this* value).
           1. Let _S_ be ? ToString(_O_).
           1. Let _len_ be the length of _S_.
-          1. Let _intStart_ be ? ToIntegerOrInfinity(_start_).
-          1. If _intStart_ is -&infin;, let _from_ be 0.
-          1. Else if _intStart_ &lt; 0, let _from_ be max(_len_ + _intStart_, 0).
-          1. Else, let _from_ be min(_intStart_, _len_).
-          1. If _end_ is *undefined*, let _intEnd_ be _len_; else let _intEnd_ be ? ToIntegerOrInfinity(_end_).
-          1. If _intEnd_ is -&infin;, let _to_ be 0.
-          1. Else if _intEnd_ &lt; 0, let _to_ be max(_len_ + _intEnd_, 0).
-          1. Else, let _to_ be min(_intEnd_, _len_).
+          1. Let _from_ be ? ToClampedIndex(_start_, _len_).
+          1. If _end_ is *undefined*, let _to_ be _len_; else let _to_ be ? ToClampedIndex(_end_, _len_).
           1. If _from_ &ge; _to_, return the empty String.
           1. Return the substring of _S_ from _from_ to _to_.
         </emu-alg>
@@ -37095,11 +37108,7 @@ <h1>Array.prototype.at ( _index_ )</h1>
         <emu-alg>
           1. Let _O_ be ? ToObject(*this* value).
           1. Let _len_ be ? LengthOfArrayLike(_O_).
-          1. Let _relativeIndex_ be ? ToIntegerOrInfinity(_index_).
-          1. If _relativeIndex_ &ge; 0, then
-            1. Let _k_ be _relativeIndex_.
-          1. Else,
-            1. Let _k_ be _len_ + _relativeIndex_.
+          1. Let _k_ be ? ToClampedIndex(_index_, _len_, -1).
           1. If _k_ &lt; 0 or _k_ &ge; _len_, return *undefined*.
           1. Return ? Get(_O_, ! ToString(𝔽(_k_))).
         </emu-alg>
@@ -37178,18 +37187,9 @@ <h1>Array.prototype.copyWithin ( _target_, _start_ [ , _end_ ] )</h1>
         <emu-alg>
           1. Let _O_ be ? ToObject(*this* value).
           1. Let _len_ be ? LengthOfArrayLike(_O_).
-          1. Let _relativeTarget_ be ? ToIntegerOrInfinity(_target_).
-          1. If _relativeTarget_ is -&infin;, let _to_ be 0.
-          1. Else if _relativeTarget_ &lt; 0, let _to_ be max(_len_ + _relativeTarget_, 0).
-          1. Else, let _to_ be min(_relativeTarget_, _len_).
-          1. Let _relativeStart_ be ? ToIntegerOrInfinity(_start_).
-          1. If _relativeStart_ is -&infin;, let _from_ be 0.
-          1. Else if _relativeStart_ &lt; 0, let _from_ be max(_len_ + _relativeStart_, 0).
-          1. Else, let _from_ be min(_relativeStart_, _len_).
-          1. If _end_ is *undefined*, let _relativeEnd_ be _len_; else let _relativeEnd_ be ? ToIntegerOrInfinity(_end_).
-          1. If _relativeEnd_ is -&infin;, let _final_ be 0.
-          1. Else if _relativeEnd_ &lt; 0, let _final_ be max(_len_ + _relativeEnd_, 0).
-          1. Else, let _final_ be min(_relativeEnd_, _len_).
+          1. Let _to_ be ? ToClampedIndex(_target_, _len_).
+          1. Let _from_ be ? ToClampedIndex(_start_, _len_).
+          1. If _end_ is *undefined*, let _final_ be _len_; else let _final_ be ? ToClampedIndex(_end_, _len_).
           1. Let _count_ be min(_final_ - _from_, _len_ - _to_).
           1. If _from_ &lt; _to_ and _to_ &lt; _from_ + _count_, then
             1. Let _direction_ be -1.
@@ -37269,14 +37269,8 @@ <h1>Array.prototype.fill ( _value_ [ , _start_ [ , _end_ ] ] )</h1>
         <emu-alg>
           1. Let _O_ be ? ToObject(*this* value).
           1. Let _len_ be ? LengthOfArrayLike(_O_).
-          1. Let _relativeStart_ be ? ToIntegerOrInfinity(_start_).
-          1. If _relativeStart_ is -&infin;, let _k_ be 0.
-          1. Else if _relativeStart_ &lt; 0, let _k_ be max(_len_ + _relativeStart_, 0).
-          1. Else, let _k_ be min(_relativeStart_, _len_).
-          1. If _end_ is *undefined*, let _relativeEnd_ be _len_; else let _relativeEnd_ be ? ToIntegerOrInfinity(_end_).
-          1. If _relativeEnd_ is -&infin;, let _final_ be 0.
-          1. Else if _relativeEnd_ &lt; 0, let _final_ be max(_len_ + _relativeEnd_, 0).
-          1. Else, let _final_ be min(_relativeEnd_, _len_).
+          1. Let _k_ be ? ToClampedIndex(_start_, _len_).
+          1. If _end_ is *undefined*, let _final_ be _len_; else let _final_ be ? ToClampedIndex(_end_, _len_).
           1. Repeat, while _k_ &lt; _final_,
             1. Let _Pk_ be ! ToString(𝔽(_k_)).
             1. Perform ? Set(_O_, _Pk_, _value_, *true*).
@@ -37646,12 +37640,7 @@ <h1>Array.prototype.lastIndexOf ( _searchElement_ [ , _fromIndex_ ] )</h1>
           1. Let _O_ be ? ToObject(*this* value).
           1. Let _len_ be ? LengthOfArrayLike(_O_).
           1. If _len_ is 0, return *-1*<sub>𝔽</sub>.
-          1. If _fromIndex_ is present, let _n_ be ? ToIntegerOrInfinity(_fromIndex_); else let _n_ be _len_ - 1.
-          1. If _n_ is -&infin;, return *-1*<sub>𝔽</sub>.
-          1. If _n_ &ge; 0, then
-            1. Let _k_ be min(_n_, _len_ - 1).
-          1. Else,
-            1. Let _k_ be _len_ + _n_.
+          1. If _fromIndex_ is not present, let _k_ be _len_ - 1; else let _k_ be ? ToClampedIndex(_fromIndex_, _len_, -1, _len_ - 1).
           1. Repeat, while _k_ &ge; 0,
             1. Let _kPresent_ be ? HasProperty(_O_, ! ToString(𝔽(_k_))).
             1. If _kPresent_ is *true*, then
@@ -37908,14 +37897,8 @@ <h1>Array.prototype.slice ( _start_, _end_ )</h1>
         <emu-alg>
           1. Let _O_ be ? ToObject(*this* value).
           1. Let _len_ be ? LengthOfArrayLike(_O_).
-          1. Let _relativeStart_ be ? ToIntegerOrInfinity(_start_).
-          1. If _relativeStart_ is -&infin;, let _k_ be 0.
-          1. Else if _relativeStart_ &lt; 0, let _k_ be max(_len_ + _relativeStart_, 0).
-          1. Else, let _k_ be min(_relativeStart_, _len_).
-          1. If _end_ is *undefined*, let _relativeEnd_ be _len_; else let _relativeEnd_ be ? ToIntegerOrInfinity(_end_).
-          1. If _relativeEnd_ is -&infin;, let _final_ be 0.
-          1. Else if _relativeEnd_ &lt; 0, let _final_ be max(_len_ + _relativeEnd_, 0).
-          1. Else, let _final_ be min(_relativeEnd_, _len_).
+          1. Let _k_ be ? ToClampedIndex(_start_, _len_).
+          1. If _end_ is *undefined*, let _final_ be _len_; else let _final_ be ? ToClampedIndex(_end_, _len_).
           1. Let _count_ be max(_final_ - _k_, 0).
           1. Let _A_ be ? ArraySpeciesCreate(_O_, _count_).
           1. Let _n_ be 0.
@@ -38084,10 +38067,7 @@ <h1>Array.prototype.splice ( _start_, _deleteCount_, ..._items_ )</h1>
         <emu-alg>
           1. Let _O_ be ? ToObject(*this* value).
           1. Let _len_ be ? LengthOfArrayLike(_O_).
-          1. Let _relativeStart_ be ? ToIntegerOrInfinity(_start_).
-          1. If _relativeStart_ is -&infin;, let _actualStart_ be 0.
-          1. Else if _relativeStart_ &lt; 0, let _actualStart_ be max(_len_ + _relativeStart_, 0).
-          1. Else, let _actualStart_ be min(_relativeStart_, _len_).
+          1. Let _actualStart_ be ? ToClampedIndex(_start_, _len_).
           1. Let _itemCount_ be the number of elements in _items_.
           1. If _start_ is not present, then
             1. Let _actualDeleteCount_ be 0.
@@ -38697,11 +38677,7 @@ <h1>%TypedArray%.prototype.at ( _index_ )</h1>
           1. Let _O_ be the *this* value.
           1. Perform ? ValidateTypedArray(_O_).
           1. Let _len_ be _O_.[[ArrayLength]].
-          1. Let _relativeIndex_ be ? ToIntegerOrInfinity(_index_).
-          1. If _relativeIndex_ &ge; 0, then
-            1. Let _k_ be _relativeIndex_.
-          1. Else,
-            1. Let _k_ be _len_ + _relativeIndex_.
+          1. Let _k_ be ? ToClampedIndex(_index_, _len_, -1).
           1. If _k_ &lt; 0 or _k_ &ge; _len_, return *undefined*.
           1. Return ! Get(_O_, ! ToString(𝔽(_k_))).
         </emu-alg>
@@ -38760,18 +38736,9 @@ <h1>%TypedArray%.prototype.copyWithin ( _target_, _start_ [ , _end_ ] )</h1>
           1. Let _O_ be the *this* value.
           1. Perform ? ValidateTypedArray(_O_).
           1. Let _len_ be _O_.[[ArrayLength]].
-          1. Let _relativeTarget_ be ? ToIntegerOrInfinity(_target_).
-          1. If _relativeTarget_ is -&infin;, let _to_ be 0.
-          1. Else if _relativeTarget_ &lt; 0, let _to_ be max(_len_ + _relativeTarget_, 0).
-          1. Else, let _to_ be min(_relativeTarget_, _len_).
-          1. Let _relativeStart_ be ? ToIntegerOrInfinity(_start_).
-          1. If _relativeStart_ is -&infin;, let _from_ be 0.
-          1. Else if _relativeStart_ &lt; 0, let _from_ be max(_len_ + _relativeStart_, 0).
-          1. Else, let _from_ be min(_relativeStart_, _len_).
-          1. If _end_ is *undefined*, let _relativeEnd_ be _len_; else let _relativeEnd_ be ? ToIntegerOrInfinity(_end_).
-          1. If _relativeEnd_ is -&infin;, let _final_ be 0.
-          1. Else if _relativeEnd_ &lt; 0, let _final_ be max(_len_ + _relativeEnd_, 0).
-          1. Else, let _final_ be min(_relativeEnd_, _len_).
+          1. Let _to_ be ? ToClampedIndex(_target_, _len_).
+          1. Let _from_ be ? ToClampedIndex(_start_, _len_).
+          1. If _end_ is *undefined*, let _final_ be _len_; else let _final_ ? ToClampedIndex(_end_, _len_).
           1. Let _count_ be min(_final_ - _from_, _len_ - _to_).
           1. If _count_ &gt; 0, then
             1. NOTE: The copying must be performed in a manner that preserves the bit-level encoding of the source data.
@@ -38839,14 +38806,8 @@ <h1>%TypedArray%.prototype.fill ( _value_ [ , _start_ [ , _end_ ] ] )</h1>
           1. Let _len_ be _O_.[[ArrayLength]].
           1. If _O_.[[ContentType]] is ~BigInt~, set _value_ to ? ToBigInt(_value_).
           1. Otherwise, set _value_ to ? ToNumber(_value_).
-          1. Let _relativeStart_ be ? ToIntegerOrInfinity(_start_).
-          1. If _relativeStart_ is -&infin;, let _k_ be 0.
-          1. Else if _relativeStart_ &lt; 0, let _k_ be max(_len_ + _relativeStart_, 0).
-          1. Else, let _k_ be min(_relativeStart_, _len_).
-          1. If _end_ is *undefined*, let _relativeEnd_ be _len_; else let _relativeEnd_ be ? ToIntegerOrInfinity(_end_).
-          1. If _relativeEnd_ is -&infin;, let _final_ be 0.
-          1. Else if _relativeEnd_ &lt; 0, let _final_ be max(_len_ + _relativeEnd_, 0).
-          1. Else, let _final_ be min(_relativeEnd_, _len_).
+          1. Let _k_ be ? ToClampedIndex(_start_, _len_).
+          1. If _end_ is *undefined*, let _final_ be _len_; else let _final_ be ? ToClampedIndex(_end_, _len_).
           1. If IsDetachedBuffer(_O_.[[ViewedArrayBuffer]]) is *true*, throw a *TypeError* exception.
           1. Repeat, while _k_ &lt; _final_,
             1. Let _Pk_ be ! ToString(𝔽(_k_)).
@@ -39089,12 +39050,7 @@ <h1>%TypedArray%.prototype.lastIndexOf ( _searchElement_ [ , _fromIndex_ ] )</h1
           1. Perform ? ValidateTypedArray(_O_).
           1. Let _len_ be _O_.[[ArrayLength]].
           1. If _len_ is 0, return *-1*<sub>𝔽</sub>.
-          1. If _fromIndex_ is present, let _n_ be ? ToIntegerOrInfinity(_fromIndex_); else let _n_ be _len_ - 1.
-          1. If _n_ is -&infin;, return *-1*<sub>𝔽</sub>.
-          1. If _n_ &ge; 0, then
-            1. Let _k_ be min(_n_, _len_ - 1).
-          1. Else,
-            1. Let _k_ be _len_ + _n_.
+          1. If _fromIndex_ is not present, let _k_ be _len_ - 1; else let _k_ be ? ToClampedIndex(_fromIndex_, _len_, -1, _len_ - 1).
           1. Repeat, while _k_ &ge; 0,
             1. Let _kPresent_ be ! HasProperty(_O_, ! ToString(𝔽(_k_))).
             1. If _kPresent_ is *true*, then
@@ -39337,14 +39293,8 @@ <h1>%TypedArray%.prototype.slice ( _start_, _end_ )</h1>
           1. Let _O_ be the *this* value.
           1. Perform ? ValidateTypedArray(_O_).
           1. Let _len_ be _O_.[[ArrayLength]].
-          1. Let _relativeStart_ be ? ToIntegerOrInfinity(_start_).
-          1. If _relativeStart_ is -&infin;, let _k_ be 0.
-          1. Else if _relativeStart_ &lt; 0, let _k_ be max(_len_ + _relativeStart_, 0).
-          1. Else, let _k_ be min(_relativeStart_, _len_).
-          1. If _end_ is *undefined*, let _relativeEnd_ be _len_; else let _relativeEnd_ be ? ToIntegerOrInfinity(_end_).
-          1. If _relativeEnd_ is -&infin;, let _final_ be 0.
-          1. Else if _relativeEnd_ &lt; 0, let _final_ be max(_len_ + _relativeEnd_, 0).
-          1. Else, let _final_ be min(_relativeEnd_, _len_).
+          1. Let _k_ be ? ToClampedIndex(_start_, _len_).
+          1. If _end_ is *undefined*, let _final_ be _len_; else let _final_ be ? ToClampedIndex(_end_, _len_).
           1. Let _count_ be max(_final_ - _k_, 0).
           1. Let _A_ be ? TypedArraySpeciesCreate(_O_, &laquo; 𝔽(_count_) &raquo;).
           1. If _count_ &gt; 0, then
@@ -39441,14 +39391,8 @@ <h1>%TypedArray%.prototype.subarray ( _begin_, _end_ )</h1>
           1. Assert: _O_ has a [[ViewedArrayBuffer]] internal slot.
           1. Let _buffer_ be _O_.[[ViewedArrayBuffer]].
           1. Let _srcLength_ be _O_.[[ArrayLength]].
-          1. Let _relativeBegin_ be ? ToIntegerOrInfinity(_begin_).
-          1. If _relativeBegin_ is -&infin;, let _beginIndex_ be 0.
-          1. Else if _relativeBegin_ &lt; 0, let _beginIndex_ be max(_srcLength_ + _relativeBegin_, 0).
-          1. Else, let _beginIndex_ be min(_relativeBegin_, _srcLength_).
-          1. If _end_ is *undefined*, let _relativeEnd_ be _srcLength_; else let _relativeEnd_ be ? ToIntegerOrInfinity(_end_).
-          1. If _relativeEnd_ is -&infin;, let _endIndex_ be 0.
-          1. Else if _relativeEnd_ &lt; 0, let _endIndex_ be max(_srcLength_ + _relativeEnd_, 0).
-          1. Else, let _endIndex_ be min(_relativeEnd_, _srcLength_).
+          1. Let _beginIndex_ be ? ToClampedIndex(_begin_, _srcLength_).
+          1. If _end_ is *undefined*, let _endIndex_ be _srcLength_; else let _endIndex_ be ? ToClampedIndex(_end_, _srcLength_).
           1. Let _newLength_ be max(_endIndex_ - _beginIndex_, 0).
           1. Let _elementSize_ be TypedArrayElementSize(_O_).
           1. Let _srcByteOffset_ be _O_.[[ByteOffset]].
@@ -41208,14 +41152,8 @@ <h1>ArrayBuffer.prototype.slice ( _start_, _end_ )</h1>
           1. If IsSharedArrayBuffer(_O_) is *true*, throw a *TypeError* exception.
           1. If IsDetachedBuffer(_O_) is *true*, throw a *TypeError* exception.
           1. Let _len_ be _O_.[[ArrayBufferByteLength]].
-          1. Let _relativeStart_ be ? ToIntegerOrInfinity(_start_).
-          1. If _relativeStart_ is -&infin;, let _first_ be 0.
-          1. Else if _relativeStart_ &lt; 0, let _first_ be max(_len_ + _relativeStart_, 0).
-          1. Else, let _first_ be min(_relativeStart_, _len_).
-          1. If _end_ is *undefined*, let _relativeEnd_ be _len_; else let _relativeEnd_ be ? ToIntegerOrInfinity(_end_).
-          1. If _relativeEnd_ is -&infin;, let _final_ be 0.
-          1. Else if _relativeEnd_ &lt; 0, let _final_ be max(_len_ + _relativeEnd_, 0).
-          1. Else, let _final_ be min(_relativeEnd_, _len_).
+          1. Let _first_ be ? ToClampedIndex(_start_, _len_).
+          1. If _end_ is *undefined*, let _final_ be _len_; else let _final_ be ? ToClampedIndex(_end_, _len_).
           1. Let _newLen_ be max(_final_ - _first_, 0).
           1. Let _ctor_ be ? SpeciesConstructor(_O_, %ArrayBuffer%).
           1. Let _new_ be ? Construct(_ctor_, &laquo; 𝔽(_newLen_) &raquo;).
@@ -41381,14 +41319,8 @@ <h1>SharedArrayBuffer.prototype.slice ( _start_, _end_ )</h1>
           1. Perform ? RequireInternalSlot(_O_, [[ArrayBufferData]]).
           1. If IsSharedArrayBuffer(_O_) is *false*, throw a *TypeError* exception.
           1. Let _len_ be _O_.[[ArrayBufferByteLength]].
-          1. Let _relativeStart_ be ? ToIntegerOrInfinity(_start_).
-          1. If _relativeStart_ is -&infin;, let _first_ be 0.
-          1. Else if _relativeStart_ &lt; 0, let _first_ be max(_len_ + _relativeStart_, 0).
-          1. Else, let _first_ be min(_relativeStart_, _len_).
-          1. If _end_ is *undefined*, let _relativeEnd_ be _len_; else let _relativeEnd_ be ? ToIntegerOrInfinity(_end_).
-          1. If _relativeEnd_ is -&infin;, let _final_ be 0.
-          1. Else if _relativeEnd_ &lt; 0, let _final_ be max(_len_ + _relativeEnd_, 0).
-          1. Else, let _final_ be min(_relativeEnd_, _len_).
+          1. Let _first_ be ? ToClampedIndex(_start_, _len_).
+          1. If _end_ is *undefined*, let _final_ be _len_; else let _final_ be ? ToClampedIndex(_end_, _len_).
           1. Let _newLen_ be max(_final_ - _first_, 0).
           1. Let _ctor_ be ? SpeciesConstructor(_O_, %SharedArrayBuffer%).
           1. Let _new_ be ? Construct(_ctor_, &laquo; 𝔽(_newLen_) &raquo;).
@@ -47513,10 +47445,7 @@ <h1>String.prototype.substr ( _start_, _length_ )</h1>
           1. Let _O_ be ? RequireObjectCoercible(*this* value).
           1. Let _S_ be ? ToString(_O_).
           1. Let _size_ be the length of _S_.
-          1. Let _intStart_ be ? ToIntegerOrInfinity(_start_).
-          1. If _intStart_ is -&infin;, set _intStart_ to 0.
-          1. Else if _intStart_ &lt; 0, set _intStart_ to max(_size_ + _intStart_, 0).
-          1. Else, set _intStart_ to min(_intStart_, _size_).
+          1. Let _intStart_ be ? ToClampedIndex(_start_, _size_).
           1. If _length_ is *undefined*, let _intLength_ be _size_.
           1. Else, let _intLength_ be the result of clamping ? ToIntegerOrInfinity(_length_) between 0 and _size_.
           1. Let _intEnd_ be min(_intStart_ + _intLength_, _size_).