From 896943313a2a3613fffa03b409ee150af03cf79d Mon Sep 17 00:00:00 2001 From: Shu-yu Guo Date: Wed, 17 Jan 2024 14:39:17 -0800 Subject: [PATCH] Editorial: Improve readability of TypedArray methods (#3258) 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. --- spec.html | 99 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 50 insertions(+), 49 deletions(-) diff --git a/spec.html b/spec.html index c675913443..a67ce4ea1a 100644 --- a/spec.html +++ b/spec.html @@ -40542,18 +40542,18 @@

%TypedArray%.prototype.copyWithin ( _target_, _start_ [ , _end_ ] )

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_ < 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_ < 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_ < 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_ < 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_ < 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_ < 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]]. @@ -40562,9 +40562,9 @@

%TypedArray%.prototype.copyWithin ( _target_, _start_ [ , _end_ ] )

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_ < _toByteIndex_ and _toByteIndex_ < _fromByteIndex_ + _countBytes_, then 1. Let _direction_ be -1. @@ -40627,18 +40627,19 @@

%TypedArray%.prototype.fill ( _value_ [ , _start_ [ , _end_ ] ] )

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_ < 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_ < 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_ < 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_ < 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_ < _final_, + 1. Set _endIndex_ to min(_endIndex_, _len_). + 1. Let _k_ be _startIndex_. + 1. Repeat, while _k_ < _endIndex_, 1. Let _Pk_ be ! ToString(𝔽(_k_)). 1. Perform ! Set(_O_, _Pk_, _value_, *true*). 1. Set _k_ to _k_ + 1. @@ -41039,8 +41040,8 @@

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_ < _limit_, @@ -41097,23 +41098,22 @@

%TypedArray%.prototype.slice ( _start_, _end_ )

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_ < 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_ < 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_ < 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_ < 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 @@ -41122,17 +41122,18 @@

%TypedArray%.prototype.slice ( _start_, _end_ )

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_ < _limit_, + 1. Let _endByteIndex_ be _targetByteIndex_ + (_countBytes_ × _elementSize_). + 1. Repeat, while _targetByteIndex_ < _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_ < _final_, + 1. Let _k_ be _startIndex_. + 1. Repeat, while _k_ < _endIndex_, 1. Let _Pk_ be ! ToString(𝔽(_k_)). 1. Let _kValue_ be ! Get(_O_, _Pk_). 1. Perform ! Set(_A_, ! ToString(𝔽(_n_)), _kValue_, *true*). @@ -41190,8 +41191,8 @@

%TypedArray%.prototype.sort ( _comparefn_ )

-

%TypedArray%.prototype.subarray ( _begin_, _end_ )

-

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.

+

%TypedArray%.prototype.subarray ( _start_, _end_ )

+

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.

It performs the following steps when called:

1. Let _O_ be the *this* value. @@ -41203,13 +41204,13 @@

%TypedArray%.prototype.subarray ( _begin_, _end_ )

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_ < 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_ < 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, @@ -41217,7 +41218,7 @@

%TypedArray%.prototype.subarray ( _begin_, _end_ )

1. If _relativeEnd_ = -∞, let _endIndex_ be 0. 1. Else if _relativeEnd_ < 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_).