java/org/eclipse/xtext/xbase/lib/MapExtensions.java - xtext_lib - Git at Google

 /*******************************************************************************
  * Copyright (c) 2011 itemis AG (http://www.itemis.eu) and others.
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License 2.0 which is available at
  * http://www.eclipse.org/legal/epl-2.0.
  *
  * SPDX-License-Identifier: EPL-2.0
  *******************************************************************************/
 package org.eclipse.xtext.xbase.lib;

 import java.util.Collections;
 import java.util.Map;
 import java.util.Map.Entry;

 import org.eclipse.xtext.xbase.lib.Functions.Function1;
 import org.eclipse.xtext.xbase.lib.Functions.Function2;
 import org.eclipse.xtext.xbase.lib.Procedures.Procedure2;
 import org.eclipse.xtext.xbase.lib.Procedures.Procedure3;
 import org.eclipse.xtext.xbase.lib.internal.FunctionDelegate;
 import org.eclipse.xtext.xbase.lib.internal.UnmodifiableMergingMapView;

 import com.google.common.annotations.GwtCompatible;
 import com.google.common.base.Objects;
 import com.google.common.base.Predicate;
 import com.google.common.collect.Iterables;
 import com.google.common.collect.Maps;


 /**
  * This is an extension library for {@link Map maps}.
  *
  * @author Sebastian Zarnekow - Initial contribution and API
  * @author Stephane Galland - Add operators on map structures.
  */
 @GwtCompatible public class MapExtensions {

 	/**
 	 * Applies the given {@code procedure} for each {@link java.util.Map.Entry key value pair} of the given {@code map}.
 	 *
 	 * @param map
 	 *            the map. May not be <code>null</code>.
 	 * @param procedure
 	 *            the procedure. May not be <code>null</code>.
 	 */
 	public static <K, V> void forEach(Map<K, V> map, Procedure2<? super K, ? super V> procedure) {
 		if (procedure == null)
 			throw new NullPointerException("procedure");
 		for (Map.Entry<K, V> entry : map.entrySet()) {
 			procedure.apply(entry.getKey(), entry.getValue());
 		}
 	}

 	/**
 	 * Applies the given {@code procedure} for each {@link java.util.Map.Entry key value pair} of the given {@code map}.
 	 * The procedure takes the key, the value and a loop counter. If the counter would overflow, {@link Integer#MAX_VALUE}
 	 * is returned for all subsequent pairs. The first pair is at index zero.
 	 *
 	 * @param map
 	 *            the map. May not be <code>null</code>.
 	 * @param procedure
 	 *            the procedure. May not be <code>null</code>.
 	 */
 	public static <K, V> void forEach(Map<K, V> map, Procedure3<? super K, ? super V, ? super Integer> procedure) {
 		if (procedure == null)
 			throw new NullPointerException("procedure");
 		int i = 0;
 		for (Map.Entry<K, V> entry : map.entrySet()) {
 			procedure.apply(entry.getKey(), entry.getValue(), i);
 			if (i != Integer.MAX_VALUE)
 				i++;
 		}
 	}

 	/**
 	 * <p>
 	 * Returns a filtered live view on top of the original map. Changes to one affect the other.
 	 * </p>
 	 *
 	 * <p>
 	 * The mapping is done lazily. That is, subsequent access of the values in the map will repeatedly apply the
 	 * transformation. Characteristics of the original map, such as iteration order, are left intact. Changes in the
 	 * original map are reflected in the result map. The results supports removal if the original map supports removal.
 	 * </p>
 	 *
 	 * @param original
 	 *            the original map. May not be <code>null</code>.
 	 * @param predicate
 	 *            the predicate. May not be <code>null</code>.
 	 * @return a filtered view on top of the original map. Never <code>null</code>.
 	 */
 	public static <K, V> Map<K, V> filter(Map<K, V> original, final Function2<? super K, ? super V, Boolean> predicate) {
 		if (predicate == null)
 			throw new NullPointerException("predicate");
 		return Maps.filterEntries(original, new Predicate<Map.Entry<K, V>>() {
 			@Override
 			public boolean apply(Map.Entry<K, V> input) {
 				Boolean result = predicate.apply(input.getKey(), input.getValue());
 				return result.booleanValue();
 			}
 		});
 	}

 	/**
 	 * Add the given pair into the map.
 	 *
 	 * <p>
 	 * If the pair key already exists in the map, its value is replaced
 	 * by the value in the pair, and the old value in the map is returned.
 	 * </p>
 	 *
 	 * @param <K> type of the map keys.
 	 * @param <V> type of the map values.
 	 * @param map the map to update.
 	 * @param entry the entry (key, value) to add into the map.
 	 * @return the value previously associated to the key, or <code>null</code>
 	 *     if the key was not present in the map before the addition.
 	 * @since 2.15
 	 */
 	@Inline(value = "$1.put($2.getKey(), $2.getValue())", statementExpression = true)
 	public static <K, V> V operator_add(Map<K, V> map, Pair<? extends K, ? extends V> entry) {
 		return map.put(entry.getKey(), entry.getValue());
 	}

 	/**
 	 * Add the given entries of the input map into the output map.
 	 *
 	 * <p>
 	 * If a key in the inputMap already exists in the outputMap, its value is
 	 * replaced in the outputMap by the value from the inputMap.
 	 * </p>
 	 *
 	 * @param <K> type of the map keys.
 	 * @param <V> type of the map values.
 	 * @param outputMap the map to update.
 	 * @param inputMap the entries to add.
 	 * @since 2.15
 	 */
 	@Inline(value = "$1.putAll($2)", statementExpression = true)
 	public static <K, V> void operator_add(Map<K, V> outputMap, Map<? extends K, ? extends V> inputMap) {
 		outputMap.putAll(inputMap);
 	}

 	/**
 	 * Add the given pair to a given map for obtaining a new map.
 	 *
 	 * <p>
 	 * The replied map is a view on the given map. It means that any change
 	 * in the original map is reflected to the result of this operation.
 	 * </p>
 	 *
 	 * <p>
 	 * Even if the key of the right operand exists in the left operand, the value in the right operand is preferred.
 	 * </p>
 	 *
 	 * @param <K> type of the map keys.
 	 * @param <V> type of the map values.
 	 * @param left the map to consider.
 	 * @param right the entry (key, value) to add into the map.
 	 * @return an immutable map with the content of the map and with the given entry.
 	 * @throws IllegalArgumentException - when the right operand key exists in the left operand.
 	 * @since 2.15
 	 */
 	@Pure
 	@Inline(value = "$3.union($1, $4.singletonMap($2.getKey(), $2.getValue()))",
 			imported = { MapExtensions.class, Collections.class })
 	public static <K, V> Map<K, V> operator_plus(Map<K, V> left, final Pair<? extends K, ? extends V> right) {
 		return union(left, Collections.singletonMap(right.getKey(), right.getValue()));
 	}

 	/**
 	 * Merge the two maps.
 	 *
 	 * <p>
 	 * The replied map is a view on the given map. It means that any change
 	 * in the original map is reflected to the result of this operation.
 	 * </p>
 	 *
 	 * <p>
 	 * If a key exists in the left and right operands, the value in the right operand is preferred.
 	 * </p>
 	 *
 	 * @param <K> type of the map keys.
 	 * @param <V> type of the map values.
 	 * @param left the left map.
 	 * @param right the right map.
 	 * @return a map with the merged contents from the two maps.
 	 * @throws IllegalArgumentException - when a right operand key exists in the left operand.
 	 * @since 2.15
 	 */
 	@Pure
 	@Inline(value = "$3.union($1, $2)", imported = MapExtensions.class)
 	public static <K, V> Map<K, V> operator_plus(Map<K, V> left, Map<? extends K, ? extends V> right) {
 		return union(left, right);
 	}

 	/**
 	 * Remove a key from the given map.
 	 *
 	 * @param <K> type of the map keys.
 	 * @param <V> type of the map values.
 	 * @param map the map to update.
 	 * @param key the key to remove.
 	 * @return the removed value, or <code>null</code> if the key was not
 	 *     present in the map.
 	 * @since 2.15
 	 */
 	@Inline(value = "$1.remove($2)", statementExpression = true)
 	public static <K, V> V operator_remove(Map<K, V> map, K key) {
 		return map.remove(key);
 	}

 	/**
 	 * Remove the given pair into the map.
 	 *
 	 * <p>
 	 * If the given key is inside the map, but is not mapped to the given value, the
 	 * map will not be changed.
 	 * </p>
 	 *
 	 * @param <K> type of the map keys.
 	 * @param <V> type of the map values.
 	 * @param map the map to update.
 	 * @param entry the entry (key, value) to remove from the map.
 	 * @return {@code true} if the pair was removed.
 	 * @since 2.15
 	 */
 	@Inline(value = "$1.remove($2.getKey(), $2.getValue())", statementExpression = true)
 	public static <K, V> boolean operator_remove(Map<K, V> map, Pair<? extends K, ? extends V> entry) {
 		//TODO use the JRE 1.8 API: map.remove(entry.getKey(), entry.getValue());
 		final K key = entry.getKey();
 		final V storedValue = map.get(entry.getKey());
 	        if (!Objects.equal(storedValue, entry.getValue())
 			|| (storedValue == null && !map.containsKey(key))) {
 	            return false;
         	}
         	map.remove(key);
 	        return true;
 	}

 	/**
 	 * Remove pairs with the given keys from the map.
 	 *
 	 * @param <K> type of the map keys.
 	 * @param <V> type of the map values.
 	 * @param map the map to update.
 	 * @param keysToRemove the keys of the pairs to remove.
 	 * @since 2.15
 	 */
 	public static <K, V> void operator_remove(Map<K, V> map, Iterable<? super K> keysToRemove) {
 		for (final Object key : keysToRemove) {
 			map.remove(key);
 		}
 	}

 	/**
 	 * Remove the given pair from a given map for obtaining a new map.
 	 *
 	 * <p>
 	 * If the given key is inside the map, but is not mapped to the given value, the
 	 * map will not be changed.
 	 * </p>
 	 *
 	 * <p>
 	 * The replied map is a view on the given map. It means that any change
 	 * in the original map is reflected to the result of this operation.
 	 * </p>
 	 *
 	 * @param <K> type of the map keys.
 	 * @param <V> type of the map values.
 	 * @param left the map to consider.
 	 * @param right the entry (key, value) to remove from the map.
 	 * @return an immutable map with the content of the map and with the given entry.
 	 * @throws IllegalArgumentException - when the right operand key exists in the left operand.
 	 * @since 2.15
 	 */
 	@Pure
 	public static <K, V> Map<K, V> operator_minus(Map<K, V> left, final Pair<? extends K, ? extends V> right) {
 		return Maps.filterEntries(left, new Predicate<Entry<K, V>>() {
 			@Override
 			public boolean apply(Entry<K, V> input) {
 				return !Objects.equal(input.getKey(), right.getKey()) || !Objects.equal(input.getValue(), right.getValue());
 			}
 		});
 	}

 	/**
 	 * Replies the elements of the given map except the pair with the given key.
 	 *
 	 * <p>
 	 * The replied map is a view on the given map. It means that any change
 	 * in the original map is reflected to the result of this operation.
 	 * </p>
 	 *
 	 * @param <K> type of the map keys.
 	 * @param <V> type of the map values.
 	 * @param map the map to update.
 	 * @param key the key to remove.
 	 * @return the map with the content of the map except the key.
 	 * @since 2.15
 	 */
 	@Pure
 	public static <K, V> Map<K, V> operator_minus(Map<K, V> map, final K key) {
 		return Maps.filterKeys(map, new Predicate<K>() {
 			@Override
 			public boolean apply(K input) {
 				return !Objects.equal(input, key);
 			}
 		});
 	}

 	/**
 	 * Replies the elements of the left map without the pairs in the right map.
 	 * If the pair's values differ from
 	 * the value within the map, the map entry is not removed.
 	 *
 	 * <p>
 	 * The difference is an immutable
 	 * snapshot of the state of the maps at the time this method is called. It
 	 * will never change, even if the maps change at a later time.
 	 * </p>
 	 *
 	 * <p>
 	 * Since this method uses {@code HashMap} instances internally, the keys of
 	 * the supplied maps must be well-behaved with respect to
 	 * {@link Object#equals} and {@link Object#hashCode}.
 	 * </p>
 	 *
 	 * @param <K> type of the map keys.
 	 * @param <V> type of the map values.
 	 * @param left the map to update.
 	 * @param right the pairs to remove.
 	 * @return the map with the content of the left map except the pairs of the right map.
 	 * @since 2.15
 	 */
 	@Pure
 	public static <K, V> Map<K, V> operator_minus(Map<K, V> left, final Map<? extends K, ? extends V> right) {
 		return Maps.filterEntries(left, new Predicate<Entry<K, V>>() {
 			@Override
 			public boolean apply(Entry<K, V> input) {
 				final V value = right.get(input.getKey());
 				if (value == null) {
 					return input.getValue() == null && right.containsKey(input.getKey());
 				}
 				return !Objects.equal(input.getValue(), value);
 			}
 		});
 	}

 	/**
 	 * Replies the elements of the given map except the pairs with the given keys.
 	 *
 	 * <p>
 	 * The replied map is a view on the given map. It means that any change
 	 * in the original map is reflected to the result of this operation.
 	 * </p>
 	 *
 	 * @param <K> type of the map keys.
 	 * @param <V> type of the map values.
 	 * @param map the map to update.
 	 * @param keys the keys of the pairs to remove.
 	 * @return the map with the content of the map except the pairs.
 	 * @since 2.15
 	 */
 	@Pure
 	public static <K, V> Map<K, V> operator_minus(Map<K, V> map, final Iterable<?> keys) {
 		return Maps.filterKeys(map, new Predicate<K>() {
 			@Override
 			public boolean apply(K input) {
 				return !Iterables.contains(keys, input);
 			}
 		});
 	}

 	/**
 	 * Merge the given maps.
 	 *
 	 * <p>
 	 * The replied map is a view on the given two maps.
 	 * If a key exists in the two maps, the replied value is the value of the right operand.
 	 * </p>
 	 *
 	 * <p>
 	 * Even if the key of the right operand exists in the left operand, the value in the right operand is preferred.
 	 * </p>
 	 *
 	 * <p>
 	 * The replied map is unmodifiable.
 	 * </p>
 	 *
 	 * @param <K> type of the map keys.
 	 * @param <V> type of the map values.
 	 * @param left the left map.
 	 * @param right the right map.
 	 * @return a map with the merged contents from the two maps.
 	 * @since 2.15
 	 */
 	@Pure
 	@Inline(value = "(new $3<$5, $6>($1, $2))", imported = UnmodifiableMergingMapView.class, constantExpression = true)
 	public static <K, V> Map<K, V> union(Map<? extends K, ? extends V> left, Map<? extends K, ? extends V> right) {
 		return new UnmodifiableMergingMapView<K, V>(left, right);
 	}

 	/**
 	 * <p>Returns a map that performs the given {@code transformation} for each value of {@code original} when requested.</p>
 	 *
 	 * <p>The mapping is done lazily. That is, subsequent access of the values in the map will repeatedly apply the
 	 * transformation. Characteristics of the original map, such as iteration order, are left intact. Changes in the
 	 * original map are reflected in the result map. The results supports removal if the original map supports removal.</p>
 	 *
 	 * @param original
 	 *            the original map. May not be <code>null</code>.
 	 * @param transformation
 	 *            the transformation. May not be <code>null</code>.
 	 * @return a map with equal keys but transformed values. Never <code>null</code>.
 	 * @since 2.4
 	 */
 	@Pure
 	public static <K, V1, V2> Map<K, V2> mapValues(Map<K, V1> original, Function1<? super V1, ? extends V2> transformation) {
 		return Maps.transformValues(original, new FunctionDelegate<V1, V2>(transformation));
 	}

 }
	/*******************************************************************************
	* Copyright (c) 2011 itemis AG (http://www.itemis.eu) and others.
	* This program and the accompanying materials are made available under the
	* terms of the Eclipse Public License 2.0 which is available at
	* http://www.eclipse.org/legal/epl-2.0.
	*
	* SPDX-License-Identifier: EPL-2.0
	*******************************************************************************/
	package org.eclipse.xtext.xbase.lib;

	import java.util.Collections;
	import java.util.Map;
	import java.util.Map.Entry;

	import org.eclipse.xtext.xbase.lib.Functions.Function1;
	import org.eclipse.xtext.xbase.lib.Functions.Function2;
	import org.eclipse.xtext.xbase.lib.Procedures.Procedure2;
	import org.eclipse.xtext.xbase.lib.Procedures.Procedure3;
	import org.eclipse.xtext.xbase.lib.internal.FunctionDelegate;
	import org.eclipse.xtext.xbase.lib.internal.UnmodifiableMergingMapView;

	import com.google.common.annotations.GwtCompatible;
	import com.google.common.base.Objects;
	import com.google.common.base.Predicate;
	import com.google.common.collect.Iterables;
	import com.google.common.collect.Maps;


	/**
	* This is an extension library for {@link Map maps}.
	*
	* @author Sebastian Zarnekow - Initial contribution and API
	* @author Stephane Galland - Add operators on map structures.
	*/
	@GwtCompatible public class MapExtensions {

	/**
	* Applies the given {@code procedure} for each {@link java.util.Map.Entry key value pair} of the given {@code map}.
	*
	* @param map
	* the map. May not be <code>null</code>.
	* @param procedure
	* the procedure. May not be <code>null</code>.
	*/
	public static <K, V> void forEach(Map<K, V> map, Procedure2<? super K, ? super V> procedure) {
	if (procedure == null)
	throw new NullPointerException("procedure");
	for (Map.Entry<K, V> entry : map.entrySet()) {
	procedure.apply(entry.getKey(), entry.getValue());
	}
	}

	/**
	* Applies the given {@code procedure} for each {@link java.util.Map.Entry key value pair} of the given {@code map}.
	* The procedure takes the key, the value and a loop counter. If the counter would overflow, {@link Integer#MAX_VALUE}
	* is returned for all subsequent pairs. The first pair is at index zero.
	*
	* @param map
	* the map. May not be <code>null</code>.
	* @param procedure
	* the procedure. May not be <code>null</code>.
	*/
	public static <K, V> void forEach(Map<K, V> map, Procedure3<? super K, ? super V, ? super Integer> procedure) {
	if (procedure == null)
	throw new NullPointerException("procedure");
	int i = 0;
	for (Map.Entry<K, V> entry : map.entrySet()) {
	procedure.apply(entry.getKey(), entry.getValue(), i);
	if (i != Integer.MAX_VALUE)
	i++;
	}
	}

	/**
	* <p>
	* Returns a filtered live view on top of the original map. Changes to one affect the other.
	* </p>
	*
	* <p>
	* The mapping is done lazily. That is, subsequent access of the values in the map will repeatedly apply the
	* transformation. Characteristics of the original map, such as iteration order, are left intact. Changes in the
	* original map are reflected in the result map. The results supports removal if the original map supports removal.
	* </p>
	*
	* @param original
	* the original map. May not be <code>null</code>.
	* @param predicate
	* the predicate. May not be <code>null</code>.
	* @return a filtered view on top of the original map. Never <code>null</code>.
	*/
	public static <K, V> Map<K, V> filter(Map<K, V> original, final Function2<? super K, ? super V, Boolean> predicate) {
	if (predicate == null)
	throw new NullPointerException("predicate");
	return Maps.filterEntries(original, new Predicate<Map.Entry<K, V>>() {
	@Override
	public boolean apply(Map.Entry<K, V> input) {
	Boolean result = predicate.apply(input.getKey(), input.getValue());
	return result.booleanValue();
	}
	});
	}

	/**
	* Add the given pair into the map.
	*
	* <p>
	* If the pair key already exists in the map, its value is replaced
	* by the value in the pair, and the old value in the map is returned.
	* </p>
	*
	* @param <K> type of the map keys.
	* @param <V> type of the map values.
	* @param map the map to update.
	* @param entry the entry (key, value) to add into the map.
	* @return the value previously associated to the key, or <code>null</code>
	* if the key was not present in the map before the addition.
	* @since 2.15
	*/
	@Inline(value = "$1.put($2.getKey(), $2.getValue())", statementExpression = true)
	public static <K, V> V operator_add(Map<K, V> map, Pair<? extends K, ? extends V> entry) {
	return map.put(entry.getKey(), entry.getValue());
	}

	/**
	* Add the given entries of the input map into the output map.
	*
	* <p>
	* If a key in the inputMap already exists in the outputMap, its value is
	* replaced in the outputMap by the value from the inputMap.
	* </p>
	*
	* @param <K> type of the map keys.
	* @param <V> type of the map values.
	* @param outputMap the map to update.
	* @param inputMap the entries to add.
	* @since 2.15
	*/
	@Inline(value = "$1.putAll($2)", statementExpression = true)
	public static <K, V> void operator_add(Map<K, V> outputMap, Map<? extends K, ? extends V> inputMap) {
	outputMap.putAll(inputMap);
	}

	/**
	* Add the given pair to a given map for obtaining a new map.
	*
	* <p>
	* The replied map is a view on the given map. It means that any change
	* in the original map is reflected to the result of this operation.
	* </p>
	*
	* <p>
	* Even if the key of the right operand exists in the left operand, the value in the right operand is preferred.
	* </p>
	*
	* @param <K> type of the map keys.
	* @param <V> type of the map values.
	* @param left the map to consider.
	* @param right the entry (key, value) to add into the map.
	* @return an immutable map with the content of the map and with the given entry.
	* @throws IllegalArgumentException - when the right operand key exists in the left operand.
	* @since 2.15
	*/
	@Pure
	@Inline(value = "$3.union($1, $4.singletonMap($2.getKey(), $2.getValue()))",
	imported = { MapExtensions.class, Collections.class })
	public static <K, V> Map<K, V> operator_plus(Map<K, V> left, final Pair<? extends K, ? extends V> right) {
	return union(left, Collections.singletonMap(right.getKey(), right.getValue()));
	}

	/**
	* Merge the two maps.
	*
	* <p>
	* The replied map is a view on the given map. It means that any change
	* in the original map is reflected to the result of this operation.
	* </p>
	*
	* <p>
	* If a key exists in the left and right operands, the value in the right operand is preferred.
	* </p>
	*
	* @param <K> type of the map keys.
	* @param <V> type of the map values.
	* @param left the left map.
	* @param right the right map.
	* @return a map with the merged contents from the two maps.
	* @throws IllegalArgumentException - when a right operand key exists in the left operand.
	* @since 2.15
	*/
	@Pure
	@Inline(value = "$3.union($1, $2)", imported = MapExtensions.class)
	public static <K, V> Map<K, V> operator_plus(Map<K, V> left, Map<? extends K, ? extends V> right) {
	return union(left, right);
	}

	/**
	* Remove a key from the given map.
	*
	* @param <K> type of the map keys.
	* @param <V> type of the map values.
	* @param map the map to update.
	* @param key the key to remove.
	* @return the removed value, or <code>null</code> if the key was not
	* present in the map.
	* @since 2.15
	*/
	@Inline(value = "$1.remove($2)", statementExpression = true)
	public static <K, V> V operator_remove(Map<K, V> map, K key) {
	return map.remove(key);
	}

	/**
	* Remove the given pair into the map.
	*
	* <p>
	* If the given key is inside the map, but is not mapped to the given value, the
	* map will not be changed.
	* </p>
	*
	* @param <K> type of the map keys.
	* @param <V> type of the map values.
	* @param map the map to update.
	* @param entry the entry (key, value) to remove from the map.
	* @return {@code true} if the pair was removed.
	* @since 2.15
	*/
	@Inline(value = "$1.remove($2.getKey(), $2.getValue())", statementExpression = true)
	public static <K, V> boolean operator_remove(Map<K, V> map, Pair<? extends K, ? extends V> entry) {
	//TODO use the JRE 1.8 API: map.remove(entry.getKey(), entry.getValue());
	final K key = entry.getKey();
	final V storedValue = map.get(entry.getKey());
	if (!Objects.equal(storedValue, entry.getValue())
	\|\| (storedValue == null && !map.containsKey(key))) {
	return false;
	}
	map.remove(key);
	return true;
	}

	/**
	* Remove pairs with the given keys from the map.
	*
	* @param <K> type of the map keys.
	* @param <V> type of the map values.
	* @param map the map to update.
	* @param keysToRemove the keys of the pairs to remove.
	* @since 2.15
	*/
	public static <K, V> void operator_remove(Map<K, V> map, Iterable<? super K> keysToRemove) {
	for (final Object key : keysToRemove) {
	map.remove(key);
	}
	}

	/**
	* Remove the given pair from a given map for obtaining a new map.
	*
	* <p>
	* If the given key is inside the map, but is not mapped to the given value, the
	* map will not be changed.
	* </p>
	*
	* <p>
	* The replied map is a view on the given map. It means that any change
	* in the original map is reflected to the result of this operation.
	* </p>
	*
	* @param <K> type of the map keys.
	* @param <V> type of the map values.
	* @param left the map to consider.
	* @param right the entry (key, value) to remove from the map.
	* @return an immutable map with the content of the map and with the given entry.
	* @throws IllegalArgumentException - when the right operand key exists in the left operand.
	* @since 2.15
	*/
	@Pure
	public static <K, V> Map<K, V> operator_minus(Map<K, V> left, final Pair<? extends K, ? extends V> right) {
	return Maps.filterEntries(left, new Predicate<Entry<K, V>>() {
	@Override
	public boolean apply(Entry<K, V> input) {
	return !Objects.equal(input.getKey(), right.getKey()) \|\| !Objects.equal(input.getValue(), right.getValue());
	}
	});
	}

	/**
	* Replies the elements of the given map except the pair with the given key.
	*
	* <p>
	* The replied map is a view on the given map. It means that any change
	* in the original map is reflected to the result of this operation.
	* </p>
	*
	* @param <K> type of the map keys.
	* @param <V> type of the map values.
	* @param map the map to update.
	* @param key the key to remove.
	* @return the map with the content of the map except the key.
	* @since 2.15
	*/
	@Pure
	public static <K, V> Map<K, V> operator_minus(Map<K, V> map, final K key) {
	return Maps.filterKeys(map, new Predicate<K>() {
	@Override
	public boolean apply(K input) {
	return !Objects.equal(input, key);
	}
	});
	}

	/**
	* Replies the elements of the left map without the pairs in the right map.
	* If the pair's values differ from
	* the value within the map, the map entry is not removed.
	*
	* <p>
	* The difference is an immutable
	* snapshot of the state of the maps at the time this method is called. It
	* will never change, even if the maps change at a later time.
	* </p>
	*
	* <p>
	* Since this method uses {@code HashMap} instances internally, the keys of
	* the supplied maps must be well-behaved with respect to
	* {@link Object#equals} and {@link Object#hashCode}.
	* </p>
	*
	* @param <K> type of the map keys.
	* @param <V> type of the map values.
	* @param left the map to update.
	* @param right the pairs to remove.
	* @return the map with the content of the left map except the pairs of the right map.
	* @since 2.15
	*/
	@Pure
	public static <K, V> Map<K, V> operator_minus(Map<K, V> left, final Map<? extends K, ? extends V> right) {
	return Maps.filterEntries(left, new Predicate<Entry<K, V>>() {
	@Override
	public boolean apply(Entry<K, V> input) {
	final V value = right.get(input.getKey());
	if (value == null) {
	return input.getValue() == null && right.containsKey(input.getKey());
	}
	return !Objects.equal(input.getValue(), value);
	}
	});
	}

	/**
	* Replies the elements of the given map except the pairs with the given keys.
	*
	* <p>
	* The replied map is a view on the given map. It means that any change
	* in the original map is reflected to the result of this operation.
	* </p>
	*
	* @param <K> type of the map keys.
	* @param <V> type of the map values.
	* @param map the map to update.
	* @param keys the keys of the pairs to remove.
	* @return the map with the content of the map except the pairs.
	* @since 2.15
	*/
	@Pure
	public static <K, V> Map<K, V> operator_minus(Map<K, V> map, final Iterable<?> keys) {
	return Maps.filterKeys(map, new Predicate<K>() {
	@Override
	public boolean apply(K input) {
	return !Iterables.contains(keys, input);
	}
	});
	}

	/**
	* Merge the given maps.
	*
	* <p>
	* The replied map is a view on the given two maps.
	* If a key exists in the two maps, the replied value is the value of the right operand.
	* </p>
	*
	* <p>
	* Even if the key of the right operand exists in the left operand, the value in the right operand is preferred.
	* </p>
	*
	* <p>
	* The replied map is unmodifiable.
	* </p>
	*
	* @param <K> type of the map keys.
	* @param <V> type of the map values.
	* @param left the left map.
	* @param right the right map.
	* @return a map with the merged contents from the two maps.
	* @since 2.15
	*/
	@Pure
	@Inline(value = "(new $3<$5, $6>($1, $2))", imported = UnmodifiableMergingMapView.class, constantExpression = true)
	public static <K, V> Map<K, V> union(Map<? extends K, ? extends V> left, Map<? extends K, ? extends V> right) {
	return new UnmodifiableMergingMapView<K, V>(left, right);
	}

	/**
	* <p>Returns a map that performs the given {@code transformation} for each value of {@code original} when requested.</p>
	*
	* <p>The mapping is done lazily. That is, subsequent access of the values in the map will repeatedly apply the
	* transformation. Characteristics of the original map, such as iteration order, are left intact. Changes in the
	* original map are reflected in the result map. The results supports removal if the original map supports removal.</p>
	*
	* @param original
	* the original map. May not be <code>null</code>.
	* @param transformation
	* the transformation. May not be <code>null</code>.
	* @return a map with equal keys but transformed values. Never <code>null</code>.
	* @since 2.4
	*/
	@Pure
	public static <K, V1, V2> Map<K, V2> mapValues(Map<K, V1> original, Function1<? super V1, ? extends V2> transformation) {
	return Maps.transformValues(original, new FunctionDelegate<V1, V2>(transformation));
	}

	}