功能介绍

BiMap是Hutool中提供的双向Map实现，它支持根据键查找值，同时也支持根据值查找键。BiMap确保值的唯一性，因此可以安全地进行双向查找，是处理一对一映射关系的理想选择。

主要特性

• 支持双向映射，根据键查找值和根据值查找键
• 确保值的唯一性，避免重复值导致的歧义
• 支持反转Map，获取值到键的映射
• 基于HashMap实现，性能优异
• 支持所有Map接口方法
• 支持null键和null值，但null值只能出现一次
• 线程不安全，建议在单线程环境下使用

适用场景

1. 需要双向映射的场景，如枚举映射、编码映射等
2. 需要根据值快速查找键的场景
3. 需要确保值唯一性的场景
4. 处理一对一关系的数据
5. 如国家代码与国家名称的映射、用户ID与用户名的映射等

使用示例

示例1：基本用法

// 创建BiMap
BiMap<String, String> biMap = new BiMap<>();

// 添加键值对
biMap.put("CN", "China");
biMap.put("US", "United States");
biMap.put("JP", "Japan");

// 根据键查找值（与普通Map相同）
String china = biMap.get("CN");
// 输出: China

// 根据值查找键（BiMap特有功能）
String cn = biMap.getKey("China");
// 输出: CN

// 遍历BiMap
biMap.forEach((key, value) -> {
    Console.log(key + "=" + value);
});
// 输出:
// CN=China
// US=United States
// JP=Japan

示例2：反转Map

BiMap<String, String> biMap = new BiMap<>();
biMap.put("CN", "China");
biMap.put("US", "United States");

// 反转Map，获取值到键的映射
BiMap<String, String> inverseMap = biMap.inverse();

// 使用反转后的Map
String cn = inverseMap.get("China");
// 输出: CN

String us = inverseMap.get("United States");
// 输出: US

示例3：处理重复值

BiMap<String, String> biMap = new BiMap<>();

// 添加第一个键值对
biMap.put("CN", "China");

// 尝试添加重复值，会抛出IllegalArgumentException
// biMap.put("CN2", "China"); // 抛出异常

// 可以使用forcePut()方法强制替换
biMap.forcePut("CN2", "China");
// 此时，biMap中的映射为 {CN2=China, US=United States}

示例4：判断值是否存在

BiMap<String, String> biMap = new BiMap<>();
biMap.put("CN", "China");
biMap.put("US", "United States");

// 判断值是否存在
boolean containsChina = biMap.containsValue("China");
// 输出: true

boolean containsJapan = biMap.containsValue("Japan");
// 输出: false

注意事项

1. BiMap是线程不安全的，在多线程环境下使用需要额外同步
2. BiMap确保值的唯一性，添加重复值会抛出IllegalArgumentException
3. 可以使用forcePut()方法强制替换重复值
4. 支持null键和null值，但null值只能出现一次
5. 反转后的BiMap是原BiMap的视图，修改原BiMap会影响反转后的BiMap
6. 性能与HashMap相当，适合大多数场景

方法列表

BiMap继承自HashMap，除了支持所有Map接口方法外，还提供了以下特有方法：

方法名	描述	参数	返回值
getKey(V value)	根据值查找键	value: 值	K
inverse()	反转Map，获取值到键的映射	无	BiMap<V, K>
forcePut(K key, V value)	强制添加键值对，替换重复值	key: 键, value: 值	V
containsValue(Object value)	判断值是否存在	value: 值	boolean
put(K key, V value)	添加键值对，值必须唯一	key: 键, value: 值	V
putAll(Map<? extends K, ? extends V> map)	批量添加键值对，所有值必须唯一	map: 要添加的Map	void
remove(Object key)	移除键值对	key: 键	V
clear()	清空BiMap	无	void