CKTIS / Java
Map.put — inserir ou substituir um valor
Associe um valor a uma chave e obtenha o valor anterior. Um retorno `null` pode indicar que a chave não existia ou que já estava associada a `null`.
Versão: Java SE 21
Sintaxe
V put(K key, V value)
V previous = map.put(key, value);Map.put é um método de instância de java.util.Map<K, V> no Java SE 21. Map.put() é uma forma abreviada de referir o mesmo método, não uma chamada sem argumentos. Chame map.put(key, value) com uma chave do tipo K e um valor do tipo V. Se a chave não existir, é adicionada uma entrada; caso contrário, o seu valor é substituído. Num HashMap, dois objetos-chave distintos identificam a mesma entrada se forem iguais segundo equals e tiverem o mesmo hashCode.
O método devolve o valor anterior, não o novo. Um retorno null significa que não havia entrada ou que o valor anterior era null, se o mapa o permitir. Verifique containsKey(key) antes de escrever para distinguir os dois casos, desde que o mapa não mude entre as operações. Guardar null como valor não remove a entrada.
put é uma operação opcional. Um mapa criado com Map.of lança UnsupportedOperationException. Um mapa pode rejeitar um null não permitido com NullPointerException, um tipo inadequado com ClassCastException ou uma propriedade não permitida da chave ou do valor com IllegalArgumentException. Escrever através de uma vista modificável de NavigableMap.subMap altera o mapa subjacente; uma chave fora do intervalo provoca IllegalArgumentException e não é inserida.
HashMap e WeakHashMap aceitam uma chave null e valores null. Uma entrada de WeakHashMap também pode desaparecer quando o coletor de lixo recolhe a sua chave fracamente alcançável. Depois de put inserir uma nova entrada num LinkedHashMap, o mapa chama automaticamente removeEldestEntry. Uma redefinição do método pode devolver true para remover a entrada mais antiga. A mera substituição de um valor não desencadeia esta chamada.
Se uma cache só deve guardar resultados válidos, não chame put quando, por exemplo, um resultado negativo assinala um erro. Map<Class<?>, Object> não exige que o valor corresponda ao tipo representado pela chave; verifique-o com type.cast(value) antes de o guardar. Se um Lock proteger um mapa partilhado, use o mesmo bloqueio em todos os acessos: chame lock.lock() antes de try, escreva dentro de try e chame lock.unlock() em finally.
Exemplos
import java.util.HashMap;
import java.util.Map;
public class Main {
public static void main(String[] args) {
Map<String, String> statuses = new HashMap<>();
String key = "job";
String equalKey = new String(key);
System.out.println(statuses.containsKey(key));
System.out.println(statuses.put(key, "ready"));
System.out.println(statuses.put(equalKey, null));
System.out.println(statuses.containsKey(key));
System.out.println(statuses.put(key, "done"));
System.out.println(statuses.get(key));
System.out.println(statuses.size());
}
}Resultado
false null ready true null done 1
O primeiro `null` devolvido por `put` indica que a chave não existia. A chave igual substitui `ready` por `null` sem remover a entrada. O segundo `null` devolvido por `put` é o valor anterior, e o mapa continua a ter apenas uma entrada.
Lições relacionadas
- Java · Lição 13 · Avançado · Versão: 2
- Java · Lição 17 · Avançado · Versão: 2
- Java · Lição 18 · Avançado · Versão: 2
- Java · Lição 20 · Avançado · Versão: 2
- Java · Lição 36 · Avançado · Versão: 2
- Java · Lição 35 · Básico · Versão: 2
- Java · Lição 42 · Básico · Versão: 2
- Java · Lição 57 · Básico · Versão: 2
- Java · Lição 58 · Básico · Versão: 2
- Java · Lição 40 · Intermédio · Versão: 2
Fontes
- Map — put (Java SE 21 & JDK 21)
- HashMap (Java SE 21 & JDK 21)
- WeakHashMap (Java SE 21 & JDK 21)
- NavigableMap — subMap (Java SE 21 & JDK 21)
- LinkedHashMap — removeEldestEntry (Java SE 21 & JDK 21)
- Class — cast (Java SE 21 & JDK 21)
- Lock (Java SE 21 & JDK 21)
- The java Command — Using Source-File Mode (JDK 21)