mapPar

Array.prototype.mapPar ( depth = 1, callbackfn, thisArg = undefined )

callbackfn should be a function that accepts four arguments. In an arbitrary order mapPar calls callbackfn once for each element in the array and constructs a new Array from the results. callbackfn is called only for elements of the array which actually exist; it is not called for missing elements of the array.

If the first argument is not a callable function then it is interpreted as the number of dimensions to map over and the second argument is used as the callbackfn. The default is 1 signifying the outermost dimension.

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

callbackfn is called with four arguments: the value of the element, the index of the element, the object being traversed, and an opaque reference to the location in the result indicated by the index of the element. The opaque reference can be assigned to by the callbackfn. If callbackfn returns a non undefined value it is placed at the index of the element in the result overwriting any assignment made to the opaque reference.

mapPar does not directly mutate the object on which it is called but the object may be mutated by the calls to callbackfn. Such mutation will defeat the parallel optimization and callbacks will be performed in an ascending left to right order.

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

When the mapPar method is called with one or two arguments, the following steps are taken:

TBD Deal with depth. TBD Deal with Typed Object Arrays, hopefully in a transparent way.

1. Let O be the result of calling ToObject passing the this value as the argument.
2. ReturnIfAbrupt(O).
3. Let lenValue be the result of Get(O, "length")
4. Let len be ToLength(lenValue).
5. ReturnIfAbrupt(len).

6.  If IsCallable(_depth_) 
   

   1. Let thisArg be callbackfun
   2. Let callbackfn be depth
   3. Let depth be 1
7. If IsCallable(callbackfn) is false, throw a TypeError exception.
8. If thisArg was supplied, let T be thisArg; else let T be undefined.
9. Let A be undefined.
10. If O is not an exotic Array object, throw a TypeError exception.
11. Let C be Get(O, "constructor").
12. ReturnIfAbrupt(C).
13. If IsConstructor(C) is true, then
    1. Let thisRealm be the running execution context’s Realm.
    2. If thisRealm and the value of A’s Realm internal slot are the same value, then
       1. Let A be the result of calling the Construct internal method of C with an argument list containing the single item len.
14. If A is undefined, then
    1. Let A be the result of the abstract operation ArrayCreate with argument len.
15. ReturnIfAbrupt(A).
16. Let k be 0.
17. In arbitrary order for each value k between 0 and len - 1
    1. Let Pk be ToString(k).
    2. Let kPresent be the result of HasProperty(O, Pk).
    3. ReturnIfAbrupt(kPresent).
    4. If kPresent is true, then
       1. Let kValue be the result of Get(O, Pk).
       2. ReturnIfAbrupt(kValue).
       3. Let out be the result of calling the CreateOpaqueReference internal method with a List containing A and k as argumentsList.
       4. Let mappedValue be the result of calling the Call internal method of callbackfn with T as thisArgument and a List containing kValue, k, O and out as argumentsList.
       5. ReturnIfAbrupt(mappedValue).
       6. If mappedValue is not undefined
          1. Let status be the result of CreateDataPropertyOrThrow (A, Pk, mappedValue).
          2. ReturnIfAbrupt(status).
18. Return A.

The length property of the mapPar method is 1.

NOTE The mapPar function is intentionally generic; it does not require that its this value be an Array object. Therefore it can be transferred to other kinds of objects for use as a method. Whether the mapPar function can be applied successfully to an exotic object that is not an Array is implementation-dependent.

If the system determines that the callback function does not mutate any state that is visible to other computation, including other callback functions, then the system is likely to execute the callback functions in parallel.