Module java.base
Package java.util

Interface Map.Entry<K,V>

类型参数:
K - 键的类型
V - 值的类型
所有已知的实现类:
AbstractMap.SimpleEntry, AbstractMap.SimpleImmutableEntry
封装的接口:
Map<K,V>
public static interface Map.Entry<K,V>
映射条目（键-值对）。条目可能是不可修改的，或者如果实现了可选的setValue方法，则值可能是可修改的。条目可能独立于任何映射，或者它可能表示映射的条目集视图中的一个条目。

如果通过映射的entrySet()视图进行迭代获得了一个条目，则该条目会保持与其底层映射的连接，无论是通过显式使用Iterator还是通过增强的for语句隐式进行。这种与后备映射的连接仅在迭代条目集视图期间有效。在迭代期间，如果由后备映射支持，通过setValue方法对条目值的更改将在后备映射中可见。这种条目的行为在映射的条目集视图之外是未定义的。如果在迭代器返回条目之后通过setValue方法以外的方式修改了后备映射，则其行为也是未定义的。此外，后备映射中的映射值的更改可能会或可能不会在条目集视图中相应的条目中可见。

条目也可以通过其他方式从映射的条目集视图中获取，例如使用parallelStream、stream、spliterator方法，任何toArray重载，或者将条目集视图复制到另一个集合中。未指定获得的条目实例是否连接到底层映射，这样的条目是否会影响底层映射以及反之，以及这样的条目是否支持可选的setValue方法。

此外，条目也可以直接从映射中获取，例如通过直接在NavigableMap接口上调用方法。因此获得的条目通常不会连接到映射，并且是在调用时的映射的不可修改快照。这样的条目通常也不支持setValue方法。

通过直接构造AbstractMap.SimpleEntry或AbstractMap.SimpleImmutableEntry类，或通过调用Map.entry或Map.Entry.copyOf方法获得的条目不会连接到任何映射。

API 注意:
从映射的条目集视图获取的条目实例的确切行为在除了通过迭代之外的不同映射实现中会有所不同；有些与后备映射连接，有些则没有。要确保条目与其后备映射断开连接，请使用copyOf方法。例如，以下代码创建了映射条目的快照，即使原始映射被修改也不会改变： 
 
 var entries = map.entrySet().stream().map(Map.Entry::copyOf).toList()
自 JDK 版本:
1.2
另请参阅:

  • Method Details

    • getKey

      K getKey()
      返回与此条目对应的键。
      返回:
      与此条目对应的键
      抛出:
      IllegalStateException - 如果实现允许，但不要求，如果条目已从后备映射中移除，则可能会抛出此异常。

    • getValue

      V getValue()
      返回与此条目对应的值。如果映射已从后备映射中移除（通过迭代器的remove操作），则此调用的结果是未定义的。
      返回:
      与此条目对应的值
      抛出:
      IllegalStateException - 如果实现允许，但不要求，如果条目已从后备映射中移除，则可能会抛出此异常。

    • setValue

      V setValue(V value)
      用指定值替换此条目对应的值（可选操作）。 （写入到映射中。）如果映射已从映射中移除（通过迭代器的remove操作），则此调用的行为是未定义的。
      参数:
      value - 要存储在此条目中的新值
      返回:
      与条目对应的旧值
      抛出:
      UnsupportedOperationException - 如果后备映射不支持put操作
      ClassCastException - 如果指定值的类阻止其存储在后备映射中
      NullPointerException - 如果后备映射不允许空值，并且指定值为null
      IllegalArgumentException - 如果此值的某些属性阻止其存储在后备映射中
      IllegalStateException - 如果实现允许，但不要求，如果条目已从后备映射中移除，则可能会抛出此异常。

    • equals

      boolean equals(Object o)
      将指定的对象与此条目进行相等性比较。如果给定对象也是映射条目，并且两个条目表示相同的映射，则返回true。更正式地，如果两个条目e1和e2表示相同的映射，则e1.equals(e2)当且仅当 
           (e1.getKey()==null ?
      e2.getKey()==null : e1.getKey().equals(e2.getKey()))  &&
     (e1.getValue()==null ?
      e2.getValue()==null : e1.getValue().equals(e2.getValue()))
      这确保了equals方法在Map.Entry接口的不同实现之间正常工作。
      覆盖:
      equals 在类 Object
      参数:
      o - 与此映射条目进行相等性比较的对象
      返回:
      如果指定对象等于此映射条目，则返回true
      另请参阅:

    • hashCode

      int hashCode()
      返回此映射条目的哈希码值。映射条目e的哈希码定义为： 
           (e.getKey()==null   ? 0 : e.getKey().hashCode()) ^
     (e.getValue()==null ? 0 : e.getValue().hashCode())
      这确保了对于任何两个条目e1和e2，如果e1.equals(e2)，则e1.hashCode()==e2.hashCode()，这是Object.hashCode的一般契约所要求的。
      覆盖:
      hashCode 在类 Object
      返回:
      此映射条目的哈希码值
      另请参阅:

    • comparingByKey

      static <K extends Comparable<? super K>, V> Comparator<Map.Entry<K,V>> comparingByKey()
      返回一个比较器，按键的自然顺序比较Map.Entry。

      返回的比较器是可序列化的，在比较具有空键的条目时会抛出NullPointerException。

      类型参数:
      K - 映射键的Comparable类型
      V - 映射值的类型
      返回:
      一个比较器，按键的自然顺序比较Map.Entry。
      自版本:
      1.8
      参见:
      • Comparable

    • comparingByValue

      static <K, V extends Comparable<? super V>> Comparator<Map.Entry<K,V>> comparingByValue()
      返回一个比较器，按值的自然顺序比较Map.Entry。

      返回的比较器是可序列化的，在比较具有空值的条目时会抛出NullPointerException。

      类型参数:
      K - 映射键的类型
      V - 映射值的Comparable类型
      返回:
      一个比较器，按值的自然顺序比较Map.Entry。
      自版本:
      1.8
      参见:
      • Comparable

    • comparingByKey

      static <K, V> Comparator<Map.Entry<K,V>> comparingByKey(Comparator<? super K> cmp)
      返回一个比较器，使用给定的Comparator按键比较Map.Entry。

      返回的比较器在指定的比较器也是可序列化的情况下也是可序列化的。

      类型参数:
      K - 映射键的类型
      V - 映射值的类型
      参数:
      cmp - 键的Comparator
      返回:
      一个比较器，按键比较Map.Entry。
      自版本:
      1.8

    • comparingByValue

      static <K, V> Comparator<Map.Entry<K,V>> comparingByValue(Comparator<? super V> cmp)
      返回一个比较器，使用给定的Comparator按值比较Map.Entry。

      返回的比较器在指定的比较器也是可序列化的情况下也是可序列化的。

      类型参数:
      K - 映射键的类型
      V - 映射值的类型
      参数:
      cmp - 值的Comparator
      返回:
      一个比较器，按值比较Map.Entry。
      自版本:
      1.8

    • copyOf

      static <K, V> Map.Entry<K,V> copyOf(Map.Entry<? extends K,? extends V> e)
      返回给定Map.Entry的副本。返回的实例不与任何映射关联。返回的实例具有与Map::entry方法返回的实例相同的特性。
      API注释:
      从映射的entry-set视图获取的实例与该映射有关联。可以使用copyOf方法创建一个独立于任何映射的包含相同键和值的Map.Entry实例。
      实现注释:
      如果给定的条目是通过调用copyOf或Map::entry获得的，则调用copyOf通常不会创建另一个副本。
      类型参数:
      K - 键的类型
      V - 值的类型
      参数:
      e - 要复制的条目
      返回:
      与给定条目相等的映射条目
      抛出:
      NullPointerException - 如果e为null或其键或值之一为null
      自版本:
      17