Array.prototype.copyWithin()

El método copyWithin() transfiere una copia  plana de una sección a otra dentro del mismo array ( o contexto similar ), sin modificar su propiedad length y lo devuelve.

Sintaxis

arr.copyWithin(target[, start[, end]])

Parámetros

target

Índice basado en cero que establece en dónde dentro de la secuencia original se insertará la secuencia copiada.  Si es negativo, target se contará desde el final. -1 es el último elemento, -2 el penúltimo, etc.

Si target es  igual o mayor que  arr.length, no se copiará nada. Si target es posicionado después de start, la secuencia copiada se recortará para que encaje con arr.length.

start

Índice basado en cero a partir del cual comenzar la copia de elementos. Si es negativo, start comenzará a contarse desde el final.

Si start es omitido, copyWithin copiará desde el principio (por defecto es 0).

end

Índice basado en cero hasta el cual se copiarán los elementos. copyWithin copiará hasta pero sin incluir el end. Si es negativo, end será contado desde el final.

Si end es omitido, copyWithin copiará hasta el final ( por defecto es arr.length ).

Descripción

copyWithin es similar a la función memcpy de C y C++  , siendo altamente eficiente para desplazar los datos en un Array o  TypedArray. La secuencia de datos es leída y escrita en una sola operación;  la escritura será correcta incluso en el caso de que la zona de lectura y el destino de escritura se solapen.

La función copyWithin es intencionadamente genérica, permitiendo que se aplique en contextos en los cuales this no sea necesariamente un objeto Array.

El método copyWithin es un método mutador. No altera la propiedad length de this, pero cambiará su contenido y creará nuevas propiedades si es necesario.

Ejemplos

En los siguientes ejemplos céntrate en los siguientes aspectos:

• El tamaño del contexto en el que se aplica no cambia. En los ejemplos el array parte con cinco elementos y siempre mantiene cinco elementos.
• start y end trabajan juntos para decidir qué se copiará.  Siempre tienen valor por defecto aunque omitas end, o start y end.
• target trabaja solo y debe especificarse.  Indica el lugar para en el que la copia comenzará a sobreescribir datos existentes. Debe estar dentro de los límites en el contexto que se aplique.
• escribir arr.copyWithin( n ) es lo mismo que arr.copyWithin( n, 0, arr.length)

[1, 2, 3, 4, 5].copyWithin(-2);
// [1, 2, 3, 1, 2]

[1, 2, 3, 4, 5].copyWithin(0, 3);
// [4, 5, 3, 4, 5]

[1, 2, 3, 4, 5].copyWithin(0, 3, 4);
// [4, 2, 3, 4, 5]

[1, 2, 3, 4, 5].copyWithin(-2, -3, -1);
// [1, 2, 3, 3, 4]

A continuación se aplica en el contexto de un objeto array-like:

• El objeto contextual tiene alguna propiedad con clave numérica, y una propiedad length. Esto es suficiente para considerarse array-like.
• observa que no se modifica la propiedad length, a pesar de que se ha introducido una nueva propiedad con clave 0. A esto ser refiere cuando se dice que copyWithin es un método mutador.  ¿Por qué se creó esta nueva propiedad?  porque mediante el argumento target se especificó que  la copia debía comenzar a partir de un índice que ¡¡no existía!!

[].copyWithin.call({length: 5, 3: 1}, 0, 3);
// {0: 1, 3: 1, length: 5}

Lo que sigue ahora son las subclases tipadas de Array en ES6:

// Arrays tipados en ES6. Son subclases de Array
var i32a = new Int32Array([1, 2, 3, 4, 5]);

i32a.copyWithin(0, 2);
// Int32Array [3, 4, 5, 4, 5]

// En plataformas que todavía no siguen la norma ES6: 
[].copyWithin.call(new Int32Array([1, 2, 3, 4, 5]), 0, 3, 4);
// Int32Array [4, 2, 3, 4, 5]

Polyfill

if (!Array.prototype.copyWithin) {
  Array.prototype.copyWithin = function(target, start/*, end*/) {
    // Steps 1-2.
    if (this == null) {
      throw new TypeError('this is null or not defined');
    }

    var O = Object(this);

    // Steps 3-5.
    var len = O.length >>> 0;

    // Steps 6-8.
    var relativeTarget = target >> 0;

    var to = relativeTarget < 0 ?
      Math.max(len + relativeTarget, 0) :
      Math.min(relativeTarget, len);

    // Steps 9-11.
    var relativeStart = start >> 0;

    var from = relativeStart < 0 ?
      Math.max(len + relativeStart, 0) :
      Math.min(relativeStart, len);

    // Steps 12-14.
    var end = arguments[2];
    var relativeEnd = end === undefined ? len : end >> 0;

    var final = relativeEnd < 0 ?
      Math.max(len + relativeEnd, 0) :
      Math.min(relativeEnd, len);

    // Step 15.
    var count = Math.min(final - from, len - to);

    // Steps 16-17.
    var direction = 1;

    if (from < to && to < (from + count)) {
      direction = -1;
      from += count - 1;
      to += count - 1;
    }

    // Step 18.
    while (count > 0) {
      if (from in O) {
        O[to] = O[from];
      } else {
        delete O[to];
      }

      from += direction;
      to += direction;
      count--;
    }

    // Step 19.
    return O;
  };
}

Especificaciones

Compatibilidad entre navegadores

Consulta también

• Array