Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / Java

List.add — adicionar um elemento a uma lista

`List.add(E)` acrescenta um elemento ao fim de uma lista e devolve `true` se a operação tiver êxito. A sobrecarga com índice insere um elemento na posição escolhida.

Versão: Java SE 21

Sintaxe

boolean add(E e)
void add(int index, E element)

Em Java SE 21, a interface java.util.List<E> disponibiliza duas sobrecargas de List.add. O método com um argumento, List.add(E), acrescenta um elemento ao fim da lista existente. E indica o tipo dos elementos, como String em List<String>. O método mantém a ordem dos elementos já presentes e devolve true em caso de êxito, não um índice nem uma nova lista. ArrayList aceita duplicados e valores null.

A sobrecarga add(int index, E element) insere numa posição numerada a partir de zero e tem o tipo de retorno void. O elemento nessa posição e os seguintes deslocam-se uma posição para a direita. Com index == size(), o elemento é acrescentado no fim. Um índice fora de 0 <= index && index <= size() é inválido e provoca uma IndexOutOfBoundsException quando a inserção é suportada. Ao contrário de set(index, element), a inserção não substitui nenhum elemento.

A adição é uma operação opcional: o tipo List<E> por si só não garante que uma determinada lista aceite adições. Uma chamada não suportada lança UnsupportedOperationException em vez de devolver false. Uma lista que suporta a adição pode ainda rejeitar null com NullPointerException, um tipo não permitido com ClassCastException ou uma propriedade não permitida do elemento com IllegalArgumentException.

List.of(...) cria uma lista não modificável. Arrays.asList(...) devolve uma lista associada a um array, na qual é possível substituir elementos, mas cujo tamanho é fixo. Nenhuma das duas suporta add. Para obter uma lista separada que possa crescer, usa new ArrayList<>(source). Acrescentar um elemento ao fim da cópia não altera a lista de origem.

Exemplos

import java.util.ArrayList;
import java.util.List;

public class Main {
    public static void main(String[] args) {
        List<String> source = List.of("alpha", "beta");
        List<String> tags = new ArrayList<>(source);

        boolean added = tags.add("alpha");
        tags.add(1, "gamma");

        System.out.println(added);
        System.out.println(tags);
        System.out.println(source);

        try {
            source.add("delta");
        } catch (UnsupportedOperationException e) {
            System.out.println("UnsupportedOperationException");
        }
    }
}

Resultado

true
[alpha, gamma, beta, alpha]
[alpha, beta]
UnsupportedOperationException

Acrescentar um segundo `alpha` ao fim de `tags` devolve `true`. Inserir `gamma` no índice `1` desloca `beta` e o segundo `alpha` para a direita. `source` mantém-se inalterada e rejeita a tentativa de adicionar `delta`.

Lições relacionadas

  • Java · Lição 1 · Avançado · Versão: 2
  • Java · Lição 2 · Avançado · Versão: 2
  • Java · Lição 6 · Avançado · Versão: 2
  • Java · Lição 8 · Avançado · Versão: 2
  • Java · Lição 10 · Avançado · Versão: 2
  • Java · Lição 13 · Avançado · Versão: 2
  • Java · Lição 21 · Avançado · Versão: 2
  • Java · Lição 33 · Avançado · Versão: 2
  • Java · Lição 35 · Avançado · Versão: 2
  • Java · Lição 36 · Avançado · Versão: 2
  • Java · Lição 38 · Avançado · Versão: 2
  • Java · Lição 19 · Básico · Versão: 2
  • Java · Lição 29 · Básico · Versão: 2
  • Java · Lição 39 · Básico · Versão: 2
  • Java · Lição 44 · Básico · Versão: 2
  • Java · Lição 54 · Básico · Versão: 2
  • Java · Lição 57 · Básico · Versão: 2
  • Java · Lição 59 · Básico · Versão: 2
  • Java · Lição 62 · Básico · Versão: 2
  • Java · Lição 2 · Intermédio · Versão: 2
  • Java · Lição 5 · Intermédio · Versão: 2
  • Java · Lição 6 · Intermédio · Versão: 2
  • Java · Lição 33 · Intermédio · Versão: 2
  • Java · Lição 34 · Intermédio · Versão: 2
  • Java · Lição 36 · Intermédio · Versão: 2
  • Java · Lição 39 · Intermédio · Versão: 2
  • Java · Lição 50 · Intermédio · Versão: 2

Fontes