Array.prototype.partition

Introduction

This is the specification for a proposed Array.prototype.partition method in JavaScript.

It is modified from Array.prototype.filter in ECMAScript specification.

1 Indexed Collections

1.1 Array Objects

1.1.1 Properties of the Array Prototype Object

1.1.1.1 Array.prototype.partition ( predictor [ , thisArg ] )

Editor's Note

This method works like Array.prototype.filter but returns both identical and opposite result in a pair.

Note 1

predictor should be a function that accepts three arguments and returns a value that is coercible to a Boolean value. partition calls predictor once for each element in the array, in ascending order, and constructs a new array contains two array, where first array contains values for which predictor returns true, while second array contains values for which predictor returns false. predictor is called only for elements of the array which actually exist; it is not called for missing elements of the array.

If a thisArg parameter is provided, it will be used as the this value for each invocation of predictor. If it is not provided, undefined is used instead.

predictor is called with three arguments: the value of the element, the index of the element, and the object being traversed.

partition does not directly mutate the object on which it is called but the object may be mutated by the calls to predictor.

The range of elements processed by partition is set before the first call to predictor. Elements which are appended to the array after the call to partition begins will not be visited by predictor. If existing elements of the array are changed their value as passed to predictor will be the value at the time partition visits them; elements that are deleted after the call to partition begins and before being visited are not visited.

When the partition method is called, the following steps are taken:

  1. Let O be ? ToObject(this value).
  2. Let len be ? LengthOfArrayLike(O).
  3. If IsCallable(predictor) is false, throw a TypeError exception.
  4. Let A be ? ArraySpeciesCreate(O, 0).
  5. Let B be ? ArraySpeciesCreate(O, 0).
  6. Let k be 0.
  7. Let toA be 0.
  8. Let toB be 0.
  9. Repeat, while k < len,
    1. Let Pk be ! ToString(𝔽(k)).
    2. Let kPresent be ? HasProperty(O, Pk).
    3. If kPresent is true, then
      1. Let kValue be ? Get(O, Pk).
      2. Let selected be ! ToBoolean(? Call(predictor, thisArg, « kValue, 𝔽(k), O »)).
      3. If selected is true, then
        1. Perform ? CreateDataPropertyOrThrow(A, ! ToString(𝔽(toA)), kValue).
        2. Set toA to toA + 1.
      4. Else,
        1. Perform ? CreateDataPropertyOrThrow(B, ! ToString(𝔽(toB)), kValue).
        2. Set toB to toB + 1.
    4. Set k to k + 1.
  10. Let Pair be ? ArrayCreate(2).
  11. Perform ? CreateDataPropertyOrThrow(Pair, ! ToString(0𝔽), A).
  12. Perform ? CreateDataPropertyOrThrow(Pair, ! ToString(1𝔽), B).
  13. Return Pair.
 Note 2

The partition function is intentionally generic; it does not require that its this value be an Array. Therefore it can be transferred to other kinds of objects for use as a method.

A Colophon

This specification is authored on GitHub in a plaintext source format called Ecmarkup.

Ecmarkup is an HTML and Markdown dialect that provides a framework and toolset for authoring ECMAScript specifications in plaintext and processing the specification into a full-featured HTML rendering that follows the editorial conventions for this document. Ecmarkup builds on and integrates a number of other formats and technologies including Grammarkdown for defining syntax and Ecmarkdown for authoring algorithm steps.

B Copyright & Software License

Copyright Notice

© 2021 Tzu-Te Kuo (Davy) <me@davy.tw>
Original ECMAScript specification, copyright © 2021 Ecma International

Software License

MIT License

Copyright (c) 2021 Tzu-Te Kuo (Davy) <me@davy.tw>

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.