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

CKTIS / Java

List.add(E) — acrescentar um elemento ao fim de uma lista

`List.add(E)` acrescenta um elemento ao fim da lista existente e devolve `true` se a chamada terminar normalmente. Nem todas as listas suportam esta operação.

Versão: Java SE 21

Sintaxe

boolean add(E e)

boolean added = items.add(element);

List.add(E) é o método com um argumento de java.util.List<E>. E é o tipo dos elementos, por exemplo Customer num repositório baseado em List<Customer>. O método altera a lista existente: o novo elemento fica no fim e os anteriores mantêm a sua ordem. Se a chamada terminar normalmente, devolve true, não um índice nem uma nova lista.

A lista guarda a referência que lhe passas, não uma cópia do objeto. Uma ArrayList pode guardar a mesma referência várias vezes; as alterações ao objeto partilhado são visíveis a partir de cada posição que o referencia. As listas normalmente aceitam duplicados, pelo que chamadas sucessivas a add permitem registar eventos ou destinatários pela ordem em que são acrescentados.

Acrescentar ao fim é uma operação opcional: uma lista criada com List.of(...) não é modificável e lança UnsupportedOperationException. Uma lista que suporta a operação pode ainda rejeitar um elemento: NullPointerException se não aceitar null, ClassCastException se não aceitar a classe do elemento ou IllegalArgumentException se não aceitar outra propriedade do elemento. ArrayList aceita null.

A sobrecarga add(int index, E element) devolve void e insere num índice entre 0 e size(), inclusive, deslocando os elementos a partir dessa posição. Para desfazer uma remoção e repor a posição original, usa o índice guardado; add(element) só acrescenta ao fim. Desde o Java 21, addLast(E) também acrescenta ao fim, mas devolve void.

Exemplos

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

public class Main {
    public static void main(String[] args) {
        List<StringBuilder> items = new ArrayList<>();
        StringBuilder first = new StringBuilder("Ada");

        boolean added = items.add(first);
        items.add(new StringBuilder("Lin"));
        items.add(first);

        System.out.println(added);
        System.out.println(items);
        System.out.println(items.get(0) == items.get(2));
        first.append("!");
        System.out.println(items);
    }
}

Resultado

true
[Ada, Lin, Ada]
true
[Ada!, Lin, Ada!]

O primeiro `true` é o resultado de `add`; o segundo é o resultado da comparação de referências com `==`. Depois de alterar `first`, ambas as posições mostram `Ada!`, porque referenciam o mesmo objeto.

Lições relacionadas

  • Java · Lição 21 · Intermédio · Versão: 2
  • Java · Lição 22 · Intermédio · Versão: 2
  • Java · Lição 26 · Intermédio · Versão: 2
  • Java · Lição 27 · Intermédio · Versão: 2
  • Java · Lição 32 · Intermédio · Versão: 2

Fontes