Map.drv

/*
 * Copyright (C) 2002-2024 Sebastiano Vigna
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */


package PACKAGE;

#if KEY_INDEX != VALUE_INDEX && !(KEYS_REFERENCE && VALUES_REFERENCE)
import VALUE_PACKAGE.VALUE_COLLECTION;
#endif

#if KEYS_PRIMITIVE
import it.unimi.dsi.fastutil.objects.ObjectSet;
import it.unimi.dsi.fastutil.objects.ObjectIterator;
#endif

import java.util.function.Consumer;
import java.util.Map;

#if !KEYS_USE_REFERENCE_EQUALITY && !VALUES_USE_REFERENCE_EQUALITY
/** A type-specific {@link Map}; provides some additional methods that use polymorphism to avoid (un)boxing, and handling of a default return value.
 *
 * <p>Besides extending the corresponding type-specific {@linkplain it.unimi.dsi.fastutil.Function function}, this interface strengthens {@link Map#entrySet()},
 * {@link #keySet()} and {@link #values()}. Moreover, a number of methods, such as {@link #size()}, {@link #defaultReturnValue()}, etc., are un-defaulted
 * as their function default do not make sense for a map.
 * Maps returning entry sets of type {@link FastEntrySet} support also fast iteration.
 *
 * <p>A submap or subset may or may not have an
 * independent default return value (which however must be initialized to the
 * default return value of the originator).
 *
 * @see Map
 */
#else
/** A type-specific {@link Map}; provides some additional methods that use polymorphism to avoid (un)boxing, and handling of a default return value.
 *
 * <p>Besides extending the corresponding type-specific {@linkplain it.unimi.dsi.fastutil.Function function}, this interface strengthens {@link Map#entrySet()},
 * {@link #keySet()} and {@link #values()}. Moreover, a number of methods, such as {@link #size()}, {@link #defaultReturnValue()}, etc., are un-defaulted
 * as their function default do not make sense for a map.
 * Maps returning entry sets of type {@link FastEntrySet} support also fast iteration.
 *
 * <p>This interface specifies reference equality semantics (members will be compared equal with
 * {@code ==} instead of {@link Object#equals(Object) equals}) for its keys or values (or both), which may result in breaks in contract
 * if attempted to be used with non reference-equality semantics based {@link Map}s. For example, a
 * {@code aReferenceToIntMap.equals(aObjectToIntMap)} may return different a different result then
 * {@code aObjectToIntMap.equals(aReferenceToIntMap)}, in violation of {@link Object#equals equals}'s
 * contract requiring it being symmetric.
 *
 * <p>A submap or subset may or may not have an
 * independent default return value (which however must be initialized to the
 * default return value of the originator).
 *
 * @see Map
 */
#endif
public interface MAP KEY_VALUE_GENERIC extends FUNCTION KEY_VALUE_GENERIC, Map<KEY_GENERIC_CLASS,VALUE_GENERIC_CLASS> {

	/** An entry set providing fast iteration.
	 *
	 * <p>In some cases (e.g., hash-based classes) iteration over an entry set requires the creation
	 * of a large number of {@link java.util.Map.Entry} objects. Some {@code fastutil}
	 * maps might return {@linkplain Map#entrySet() entry set} objects of type {@code FastEntrySet}: in this case, {@link #fastIterator() fastIterator()}
	 * will return an iterator that is guaranteed not to create a large number of objects, <em>possibly
	 * by returning always the same entry</em> (of course, mutated), and {@link #fastForEach(Consumer)} will apply
	 * the provided consumer to all elements of the entry set, <em>which might be represented
	 * always by the same entry</em> (of course, mutated).
	 */

	interface FastEntrySet KEY_VALUE_GENERIC extends ObjectSet<MAP.Entry KEY_VALUE_GENERIC> {
		/** Returns a fast iterator over this entry set; the iterator might return always the same entry instance, suitably mutated.
		 *
		 * @return a fast iterator over this entry set; the iterator might return always the same {@link java.util.Map.Entry} instance, suitably mutated.
		 */
		ObjectIterator<MAP.Entry KEY_VALUE_GENERIC> fastIterator();

		/** Iterates quickly over this entry set; the iteration might happen always on the same entry instance, suitably mutated.
		 *
		 * <p>This default implementation just delegates to {@link #forEach(Consumer)}.
		 *
		 * @param consumer a consumer that will by applied to the entries of this set; the entries might be represented
		 * by the same entry instance, suitably mutated.
		 * @since 8.1.0
		 */
		default void fastForEach(final Consumer<? super MAP.Entry KEY_VALUE_GENERIC> consumer) {
			forEach(consumer);
		}
	}

	/**
	 * Returns the number of key/value mappings in this map.  If the
	 * map contains more than {@link Integer#MAX_VALUE} elements, returns {@link Integer#MAX_VALUE}.
	 *
	 * @return the number of key-value mappings in this map.
	 * @see it.unimi.dsi.fastutil.Size64
	 */

	@Override
	int size();

	/** Removes all of the mappings from this map (optional operation).
	 * The map will be empty after this call returns.
	 *
	 * @throws UnsupportedOperationException if the {@link #clear()} operation is not supported by this map
	 */

	@Override
	default void clear() { throw new UnsupportedOperationException(); }

#if VALUES_PRIMITIVE
	/** Sets the default return value (optional operation).
	 *
	 * This value must be returned by type-specific versions of {@code get()},
	 * {@code put()} and {@code remove()} to denote that the map does not contain
	 * the specified key. It must be 0/{@code false} by default.
	 *
	 * @param rv the new default return value.
	 * @see #defaultReturnValue()
	 */
#else
	/** Sets the default return value (optional operation).
	 *
	 * This value must be returned by type-specific versions of {@code get()},
	 * {@code put()} and {@code remove()} to denote that the map does not contain
	 * the specified key. It must be {@code null} by default.
	 *
	 * <p><strong>Warning</strong>: Changing this to a non-null value can have
	 * unforeseen consequences. Especially, it breaks compatibility with the
	 * specifications of Java's {@link java.util.Map} interface. It has to be
	 * used with great care and thorough study of all method comments is
	 * recommended.
	 *
	 * @param rv the new default return value.
	 * @see #defaultReturnValue()
	 */
#endif

	@Override
	void defaultReturnValue(VALUE_GENERIC_TYPE rv);

	/** Gets the default return value.
	 *
	 * @return the current default return value.
	 */

	@Override
	VALUE_GENERIC_TYPE defaultReturnValue();

	/** Returns a type-specific set view of the mappings contained in this map.
	 *
	 * <p>This method is necessary because there is no inheritance along
	 * type parameters: it is thus impossible to strengthen {@link Map#entrySet()}
	 * so that it returns an {@link it.unimi.dsi.fastutil.objects.ObjectSet}
	 * of type-specific entries (the latter makes it possible to
	 * access keys and values with type-specific methods).
	 *
	 * @return a type-specific set view of the mappings contained in this map.
	 * @see Map#entrySet()
	 */
	ObjectSet<MAP.Entry KEY_VALUE_GENERIC> ENTRYSET();

#if KEYS_PRIMITIVE || VALUES_PRIMITIVE
	/** Returns a set view of the mappings contained in this map.
	 *  @apiNote Note that this specification strengthens the one given in {@link Map#entrySet()}.
	 *
	 * @return a set view of the mappings contained in this map.
	 * @see Map#entrySet()
	 * @deprecated Please use the corresponding type-specific method instead.
	 */
	@Deprecated
	@Override
	@SuppressWarnings({ "unchecked", "rawtypes" })
	default ObjectSet<Map.Entry<KEY_GENERIC_CLASS, VALUE_GENERIC_CLASS>> entrySet() {
		return (ObjectSet)ENTRYSET();
	}
#else
	/** Returns a set view of the mappings contained in this map.
	 *  @apiNote Note that this specification strengthens the one given in {@link Map#entrySet()}.
	 *
	 * @return a set view of the mappings contained in this map.
	 * @see Map#entrySet()
	 */

	@Override
	@SuppressWarnings({ "unchecked", "rawtypes" })
	default ObjectSet<Map.Entry<KEY_GENERIC_CLASS, VALUE_GENERIC_CLASS>> entrySet() {
		return (ObjectSet)ENTRYSET();
	}
#endif

#if KEYS_PRIMITIVE || VALUES_PRIMITIVE
	/** {@inheritDoc}
	 * <p>This default implementation just delegates to the corresponding type-specific&ndash;{@linkplain it.unimi.dsi.fastutil.Function function} method.
	 * @deprecated Please use the corresponding type-specific method instead. */
	@Deprecated
#else
	/** {@inheritDoc}
	 * <p>This default implementation just delegates to the corresponding function method.
	 */
#endif
	@Override
	default VALUE_GENERIC_CLASS put(final KEY_GENERIC_CLASS key, final VALUE_GENERIC_CLASS value) {
		return FUNCTION.super.put(key, value);
	}

#if KEYS_PRIMITIVE || VALUES_PRIMITIVE

	/** {@inheritDoc}
	 * <p>This default implementation just delegates to the corresponding type-specific&ndash;{@linkplain it.unimi.dsi.fastutil.Function function} method.
	 * @deprecated Please use the corresponding type-specific method instead. */
	@Deprecated
	@Override
	default VALUE_GENERIC_CLASS get(final Object key) {
		return FUNCTION.super.get(key);
	}

#endif

#if KEYS_PRIMITIVE || VALUES_PRIMITIVE
	/** {@inheritDoc}
	 * <p>This default implementation just delegates to the corresponding type-specific&ndash;{@linkplain it.unimi.dsi.fastutil.Function function} method.
	 * @deprecated Please use the corresponding type-specific method instead. */
	@Deprecated
#else
	/** {@inheritDoc}
	 * <p>This default implementation just delegates to the corresponding type-specific&ndash;{@linkplain it.unimi.dsi.fastutil.Function function} method.
	 */
#endif
	@Override
	default VALUE_GENERIC_CLASS remove(final Object key) {
		return FUNCTION.super.remove(key);
	}

	/** {@inheritDoc}
	 * @apiNote Note that this specification strengthens the one given in {@link Map#keySet()}.
	 * @return a set view of the keys contained in this map.
	 * @see Map#keySet()
	 */

	@Override
	SET KEY_GENERIC keySet();

	/** {@inheritDoc}
	 * @apiNote Note that this specification strengthens the one given in {@link Map#values()}.
	 * @return a set view of the values contained in this map.
	 * @see Map#values()
	 */

	@Override
	VALUE_COLLECTION VALUE_GENERIC values();

#if KEYS_PRIMITIVE

	/** Returns true if this function contains a mapping for the specified key.
	 *
	 * @param key the key.
	 * @return true if this function associates a value to {@code key}.
	 * @see Map#containsKey(Object)
	 */

	@Override
	boolean containsKey(KEY_TYPE key);

	/** Returns true if this function contains a mapping for the specified key.
	 * <p>This default implementation just delegates to the corresponding type-specific&ndash;{@linkplain it.unimi.dsi.fastutil.Function function} method.
	 * @deprecated Please use the corresponding type-specific method instead.
	 */

	@Deprecated
	@Override
	default boolean containsKey(final Object key) {
		return FUNCTION.super.containsKey(key);
	}
#else

	/** Returns true if this function contains a mapping for the specified key.
	 *
	 * @param key the key.
	 * @return true if this function associates a value to {@code key}.
	 * @see Map#containsKey(Object)
	 */

	@Override
	boolean containsKey(Object key);

#endif

#if VALUES_PRIMITIVE

	/** Returns {@code true} if this map maps one or more keys to the specified value.
	 * @see Map#containsValue(Object)
	 */

	boolean containsValue(VALUE_TYPE value);

	/** {@inheritDoc}
	 * @deprecated Please use the corresponding type-specific method instead. */

	@Deprecated
	@Override
	default boolean containsValue(final Object value) {
		return value == null ? false : containsValue(VALUE_OBJ2TYPE(value));
	}

#endif

	// Defaultable methods

	@Override
	default void forEach(final java.util.function.BiConsumer<? super KEY_GENERIC_CLASS, ? super VALUE_GENERIC_CLASS> consumer) {
		final ObjectSet<MAP.Entry KEY_VALUE_GENERIC> entrySet = ENTRYSET();
		final Consumer<MAP.Entry KEY_VALUE_GENERIC> wrappingConsumer = (entry) -> consumer.accept(KEY2OBJ(entry.ENTRY_GET_KEY()), VALUE2OBJ(entry.ENTRY_GET_VALUE()));
		if (entrySet instanceof FastEntrySet) {
			((FastEntrySet KEY_VALUE_GENERIC)entrySet).fastForEach(wrappingConsumer);
		} else {
			entrySet.forEach(wrappingConsumer);
		}
	}


	/** Returns the value to which the specified key is mapped, or the {@code defaultValue} if this
	 * map contains no mapping for the key.
	 *
	 * @param key the key.
	 * @param defaultValue the default mapping of the key.
	 *
	 * @return the value to which the specified key is mapped, or the {@code defaultValue} if this map contains no mapping for the key.
	 *
	 * @see java.util.Map#getOrDefault(Object, Object)
	 * @since 8.0.0
	 */
	@Override	
	default VALUE_GENERIC_TYPE getOrDefault(final KEY_TYPE key, final VALUE_GENERIC_TYPE defaultValue) {
		final VALUE_GENERIC_TYPE v;
		return ((v = GET_VALUE(key)) != defaultReturnValue() || containsKey(key)) ? v : defaultValue;
	}

#if KEYS_PRIMITIVE || VALUES_PRIMITIVE
	/** {@inheritDoc}
	 * <p>This default implementation just delegates to the corresponding {@link Map} method.
	 * @deprecated Please use the corresponding type-specific method instead. */
	@Deprecated
	@Override
	default VALUE_GENERIC_CLASS getOrDefault(final Object key, final VALUE_GENERIC_CLASS defaultValue) {
		return Map.super.getOrDefault(key, defaultValue);
	}
#endif

	/** If the specified key is not already associated with a value, associates it with the given
	 * value and returns the {@linkplain #defaultReturnValue() default return value}, else returns
	 * the current value.
	 *
	 * @param key key with which the specified value is to be associated.
	 * @param value value to be associated with the specified key.
	 *
	 * @return the previous value associated with the specified key, or the {@linkplain #defaultReturnValue() default return value} if there was no mapping for the key.
	 *
	 * @see java.util.Map#putIfAbsent(Object, Object)
	 * @since 8.0.0
	 */

	default VALUE_GENERIC_TYPE putIfAbsent(final KEY_GENERIC_TYPE key, final VALUE_GENERIC_TYPE value) {
		final VALUE_GENERIC_TYPE v = GET_VALUE(key), drv = defaultReturnValue();
		if (v != drv || containsKey(key)) return v;
		put(key, value);
		return drv;
	}

	/** Removes the entry for the specified key only if it is currently mapped to the specified value.
	 *
	 * @param key key with which the specified value is associated.
	 * @param value value expected to be associated with the specified key.
	 *
	 * @return {@code true} if the value was removed.
	 *
	 * @see java.util.Map#remove(Object, Object)
	 * @since 8.0.0
	 */

	default boolean remove(final KEY_TYPE key, final VALUE_TYPE value) {
		final VALUE_GENERIC_TYPE curValue = GET_VALUE(key);
		if (!VALUE_EQUALS(curValue, value) || (curValue == defaultReturnValue() && !containsKey(key))) return false;
		REMOVE_VALUE(key);
		return true;
	}

	/** Replaces the entry for the specified key only if currently mapped to the specified value.
	 *
	 * @param key key with which the specified value is associated.
	 * @param oldValue value expected to be associated with the specified key.
	 * @param newValue value to be associated with the specified key.
	 *
	 * @return {@code true} if the value was replaced.
	 *
	 * @see java.util.Map#replace(Object, Object, Object)
	 * @since 8.0.0
	 */

	default boolean replace(final KEY_GENERIC_TYPE key, final VALUE_GENERIC_TYPE oldValue, final VALUE_GENERIC_TYPE newValue) {
		final VALUE_GENERIC_TYPE curValue = GET_VALUE(key);
		if (!VALUE_EQUALS(curValue, oldValue) || (curValue == defaultReturnValue() && !containsKey(key))) return false;
		put(key, newValue);
		return true;
	}

	/** Replaces the entry for the specified key only if it is currently mapped to some value.
	 *
	 * @param key key with which the specified value is associated.
	 * @param value value to be associated with the specified key.
	 *
	 * @return the previous value associated with the specified key, or the {@linkplain #defaultReturnValue() default return value} if there was no mapping for the key.
	 *
	 * @see java.util.Map#replace(Object, Object)
	 * @since 8.0.0
	 */

	default VALUE_GENERIC_TYPE replace(final KEY_GENERIC_TYPE key, final VALUE_GENERIC_TYPE value) { return containsKey(key) ? put(key, value) : defaultReturnValue(); }

#ifdef JDK_PRIMITIVE_FUNCTION

	/** If the specified key is not already associated with a value, attempts to compute its value
	 * using the given mapping function and enters it into this map.
	 *
	 * <p>Note that contrarily to the default {@linkplain java.util.Map#computeIfAbsent(Object, java.util.function.Function) computeIfAbsent()},
	 * it is not possible to not add a value for a given key, since the {@code mappingFunction} cannot
	 * return {@code null}. If such a behavior is needed, please use the corresponding <em>nullable</em> version.
	 *
	 * @apiNote all {@code computeIfAbsent()} methods have a different logic based on the argument;
	 * no delegation is performed, contrarily to other superficially similar 
	 * methods such as {@link java.util.Iterator#forEachRemaining} or {@link java.util.List#replaceAll}.
	 *
	 * @param key key with which the specified value is to be associated.
	 * @param mappingFunction the function to compute a value.
	 *
	 * @return the current (existing or computed) value associated with the specified key.
	 *
	 * @see java.util.Map#computeIfAbsent(Object, java.util.function.Function)
	 * @since 8.0.0
	 */

	default VALUE_GENERIC_TYPE computeIfAbsent(final KEY_GENERIC_TYPE key, final JDK_PRIMITIVE_FUNCTION KEY_SUPER_GENERIC_VALUE_EXTENDS_GENERIC mappingFunction) {
		java.util.Objects.requireNonNull(mappingFunction);
		final VALUE_GENERIC_TYPE v = GET_VALUE(key);
		if (v != defaultReturnValue() || containsKey(key)) return v;

		VALUE_GENERIC_TYPE newValue = VALUE_NARROWING(mappingFunction.JDK_PRIMITIVE_FUNCTION_APPLY(key));
		put(key, newValue);
		return newValue;
	}

#if KEYS_REFERENCE
	/**
	 * @deprecated Please use {@code computeIfAbsent()} instead.
	 */
	@Deprecated
	default VALUE_GENERIC_TYPE COMPUTE_IF_ABSENT_JDK(final KEY_GENERIC_TYPE key, final JDK_PRIMITIVE_FUNCTION KEY_SUPER_GENERIC_VALUE_EXTENDS_GENERIC mappingFunction) {
		return computeIfAbsent(key, mappingFunction);
	}
#endif

#endif

#if KEYS_PRIMITIVE && VALUES_PRIMITIVE

	/** If the specified key is not already associated with a value, attempts to compute its value
	 * using the given mapping function and enters it into this map unless it is {@code null}.
	 *
	 * <p>Note that this version of {@linkplain java.util.Map#computeIfAbsent(Object, java.util.function.Function) computeIfAbsent()}
	 * should be used only if you plan to return {@code null} in the mapping function.
	 *
	 * @param key key with which the specified value is to be associated.
	 * @param mappingFunction the function to compute a value.
	 *
	 * @return the current (existing or computed) value associated with the specified key,
	 * or the {@linkplain #defaultReturnValue() default return value} if the computed value is {@code null}.
	 *
	 * @see java.util.Map#computeIfAbsent(Object, java.util.function.Function)
	 * @since 8.0.0
	 */

	default VALUE_GENERIC_TYPE COMPUTE_IF_ABSENT_NULLABLE(final KEY_GENERIC_TYPE key, final JDK_KEY_TO_GENERIC_FUNCTION<? extends VALUE_GENERIC_CLASS> mappingFunction) {
		java.util.Objects.requireNonNull(mappingFunction);
		final VALUE_GENERIC_TYPE v = GET_VALUE(key), drv = defaultReturnValue();
		if (v != drv || containsKey(key)) return v;

		VALUE_GENERIC_CLASS mappedValue = mappingFunction.apply(key);
		if (mappedValue == null) return drv;
		VALUE_GENERIC_TYPE newValue = VALUE_CLASS2TYPE(mappedValue);
		put(key, newValue);
		return newValue;
	}

#endif

	/** If the specified key is not already associated with a value, attempts to compute its value
	 * using the given mapping function and enters it into this map, unless the key is not present
	 * in the given mapping function.
	 *
	 * <p>This version of {@linkplain java.util.Map#computeIfAbsent(Object, java.util.function.Function) computeIfAbsent()}
	 * uses a type-specific version of {@code fastutil}'s {@link it.unimi.dsi.fastutil.Function Function}.
	 * Since {@link it.unimi.dsi.fastutil.Function Function} has a {@link it.unimi.dsi.fastutil.Function#containsKey(Object) containsKey()}
	 * method, it is possible to avoid adding a key by having {@code containsKey()} return {@code false} for that key.
	 *
	 * @apiNote all {@code computeIfAbsent()} methods have a different logic based on the argument;
	 * no delegation is performed, contrarily to other superficially similar 
	 * methods such as {@link java.util.Iterator#forEachRemaining} or {@link java.util.List#replaceAll}.
	 *
	 * @param key key with which the specified value is to be associated.
	 * @param mappingFunction the function to compute a value.
	 *
	 * @return the current (existing or computed) value associated with the specified key.
	 *
	 * @see java.util.Map#computeIfAbsent(Object, java.util.function.Function)
	 * @since 8.0.0
	 */

	default VALUE_GENERIC_TYPE computeIfAbsent(final KEY_GENERIC_TYPE key, final FUNCTION KEY_SUPER_GENERIC_VALUE_EXTENDS_GENERIC mappingFunction) {
		java.util.Objects.requireNonNull(mappingFunction);
		final VALUE_GENERIC_TYPE v = GET_VALUE(key), drv = defaultReturnValue();
		if (v != drv || containsKey(key)) return v;

		if (!mappingFunction.containsKey(key)) return drv;
		VALUE_GENERIC_TYPE newValue = mappingFunction.GET_VALUE(key);
		put(key, newValue);
		return newValue;
	}

	/**
	 * @deprecated Please use {@code computeIfAbsent()} instead.
	 */
	@Deprecated
	default VALUE_GENERIC_TYPE COMPUTE_IF_ABSENT_PARTIAL(final KEY_GENERIC_TYPE key, final FUNCTION KEY_SUPER_GENERIC_VALUE_EXTENDS_GENERIC mappingFunction) {
		return computeIfAbsent(key, mappingFunction);
	}


	/** If the value for the specified key is present, attempts to compute a new mapping given the key and its current mapped value.
	 *
	 * @apiNote The JDK specification for this method equates not being associated with a value with being associated with {code null}.
	 * This is not the case for this method.
	 *
	 * @param key key with which the specified value is to be associated.
	 * @param remappingFunction the function to compute a value.
	 *
	 * @return the new value associated with the specified key, or the {@linkplain #defaultReturnValue() default return value} if none.
	 *
	 * @see java.util.Map#computeIfPresent(Object, java.util.function.BiFunction)
	 * @since 8.0.0
	 */

	default VALUE_GENERIC_TYPE COMPUTE_IF_PRESENT(final KEY_GENERIC_TYPE key, final java.util.function.BiFunction<? super KEY_GENERIC_CLASS, ? super VALUE_GENERIC_CLASS, ? extends VALUE_GENERIC_CLASS> remappingFunction) {
		java.util.Objects.requireNonNull(remappingFunction);

		final VALUE_GENERIC_TYPE oldValue = GET_VALUE(key), drv = defaultReturnValue();
		if (oldValue == drv && !containsKey(key)) return drv;
		final VALUE_GENERIC_CLASS newValue = remappingFunction.apply(KEY2OBJ(key), VALUE2OBJ(oldValue));

		if (newValue == null) { REMOVE_VALUE(key); return drv; }

#if VALUES_PRIMITIVE
		VALUE_GENERIC_TYPE newVal = VALUE_CLASS2TYPE(newValue);
		put(key, newVal);
		return newVal;
#else
		put(key, newValue);
		return newValue;
#endif
	}

	/** Attempts to compute a mapping for the specified key and its current mapped value (or {@code null} if there is no current mapping).
	 *
	 * <p>If the function returns {@code null}, the mapping is removed (or remains absent if initially absent).
	 * If the function itself throws an (unchecked) exception, the exception is rethrown, and the current mapping is left unchanged.
	 *
	 * @param key key with which the specified value is to be associated.
	 * @param remappingFunction the function to compute a value.
	 *
	 * @return the new value associated with the specified key, or the {@linkplain #defaultReturnValue() default return value} if none.
	 *
	 * @see java.util.Map#compute(Object, java.util.function.BiFunction)
	 * @since 8.0.0
	 */

	default VALUE_GENERIC_TYPE COMPUTE(final KEY_GENERIC_TYPE key, final java.util.function.BiFunction<? super KEY_GENERIC_CLASS, ? super VALUE_GENERIC_CLASS, ? extends VALUE_GENERIC_CLASS> remappingFunction) {
		java.util.Objects.requireNonNull(remappingFunction);
		final VALUE_GENERIC_TYPE oldValue = GET_VALUE(key), drv = defaultReturnValue();
		final boolean contained = oldValue != drv || containsKey(key);
		final VALUE_GENERIC_CLASS newValue = remappingFunction.apply(KEY2OBJ(key), contained ? VALUE2OBJ(oldValue) : null);

		if (newValue == null) {
			if (contained) REMOVE_VALUE(key);
			return drv;
		}
#if VALUES_PRIMITIVE
		final VALUE_GENERIC_TYPE newVal = VALUE_CLASS2TYPE(newValue);
		put(key, newVal);
		return newVal;
#else
		put(key, newValue);
		return newValue;
#endif
	}

	/**
	 * If the specified key is not already associated with a value, associates it with the given {@code value}.
	 * Otherwise, replaces the associated value with the results of the given remapping function, or removes if the result is {@code null}.
	 *
	 * @apiNote The JDK specification for this method equates not being associated with a value with being associated with {code null}.
	 * This is not the case for this method.
	 *
	 * @param key key with which the resulting value is to be associated.
	 * @param value the value to be merged with the existing value associated with the key or, if no existing value is associated with the key, to be associated with the key.
	 * @param remappingFunction the function to recompute a value if present.
	 *
	 * @return the new value associated with the specified key, or the {@linkplain #defaultReturnValue() default return value} if no value is associated with the key.
	 *
	 * @see java.util.Map#merge(Object, Object, java.util.function.BiFunction)
	 * @since 8.0.0
	 */
	default VALUE_GENERIC_TYPE merge(final KEY_GENERIC_TYPE key, final VALUE_GENERIC_TYPE value, final java.util.function.BiFunction<? super VALUE_GENERIC_CLASS, ? super VALUE_GENERIC_CLASS, ? extends VALUE_GENERIC_CLASS> remappingFunction) {
		java.util.Objects.requireNonNull(remappingFunction);
		REQUIRE_VALUE_NON_NULL(value)

		final VALUE_GENERIC_TYPE oldValue = GET_VALUE(key), drv = defaultReturnValue();
		final VALUE_GENERIC_TYPE newValue;
		if (oldValue != drv || containsKey(key)) {
			final VALUE_GENERIC_CLASS mergedValue = remappingFunction.apply(VALUE2OBJ(oldValue), VALUE2OBJ(value));
			if (mergedValue == null) { REMOVE_VALUE(key); return drv; }
			newValue = VALUE_CLASS2TYPE(mergedValue);
		} else {
			newValue = value;
		}

		put(key, newValue);
		return newValue;
	}

#if VALUES_PRIMITIVE && ! VALUE_CLASS_Boolean

	/**
	 * If the specified key is not already associated with a value, associates it with the given {@code value}.
	 * Otherwise, replaces the associated value with the results of the given remapping function.
	 *
	 * @apiNote The JDK specification for this method equates not being associated with a value with being associated with {code null}.
	 * This is not the case for this method. Moreover, this method cannot delete entries as the type-specific remapping
	 * function cannot return {@code null}.
	 *
	 * @param key key with which the resulting value is to be associated.
	 * @param value the value to be merged with the existing value associated with the key or, if no existing value is associated with the key, to be associated with the key.
	 * @param remappingFunction the function to recompute a value if present.
	 *
	 * @return the new value associated with the specified key.
	 *
	 * @see java.util.Map#merge(Object, Object, java.util.function.BiFunction)
	 * @since 8.5.0
	 */
	default VALUE_TYPE MERGE_VALUE(final KEY_GENERIC_TYPE key, final VALUE_TYPE value, final METHOD_ARG_VALUE_BINARY_OPERATOR remappingFunction) {
		java.util.Objects.requireNonNull(remappingFunction);
		final VALUE_TYPE oldValue = GET_VALUE(key), drv = defaultReturnValue();
		final VALUE_TYPE newValue = oldValue != drv || containsKey(key) ? remappingFunction.VALUE_OPERATOR_APPLY(oldValue, value) : value;
		put(key, newValue);
		return newValue;
	}

#if VALUES_INT_LONG_DOUBLE
	// Because our primitive BinaryOperator interface extends both the JDK's primitive
	// and object BinaryOperator interfaces, calling this method with it would be ambiguous.
	// This overload exists to pass it to the proper primitive overload.
	/**
	 * If the specified key is not already associated with a value, associates it with the given {@code value}.
	 * Otherwise, replaces the associated value with the results of the given remapping function.
	 *
	 * @apiNote The JDK specification for this method equates not being associated with a value with being associated with {code null}.
	 * This is not the case for this method. Moreover, this method cannot delete entries as the type-specific remapping
	 * function cannot return {@code null}.
	 *
	 * <p><b>WARNING</b>: Overriding this method is almost always a mistake, as this
	 * overload only exists to disambiguate. Instead, override the overload
	 * that uses the JDK's primitive binary operator (e.g. {@link java.util.function.IntBinaryOperator}).
	 *
	 * <p>If Java supported final default methods, this would be one, but sadly it does not.
	 *
	 * <p>If you checked and are overriding the version with {@code java.util.function.XBinaryOperator}, and
	 * still see this warning, then your IDE is incorrectly conflating this method with the proper
	 * method to override, and you can safely ignore this message.
	 *
	 * @param key key with which the resulting value is to be associated.
	 * @param value the value to be merged with the existing value associated with the key or, if no existing value is associated with the key, to be associated with the key.
	 * @param remappingFunction the function to recompute a value if present.
	 *
	 * @see java.util.Map#merge(Object, Object, java.util.function.BiFunction)
	 * @since 8.5.1
	 */

	default VALUE_TYPE MERGE_VALUE(final KEY_GENERIC_TYPE key, final VALUE_TYPE value, final VALUE_PACKAGE.VALUE_BINARY_OPERATOR remappingFunction) {
		return MERGE_VALUE(key, value, (JDK_PRIMITIVE_VALUE_BINARY_OPERATOR)remappingFunction);
	}
#else
	/**
	 * If the specified key is not already associated with a value, associates it with the given {@code value}.
	 * Otherwise, replaces the associated value with the results of the given remapping function.
	 *
	 * @apiNote The JDK specification for this method equates not being associated with a value with being associated with {code null}.
	 * This is not the case for this method. Moreover, this method cannot delete entries as the type-specific remapping
	 * function cannot return {@code null}.
	 *
	 * @param key key with which the resulting value is to be associated.
	 * @param value the value to be merged with the existing value associated with the key or, if no existing value is associated with the key, to be associated with the key.
	 * @param remappingFunction the function to recompute a value if present.
	 *
	 * @return the new value associated with the specified key.
	 *
	 * @see java.util.Map#merge(Object, Object, java.util.function.BiFunction)
	 * @since 8.5.0
	 * @implNote Unless the argument is type-specific, this method will introduce an intermediary
	 *   lambda to perform narrowing and widening casts. Please use the type-specific overload to avoid this overhead.
	 */

	default VALUE_TYPE MERGE_VALUE(final KEY_GENERIC_TYPE key, final VALUE_TYPE value, final JDK_PRIMITIVE_VALUE_BINARY_OPERATOR remappingFunction) {
		return MERGE_VALUE(key, value, remappingFunction instanceof METHOD_ARG_VALUE_BINARY_OPERATOR ? (METHOD_ARG_VALUE_BINARY_OPERATOR)remappingFunction : (x, y) -> VALUE_NARROWING(remappingFunction.JDK_PRIMITIVE_VALUE_OPERATOR_APPLY(x, y)));
	}

#endif

#if KEYS_REFERENCE

	/**
	 * @deprecated Please use {@code merge()} instead.
	 */
	@Deprecated
	default VALUE_GENERIC_TYPE MERGE(final KEY_GENERIC_TYPE key, final VALUE_GENERIC_TYPE value, final java.util.function.BiFunction<? super VALUE_GENERIC_CLASS, ? super VALUE_GENERIC_CLASS, ? extends VALUE_GENERIC_CLASS> remappingFunction) {
		return merge(key, value, remappingFunction);
	}

#endif

  /** {@inheritDoc}
	 * <p>This default implementation just delegates to the corresponding {@link Map} method.
	 * @deprecated Please use the corresponding type-specific method instead. */
	@Deprecated
	@Override
	default VALUE_GENERIC_CLASS putIfAbsent(final KEY_GENERIC_CLASS key, final VALUE_GENERIC_CLASS value) {
		return Map.super.putIfAbsent(key, value);
	}

  /** {@inheritDoc}
	 * <p>This default implementation just delegates to the corresponding {@link Map} method.
	 * @deprecated Please use the corresponding type-specific method instead. */
	@Deprecated
	@Override
	default boolean remove(final Object key, final Object value) {
		return Map.super.remove(key, value);
	}

  /** {@inheritDoc}
	 * <p>This default implementation just delegates to the corresponding {@link Map} method.
	 * @deprecated Please use the corresponding type-specific method instead. */
	@Deprecated
	@Override
	default boolean replace(final KEY_GENERIC_CLASS key, final VALUE_GENERIC_CLASS oldValue, final VALUE_GENERIC_CLASS newValue) {
		return Map.super.replace(key, oldValue, newValue);
	}

  /** {@inheritDoc}
	 * <p>This default implementation just delegates to the corresponding {@link Map} method.
	 * @deprecated Please use the corresponding type-specific method instead. */
	@Deprecated
	@Override
	default VALUE_GENERIC_CLASS replace(final KEY_GENERIC_CLASS key, final VALUE_GENERIC_CLASS value) {
		return Map.super.replace(key, value);
	}

#if KEYS_PRIMITIVE

	/** {@inheritDoc}
	 * <p>This default implementation just delegates to the corresponding {@link Map} method.
	 * @deprecated Please use the corresponding type-specific method instead. */
	@Deprecated
	@Override
	default VALUE_GENERIC_CLASS computeIfAbsent(final KEY_GENERIC_CLASS key, final java.util.function.Function<? super KEY_GENERIC_CLASS, ? extends VALUE_GENERIC_CLASS> mappingFunction) {
		return Map.super.computeIfAbsent(key, mappingFunction);
	}

	/** {@inheritDoc}
	 * <p>This default implementation just delegates to the corresponding {@link Map} method.
	 * @deprecated Please use the corresponding type-specific method instead. */
	@Deprecated
	@Override
	default VALUE_GENERIC_CLASS computeIfPresent(final KEY_GENERIC_CLASS key, final java.util.function.BiFunction<? super KEY_GENERIC_CLASS, ? super VALUE_GENERIC_CLASS, ? extends VALUE_GENERIC_CLASS> remappingFunction) {
		return Map.super.computeIfPresent(key, remappingFunction);
	}

	/** {@inheritDoc}
	 * <p>This default implementation just delegates to the corresponding {@link Map} method.
	 * @deprecated Please use the corresponding type-specific method instead. */
	@Deprecated
	@Override
	default VALUE_GENERIC_CLASS compute(final KEY_GENERIC_CLASS key, final java.util.function.BiFunction<? super KEY_GENERIC_CLASS, ? super VALUE_GENERIC_CLASS, ? extends VALUE_GENERIC_CLASS> remappingFunction) {
		return Map.super.compute(key, remappingFunction);
	}

#endif

	/** {@inheritDoc}
	 * <p>This default implementation just delegates to the corresponding {@link Map} method.
	 * @deprecated Please use the corresponding type-specific method instead. */
	@Deprecated
	@Override
	default VALUE_GENERIC_CLASS merge(final KEY_GENERIC_CLASS key, final VALUE_GENERIC_CLASS value, final java.util.function.BiFunction<? super VALUE_GENERIC_CLASS, ? super VALUE_GENERIC_CLASS, ? extends VALUE_GENERIC_CLASS> remappingFunction) {
		return Map.super.merge(key, value, remappingFunction);
	}

#endif

	/** A type-specific {@link java.util.Map.Entry}; provides some additional methods
	 *  that use polymorphism to avoid (un)boxing.
	 *
	 * @see java.util.Map.Entry
	 */

	interface Entry KEY_VALUE_GENERIC extends Map.Entry <KEY_GENERIC_CLASS,VALUE_GENERIC_CLASS> {

#if KEYS_PRIMITIVE
		/** Returns the key corresponding to this entry.
		 * @see java.util.Map.Entry#getKey()
		 */
		KEY_TYPE ENTRY_GET_KEY();

		/** {@inheritDoc}
		 * @deprecated Please use the corresponding type-specific method instead. */
		@Deprecated
		@Override
		default KEY_GENERIC_CLASS getKey() {
			return KEY2OBJ(ENTRY_GET_KEY());
		}
#endif

#if VALUES_PRIMITIVE
		/** Returns the value corresponding to this entry.
		 * @see java.util.Map.Entry#getValue()
		 */
		VALUE_TYPE ENTRY_GET_VALUE();

		/** Replaces the value corresponding to this entry with the specified value (optional operation).
		 * @see java.util.Map.Entry#setValue(Object)
		 */
		VALUE_TYPE setValue(final VALUE_TYPE value);

		/** {@inheritDoc}
		 * @deprecated Please use the corresponding type-specific method instead. */
		@Deprecated
		@Override
		default VALUE_GENERIC_CLASS getValue() {
			return VALUE2OBJ(ENTRY_GET_VALUE());
		}

		/** {@inheritDoc}
		 * @deprecated Please use the corresponding type-specific method instead. */
		@Deprecated
		@Override
		default VALUE_GENERIC_CLASS setValue(final VALUE_GENERIC_CLASS value) {
			return VALUE2OBJ(setValue(VALUE_CLASS2TYPE(value)));
		}
#endif
	}
}