Array

Sintaxe

[element0, element1, ..., elementN]
new Array(element0, element1, ..., elementN)
new Array(arrayLength)

element0, element1, ..., elementN

Um array JavaScript inicializado com os elementos contm, exceto no caso onde um nico argumento passado para o construtor do Array e esse argumento um nmero (veja o parmetro arrayLength abaixo). Esse caso especial s se aplica para os arrays JavaScript criados com o construtor Array , e no para literais de array criados com a sintaxe de colchetes [].

arrayLength

Se o nico argumento passado para o construtor do Array for um nmero inteiro entre 0 e 232-1 (inclusive), um novo array com o tamanho desse nmero retornado. Se o argumento for qualquer outro nmero, uma exceo RangeError lanada.

Descrio

Arrays so objetos semelhantes a listas que vm com uma srie de mtodos embutidos para realizar operaes de travessia e mutao. Nem o tamanho de um array JavaScript nem os tipos de elementos so fixos. J que o tamanho de um array pode ser alterado a qualquer momento e os dados podem ser armazenados em posies no contguas, arrays JavaScript no tem a garantia de serem densos; isso depende de como o programador escolhe us-los. De uma maneira geral, essas so caractersticas convenientes, mas, se esses recursos no so desejveis para o seu caso em particular, voc pode considerar usar arrays tipados.

Arrays no podem usar strings como ndices (como em um array associativo), devem ser usados nmeros inteiros. Definir ou acessar no-inteiros usando notao de colchetes (ou notao de ponto) no vai definir ou recuperar um elemento do array em si, mas sim definir ou acessar uma varivel associada com a coleo de propriedades de objeto daquele array. As propriedades de objeto do array e a lista de elementos do array so separados, e as operaes de travessia e mutao no podem ser aplicadas a essas propriedades nomeadas.

Accessando elementos de um array

Arrays JavaScript comeam com ndice zero: o primeiro elemento de um array est na posio 0 e o ltimo elemento est na posio equivalente ao valor da propriedade length (tamanho) menos 1.

var arr = ["este  o primeiro elemento", "este  o segundo elemento"];
console.log(arr[0]); // exibe 'este  o primeiro elemento'
console.log(arr[1]); // exibe 'este  o segundo elemento'
console.log(arr[arr.length - 1]); // exibe 'este  o segundo elemento'

Elementos de um array so somente propriedades de objetos, da forma que toString uma propriedade. Contudo, note que tentando acessar o primeiro elemento de um array da seguinte forma causar um erro de sintaxe, pois o nome da propriedade invlido:

console.log(arr.0); // um erro de sintaxe

No h nada de especial a respeito de arrays JavaScript e suas propriedades que causam isso. As propriedades JavaScript que comeam com um dgito no podem ser referenciadas com notao de ponto. Elas necesitam usar notao de colchetes para poderem ser acessadas. Por exemplo, se voc tivesse um objeto com a propriedade "3d", tambm teria que ser referenci-la usando notao de colchetes. Por exemplo:

var anos = [1950, 1960, 1970, 1980, 1990, 2000, 2010];
console.log(anos.0); // um erro de sintaxe
console.log(anos[0]); // funciona corretamente

renderer.3d.setTexture(model, 'personagem.png'); // um erro de sintaxe
renderer['3d'].setTexture(model, 'personagem.png'); //funciona corretamente

Note que no exemplo 3d, '3d' teve de ser colocado entre aspas. possivel tambm colocar entre aspas os ndices de arrays JavaScript (ou seja, years['2'] ao invs de years[2]), contudo isto no necessrio. O valor 2 em years[2] eventualmente ser convertido a uma string pela engine do JavaScript atravs de uma converso explicita com o mtodo toString. E por esta razo que '2' e '02' iro referenciar dois slots diferentes no objeto anos e o seguinte exemplo pode ser true:

console.log(anos["2"] != anos["02"]);

De forma similar, propriedades de objeto que sejam palavras reservadas(!) s podem ser acessadas como strings em notao de colchetes:

var promessa = {
  var: "texto",
  array: [1, 2, 3, 4],
};

console.log(promessa["var"]);

Relao entre length e propriedades numricas

As propriedades length e numricas de um array Javascript so conectadas. Varios dos mtodos javascript pr-definidos (por exemplo, join, slice, indexOf etc.) levam em conta o valor da propriedade length de um array quando eles so chamados. Outros mtodos (por exemplo, push, splice etc.) tambm resultam em uma atualizao na propriedade length do array.

var frutas = [];
frutas.push("banana", "maa", "pssego");

console.log(frutas.length); // 3

Quando configurar uma propriedade num array Javascript em que a propriedade um ndice valido do array e este ndice est fora do atual limite do array, o array ir crescer para um tamanho grande o suficiente para acomodar o elemento neste ndice, e a engine ir atualizar a propriedade length do array de acordo com isto:

frutas[5] = "manga";
console.log(frutas[5]); // 'manga'
console.log(Object.keys(frutas)); // ['0', '1', '2', '5']
console.log(frutas.length); // 6

Configurar a propriedade length diretamente, tambm resulta em um comportamento especial:

frutas.length = 10;
console.log(Object.keys(frutas)); // ['0', '1', '2', '5']
console.log(frutas.length); // 10

Diminuir o valor de length, entretanto, apaga elementos:

frutas.length = 2;
console.log(Object.keys(frutas)); // ['0', '1']
console.log(frutas.length); // 2

Criando um array usando o resultado de uma comparao

O resultado de uma comparao entre uma expresso regular e uma string pode criar um array Javascript. Este array tem propriedades e elementos que disponibilizam informaes sobre a comparao. Esse array o valor de retorno dos mtodos RegExp.exec, String.match, e String.replace. Para explicar melhor sobre estas propriedades e elementos, veja o seguinte exemplo e ento consulte a tabela abaixo:

// Encontra um d seguido por um ou mais b's seguido por um d
// Salva os b's encontrados e o d seguinte
// Ignora caixa (maiscula/minscula)

var minhaRegex = /d(b+)(d)/i;
var meuArray = minhaRegex.exec("cdbBdbsbz");

As propriedades e elementos retornados desta comparao so os seguintes:

Propriedades

Array.length

Propriedade comprimento do construtor Array, cujo valor 1.

get Array[@@species]

A funo de construtor que utilizada para criar objetos derivados.

Array

Permite a adio de propriedades para todos os objetos array.

Mtodos

Array.from()

Cria uma nova instncia de Array a partir de um objeto semelhante ou itervel.

Array.isArray()

Retorna true se a varivel um array e false caso contrrio.

Array.of()

Cria uma nova instncia de Array com um nmero varivel de argumentos, independentemente do nmero ou tipo dos argumentos.

Instncias de Array

Todas as instncias de Array herdam de Array.prototype. O prottipo do construtor Array pode ser modificado de forma a afetar todas as instncias de Array.

Propriedades

Mtodos

Mtodos modificadores

Mtodos de acesso

Mtodos de iterao

Mtodos genricos de Array

Algumas vezes voc poder querer aplicar mtodos de arrays para strings ou outros objetos parecidos com arrays (como em argumentos de funes). Ao fazer isto, voc trata uma string como um array de caracteres (ou em outros casos onde trata-se no-arrays como um array). Por exemplo, para checar se cada caractere em uma varivvel str uma letra, voc poderia escrever:

function isLetter(character) {
  return character >= "a" && character <= "z";
}

if (Array.prototype.every.call(str, isLetter))
  alert("A string '" + str + "' contm somente letras!");

Esta notao um pouco despendiosa e o JavaScript 1.6 introduziu a seguinte abreviao genrica:

if (Array.every(isLetter, str))
  alert("A string '" + str + "' contm somente letras!");

Generics tambm esto disponveis em String.

Estes no so atualmente parte dos padres ECMAScript (atravs do ES2015 Array.from() pode se conseguir isto). A seguir segue uma adaptao para permitir o uso em todos os navegadores:

/*globals define*/
// Assumes Array extras already present (one may use shims for these as well)
(function () {
  "use strict";

  var i,
    // We could also build the array of methods with the following, but the
    //   getOwnPropertyNames() method is non-shimable:
    // Object.getOwnPropertyNames(Array).filter(function (methodName) {return typeof Array[methodName] === 'function'});
    methods = [
      "join",
      "reverse",
      "sort",
      "push",
      "pop",
      "shift",
      "unshift",
      "splice",
      "concat",
      "slice",
      "indexOf",
      "lastIndexOf",
      "forEach",
      "map",
      "reduce",
      "reduceRight",
      "filter",
      "some",
      "every",
      "isArray",
    ],
    methodCount = methods.length,
    assignArrayGeneric = function (methodName) {
      var method = Array.prototype[methodName];
      Array[methodName] = function (arg1) {
        return method.apply(arg1, Array.prototype.slice.call(arguments, 1));
      };
    };

  for (i = 0; i < methodCount; i++) {
    assignArrayGeneric(methods[i]);
  }
})();

Exemplos

Exemplo: Criando um array

O exemplo a seguir cria um array, msgArray, com length 0, ento atribui valores para msgArray[0] e msgArray[99], trocando o length do array para 100.

var msgArray = new Array();
msgArray[0] = "Hello";
msgArray[99] = "world";

if (msgArray.length == 100) console.log("O length  100.");

Criando um Array

var frutas = ["Ma", "Banana"];

console.log(frutas.length);
// 2

Acessar um item (index) do Array

var primeiro = frutas[0];
// Ma

var ultimo = frutas[frutas.length - 1];
// Banana

Iterar um Array

frutas.forEach(function (item, indice, array) {
  console.log(item, indice);
});
// Ma 0
// Banana 1

Adicionar um item ao final do Array

var adicionar = frutas.push("Laranja");
// ['Ma', 'Banana', 'Laranja']

Remover um item do final do Array

var ultimo = frutas.pop(); // remove Laranja (do final)
// ['Ma', 'Banana'];

Remover do incio do Array

var primeiro = frutas.shift(); // remove Ma do incio
// ['Banana'];

Adicionar ao incio do Array

var adicionar = frutas.unshift("Morango"); // adiciona ao incio
// ['Morango', 'Banana'];

Procurar o ndice de um item na Array

frutas.push("Manga");
// ['Morango', 'Banana', 'Manga']

var pos = frutas.indexOf("Banana");
// 1

Remover um item pela posio do ndice

var removedItem = frutas.splice(pos, 1); //  assim que se remove um item
// ['Morango', 'Manga']

Remover itens de uma posio de ndice

var vegetais = ["Repolho", "Nabo", "Rabanete", "Cenoura"];
console.log(vegetais);
// ['Repolho', 'Nabo', 'Rabanete', 'Cenoura']

var pos = 1,
  n = 2;

var itensRemovidos = vegetais.splice(pos, n);
// Isso  como se faz para remover itens, n define o nmero de itens a se remover,
// a partir da posio (pos) em direo ao fim da array.

console.log(vegetais);
// ['Repolho', 'Cenoura'] (o array original  alterado)

console.log(itensRemovidos);
// ['Nabo', 'Rabanete']

Copiar um Array

var copiar = frutas.slice(); //  assim que se copia
// ['Morango', 'Manga']

Exemplo: Criando um array bi-dimensional

O exemplo a seguir cria um tabuleiro de xadrez usando dois arrays bi-dimensionais de string. A primeira jogada feita copiando o 'p' em 6,4 para 4,4. A posio antiga de 6,4 colocada em branco.

var board = [
  ["R", "N", "B", "Q", "K", "B", "N", "R"],
  ["P", "P", "P", "P", "P", "P", "P", "P"],
  [" ", " ", " ", " ", " ", " ", " ", " "],
  [" ", " ", " ", " ", " ", " ", " ", " "],
  [" ", " ", " ", " ", " ", " ", " ", " "],
  [" ", " ", " ", " ", " ", " ", " ", " "],
  ["p", "p", "p", "p", "p", "p", "p", "p"],
  ["r", "n", "b", "q", "k", "b", "n", "r"],
];
console.log(board.join("\n") + "\n\n");

// Fazendo o King's Pawn avanar 2
board[4][4] = board[6][4];
board[6][4] = " ";
console.log(board.join("\n"));

Sada:

R,N,B,Q,K,B,N,R
P,P,P,P,P,P,P,P
 , , , , , , ,
 , , , , , , ,
 , , , , , , ,
 , , , , , , ,
p,p,p,p,p,p,p,p
r,n,b,q,k,b,n,r

R,N,B,Q,K,B,N,R
P,P,P,P,P,P,P,P
 , , , , , , ,
 , , , , , , ,
 , , , ,p, , ,
 , , , , , , ,
p,p,p,p, ,p,p,p
r,n,b,q,k,b,n,r

Utilizando um array para tabular um conjunto de valores

values = [];
for (var x = 0; x < 10; x++) {
  values.push([2 ** x, 2 * x ** 2]);
}
console.table(values);

Sada:

0  1  0
1  2  2
2  4  8
3  8  18
4  16  32
5  32  50
6  64  72
7  128  98
8  256  128
9  512  162

Especificaes

Compatibilidade com os navegadores

Ver tambm

• "Indexing object properties" in JavaScript Guide: "Working with objects"
• New in JavaScript 1.7: Array comprehensions
• New in JavaScript 1.6: Array extras
• Draft: Typed Arrays