001/* 002 * Copyright (C) 2007 The Guava Authors 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package com.google.common.collect; 018 019import com.google.common.annotations.GwtCompatible; 020import com.google.errorprone.annotations.CanIgnoreReturnValue; 021import java.util.Map; 022import java.util.Set; 023import org.checkerframework.checker.nullness.qual.Nullable; 024 025/** 026 * A bimap (or "bidirectional map") is a map that preserves the uniqueness of its values as well as 027 * that of its keys. This constraint enables bimaps to support an "inverse view", which is another 028 * bimap containing the same entries as this bimap but with reversed keys and values. 029 * 030 * <p>See the Guava User Guide article on <a href= 031 * "https://github.com/google/guava/wiki/NewCollectionTypesExplained#bimap"> {@code BiMap}</a>. 032 * 033 * @author Kevin Bourrillion 034 * @since 2.0 035 */ 036@GwtCompatible 037public interface BiMap<K, V> extends Map<K, V> { 038 // Modification Operations 039 040 /** 041 * {@inheritDoc} 042 * 043 * @throws IllegalArgumentException if the given value is already bound to a different key in this 044 * bimap. The bimap will remain unmodified in this event. To avoid this exception, call {@link 045 * #forcePut} instead. 046 */ 047 @CanIgnoreReturnValue 048 @Override 049 @Nullable 050 V put(@Nullable K key, @Nullable V value); 051 052 /** 053 * An alternate form of {@code put} that silently removes any existing entry with the value {@code 054 * value} before proceeding with the {@link #put} operation. If the bimap previously contained the 055 * provided key-value mapping, this method has no effect. 056 * 057 * <p>Note that a successful call to this method could cause the size of the bimap to increase by 058 * one, stay the same, or even decrease by one. 059 * 060 * <p><b>Warning:</b> If an existing entry with this value is removed, the key for that entry is 061 * discarded and not returned. 062 * 063 * @param key the key with which the specified value is to be associated 064 * @param value the value to be associated with the specified key 065 * @return the value which was previously associated with the key, which may be {@code null}, or 066 * {@code null} if there was no previous entry 067 */ 068 @CanIgnoreReturnValue 069 @Nullable 070 V forcePut(@Nullable K key, @Nullable V value); 071 072 // Bulk Operations 073 074 /** 075 * {@inheritDoc} 076 * 077 * <p><b>Warning:</b> the results of calling this method may vary depending on the iteration order 078 * of {@code map}. 079 * 080 * @throws IllegalArgumentException if an attempt to {@code put} any entry fails. Note that some 081 * map entries may have been added to the bimap before the exception was thrown. 082 */ 083 @Override 084 void putAll(Map<? extends K, ? extends V> map); 085 086 // Views 087 088 /** 089 * {@inheritDoc} 090 * 091 * <p>Because a bimap has unique values, this method returns a {@link Set}, instead of the {@link 092 * java.util.Collection} specified in the {@link Map} interface. 093 */ 094 @Override 095 Set<V> values(); 096 097 /** 098 * Returns the inverse view of this bimap, which maps each of this bimap's values to its 099 * associated key. The two bimaps are backed by the same data; any changes to one will appear in 100 * the other. 101 * 102 * <p><b>Note:</b>There is no guaranteed correspondence between the iteration order of a bimap and 103 * that of its inverse. 104 * 105 * @return the inverse view of this bimap 106 */ 107 BiMap<V, K> inverse(); 108}