Skip to content

Commit

Permalink
Editorial: Improve readability of TypedArray methods (#3258)
Browse files Browse the repository at this point in the history 
Broadly, this PR follows the following conventions for TA methods that
take start and end parameters,
  - The aliases for parameters are start and end
  - The relative values for the parameters, after coercion, are called
    relativeStart and relativeEnd
  - The absolute index values are called startIndex and endIndex

Also explicitly parenthesize multiplication in element size
computations.
  • Loading branch information
@syg @ljharb
syg authored and ljharb committed Jan 17, 2024
1 parent 17d66b5 commit 8969433
Showing 1 changed file with 50 additions and 49 deletions.
99 changes: 50 additions & 49 deletions spec.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40542,18 +40542,18 @@ <h1>%TypedArray%.prototype.copyWithin ( _target_, _start_ [ , _end_ ] )</h1>
1. Let _taRecord_ be ? ValidateTypedArray(_O_, ~seq-cst~).
1. Let _len_ be TypedArrayLength(_taRecord_).
1. Let _relativeTarget_ be ? ToIntegerOrInfinity(_target_).
1. If _relativeTarget_ = -∞, 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. If _relativeTarget_ = -∞, let _targetIndex_ be 0.
1. Else if _relativeTarget_ &lt; 0, let _targetIndex_ be max(_len_ + _relativeTarget_, 0).
1. Else, let _targetIndex_ be min(_relativeTarget_, _len_).
1. Let _relativeStart_ be ? ToIntegerOrInfinity(_start_).
1. If _relativeStart_ = -∞, 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 _relativeStart_ = -∞, let _startIndex_ be 0.
1. Else if _relativeStart_ &lt; 0, let _startIndex_ be max(_len_ + _relativeStart_, 0).
1. Else, let _startIndex_ be min(_relativeStart_, _len_).
1. If _end_ is *undefined*, let _relativeEnd_ be _len_; else let _relativeEnd_ be ? ToIntegerOrInfinity(_end_).
1. If _relativeEnd_ = -∞, 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 _count_ be min(_final_ - _from_, _len_ - _to_).
1. If _relativeEnd_ = -∞, let _endIndex_ be 0.
1. Else if _relativeEnd_ &lt; 0, let _endIndex_ be max(_len_ + _relativeEnd_, 0).
1. Else, let _endIndex_ be min(_relativeEnd_, _len_).
1. Let _count_ be min(_endIndex_ - _startIndex_, _len_ - _targetIndex_).
1. If _count_ > 0, then
1. NOTE: The copying must be performed in a manner that preserves the bit-level encoding of the source data.
1. Let _buffer_ be _O_.[[ViewedArrayBuffer]].
Expand All @@ -40562,9 +40562,9 @@ <h1>%TypedArray%.prototype.copyWithin ( _target_, _start_ [ , _end_ ] )</h1>
1. Set _len_ to TypedArrayLength(_taRecord_).
1. Let _elementSize_ be TypedArrayElementSize(_O_).
1. Let _byteOffset_ be _O_.[[ByteOffset]].
1. Let _bufferByteLimit_ be _len_ × _elementSize_ + _byteOffset_.
1. Let _toByteIndex_ be _to_ × _elementSize_ + _byteOffset_.
1. Let _fromByteIndex_ be _from_ × _elementSize_ + _byteOffset_.
1. Let _bufferByteLimit_ be (_len_ × _elementSize_) + _byteOffset_.
1. Let _toByteIndex_ be (_targetIndex_ × _elementSize_) + _byteOffset_.
1. Let _fromByteIndex_ be (_startIndex_ × _elementSize_) + _byteOffset_.
1. Let _countBytes_ be _count_ × _elementSize_.
1. If _fromByteIndex_ &lt; _toByteIndex_ and _toByteIndex_ &lt; _fromByteIndex_ + _countBytes_, then
1. Let _direction_ be -1.
Expand Down Expand Up @@ -40627,18 +40627,19 @@ <h1>%TypedArray%.prototype.fill ( _value_ [ , _start_ [ , _end_ ] ] )</h1>
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_ = -∞, 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 _relativeStart_ = -∞, let _startIndex_ be 0.
1. Else if _relativeStart_ &lt; 0, let _startIndex_ be max(_len_ + _relativeStart_, 0).
1. Else, let _startIndex_ be min(_relativeStart_, _len_).
1. If _end_ is *undefined*, let _relativeEnd_ be _len_; else let _relativeEnd_ be ? ToIntegerOrInfinity(_end_).
1. If _relativeEnd_ = -∞, 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. If _relativeEnd_ = -∞, let _endIndex_ be 0.
1. Else if _relativeEnd_ &lt; 0, let _endIndex_ be max(_len_ + _relativeEnd_, 0).
1. Else, let _endIndex_ be min(_relativeEnd_, _len_).
1. Set _taRecord_ to MakeTypedArrayWithBufferWitnessRecord(_O_, ~seq-cst~).
1. If IsTypedArrayOutOfBounds(_taRecord_) is *true*, throw a *TypeError* exception.
1. Set _len_ to TypedArrayLength(_taRecord_).
1. Set _final_ to min(_final_, _len_).
1. Repeat, while _k_ &lt; _final_,
1. Set _endIndex_ to min(_endIndex_, _len_).
1. Let _k_ be _startIndex_.
1. Repeat, while _k_ &lt; _endIndex_,
1. Let _Pk_ be ! ToString(𝔽(_k_)).
1. Perform ! Set(_O_, _Pk_, _value_, *true*).
1. Set _k_ to _k_ + 1.
Expand Down Expand Up @@ -41039,8 +41040,8 @@ <h1>
1. Let _srcByteIndex_ be 0.
1. Else,
1. Let _srcByteIndex_ be _srcByteOffset_.
1. Let _targetByteIndex_ be _targetOffset_ × _targetElementSize_ + _targetByteOffset_.
1. Let _limit_ be _targetByteIndex_ + _targetElementSize_ × _srcLength_.
1. Let _targetByteIndex_ be (_targetOffset_ × _targetElementSize_) + _targetByteOffset_.
1. Let _limit_ be _targetByteIndex_ + (_targetElementSize_ × _srcLength_).
1. If _srcType_ is _targetType_, then
1. NOTE: The transfer must be performed in a manner that preserves the bit-level encoding of the source data.
1. Repeat, while _targetByteIndex_ &lt; _limit_,
Expand Down Expand Up @@ -41097,23 +41098,22 @@ <h1>%TypedArray%.prototype.slice ( _start_, _end_ )</h1>
<emu-alg>
1. Let _O_ be the *this* value.
1. Let _taRecord_ be ? ValidateTypedArray(_O_, ~seq-cst~).
1. Let _len_ be TypedArrayLength(_taRecord_).
1. Let _srcArrayLength_ be TypedArrayLength(_taRecord_).
1. Let _relativeStart_ be ? ToIntegerOrInfinity(_start_).
1. If _relativeStart_ = -∞, 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_ = -∞, 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 _count_ be max(_final_ - _k_, 0).
1. Let _A_ be ? TypedArraySpeciesCreate(_O_, « 𝔽(_count_) »).
1. If _count_ > 0, then
1. If _relativeStart_ = -∞, let _startIndex_ be 0.
1. Else if _relativeStart_ &lt; 0, let _startIndex_ be max(_srcArrayLength_ + _relativeStart_, 0).
1. Else, let _startIndex_ be min(_relativeStart_, _srcArrayLength_).
1. If _end_ is *undefined*, let _relativeEnd_ be _srcArrayLength_; else let _relativeEnd_ be ? ToIntegerOrInfinity(_end_).
1. If _relativeEnd_ = -∞, let _endIndex_ be 0.
1. Else if _relativeEnd_ &lt; 0, let _endIndex_ be max(_srcArrayLength_ + _relativeEnd_, 0).
1. Else, let _endIndex_ be min(_relativeEnd_, _srcArrayLength_).
1. Let _countBytes_ be max(_endIndex_ - _startIndex_, 0).
1. Let _A_ be ? TypedArraySpeciesCreate(_O_, « 𝔽(_countBytes_) »).
1. If _countBytes_ > 0, then
1. Set _taRecord_ to MakeTypedArrayWithBufferWitnessRecord(_O_, ~seq-cst~).
1. If IsTypedArrayOutOfBounds(_taRecord_) is *true*, throw a *TypeError* exception.
1. Set _len_ to TypedArrayLength(_taRecord_).
1. Set _final_ to min(_final_, _len_).
1. Set _count_ to max(_final_ - _k_, 0).
1. Set _endIndex_ to min(_endIndex_, TypedArrayLength(_taRecord_)).
1. Set _countBytes_ to max(_endIndex_ - _startIndex_, 0).
1. Let _srcType_ be TypedArrayElementType(_O_).
1. Let _targetType_ be TypedArrayElementType(_A_).
1. If _srcType_ is _targetType_, then
Expand All @@ -41122,17 +41122,18 @@ <h1>%TypedArray%.prototype.slice ( _start_, _end_ )</h1>
1. Let _targetBuffer_ be _A_.[[ViewedArrayBuffer]].
1. Let _elementSize_ be TypedArrayElementSize(_O_).
1. Let _srcByteOffset_ be _O_.[[ByteOffset]].
1. Let _srcByteIndex_ be (_k_ × _elementSize_) + _srcByteOffset_.
1. Let _srcByteIndex_ be (_startIndex_ × _elementSize_) + _srcByteOffset_.
1. Let _targetByteIndex_ be _A_.[[ByteOffset]].
1. Let _limit_ be _targetByteIndex_ + (_count_ × _elementSize_).
1. Repeat, while _targetByteIndex_ &lt; _limit_,
1. Let _endByteIndex_ be _targetByteIndex_ + (_countBytes_ × _elementSize_).
1. Repeat, while _targetByteIndex_ &lt; _endByteIndex_,
1. Let _value_ be GetValueFromBuffer(_srcBuffer_, _srcByteIndex_, ~uint8~, *true*, ~unordered~).
1. Perform SetValueInBuffer(_targetBuffer_, _targetByteIndex_, ~uint8~, _value_, *true*, ~unordered~).
1. Set _srcByteIndex_ to _srcByteIndex_ + 1.
1. Set _targetByteIndex_ to _targetByteIndex_ + 1.
1. Else,
1. Let _n_ be 0.
1. Repeat, while _k_ &lt; _final_,
1. Let _k_ be _startIndex_.
1. Repeat, while _k_ &lt; _endIndex_,
1. Let _Pk_ be ! ToString(𝔽(_k_)).
1. Let _kValue_ be ! Get(_O_, _Pk_).
1. Perform ! Set(_A_, ! ToString(𝔽(_n_)), _kValue_, *true*).
Expand Down Expand Up @@ -41190,8 +41191,8 @@ <h1>%TypedArray%.prototype.sort ( _comparefn_ )</h1>
</emu-clause>

<emu-clause id="sec-%typedarray%.prototype.subarray">
<h1>%TypedArray%.prototype.subarray ( _begin_, _end_ )</h1>
<p>This method returns a new _TypedArray_ whose element type is the element type of this _TypedArray_ and whose ArrayBuffer is the ArrayBuffer of this _TypedArray_, referencing the elements in the interval from _begin_ (inclusive) to _end_ (exclusive). If either _begin_ or _end_ is negative, it refers to an index from the end of the array, as opposed to from the beginning.</p>
<h1>%TypedArray%.prototype.subarray ( _start_, _end_ )</h1>
<p>This method returns a new _TypedArray_ whose element type is the element type of this _TypedArray_ and whose ArrayBuffer is the ArrayBuffer of this _TypedArray_, referencing the elements in the interval from _start_ (inclusive) to _end_ (exclusive). If either _start_ or _end_ is negative, it refers to an index from the end of the array, as opposed to from the beginning.</p>
<p>It performs the following steps when called:</p>
<emu-alg>
1. Let _O_ be the *this* value.
Expand All @@ -41203,21 +41204,21 @@ <h1>%TypedArray%.prototype.subarray ( _begin_, _end_ )</h1>
1. Let _srcLength_ be 0.
1. Else,
1. Let _srcLength_ be TypedArrayLength(_srcRecord_).
1. Let _relativeBegin_ be ? ToIntegerOrInfinity(_begin_).
1. If _relativeBegin_ = -∞, 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. Let _relativeStart_ be ? ToIntegerOrInfinity(_start_).
1. If _relativeStart_ = -∞, let _startIndex_ be 0.
1. Else if _relativeStart_ &lt; 0, let _startIndex_ be max(_srcLength_ + _relativeStart_, 0).
1. Else, let _startIndex_ be min(_relativeStart_, _srcLength_).
1. Let _elementSize_ be TypedArrayElementSize(_O_).
1. Let _srcByteOffset_ be _O_.[[ByteOffset]].
1. Let _beginByteOffset_ be _srcByteOffset_ + _beginIndex_ × _elementSize_.
1. Let _beginByteOffset_ be _srcByteOffset_ + (_startIndex_ × _elementSize_).
1. If _O_.[[ArrayLength]] is ~auto~ and _end_ is *undefined*, then
1. Let _argumentsList_ be « _buffer_, 𝔽(_beginByteOffset_) ».
1. Else,
1. If _end_ is *undefined*, let _relativeEnd_ be _srcLength_; else let _relativeEnd_ be ? ToIntegerOrInfinity(_end_).
1. If _relativeEnd_ = -∞, 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 _newLength_ be max(_endIndex_ - _beginIndex_, 0).
1. Let _newLength_ be max(_endIndex_ - _startIndex_, 0).
1. Let _argumentsList_ be « _buffer_, 𝔽(_beginByteOffset_), 𝔽(_newLength_) ».
1. Return ? TypedArraySpeciesCreate(_O_, _argumentsList_).
</emu-alg>
Expand Down

0 comments on commit 8969433

Please sign in to comment.