/*
	* Copyright (C) 2002-2019 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 it.unimi.dsi.fastutil.objects;
import it.unimi.dsi.fastutil.Function;
A type-specific Function; provides some additional methods that use polymorphism to avoid (un)boxing. 
 Type-specific versions of get(), put() and remove() cannot rely on null to denote absence of a key. Rather, they return a default return value, which is set to 0/false at creation, but can be changed using the defaultReturnValue() method. 
 For uniformity reasons, even functions returning objects implement the default return value (of course, in this case the default return value is initialized to null). 
 The default implementation of optional operations just throw an UnsupportedOperationException, except for the type-specific 
containsKey(), which return true. Generic versions of accessors delegate to the corresponding type-specific counterparts following the interface rules. 

Warning: to fall in line as much as possible with the standard map interface, it is required that standard versions of get(), put() and remove() for maps with primitive-type keys or values return null to denote missing keys  rather than wrap the default return value in an object. In case both keys and values are reference types, the default return value must be returned instead, thus violating the standard
map interface when the default return value is not null. 
See Also:
Function/**
 * A type-specific {@link Function}; provides some additional methods that use
 * polymorphism to avoid (un)boxing.
 *
 * <p>
 * Type-specific versions of {@code get()}, {@code put()} and {@code remove()}
 * cannot rely on {@code null} to denote absence of a key. Rather, they return a
 * {@linkplain #defaultReturnValue() default return value}, which is set to
 * 0/false at creation, but can be changed using the
 * {@code defaultReturnValue()} method.
 *
 * <p>
 * For uniformity reasons, even functions returning objects implement the
 * default return value (of course, in this case the default return value is
 * initialized to {@code null}).
 *
 * <p>
 * The default implementation of optional operations just throw an
 * {@link UnsupportedOperationException}, except for the type-specific {@code
* containsKey()}, which return true. Generic versions of accessors delegate to
 * the corresponding type-specific counterparts following the interface rules.
 *
 * <p>
 * <strong>Warning:</strong> to fall in line as much as possible with the
 * {@linkplain java.util.Map standard map interface}, it is required that
 * standard versions of {@code get()}, {@code put()} and {@code remove()} for
 * maps with primitive-type keys or values <em>return {@code null} to denote
 * missing keys </em> rather than wrap the default return value in an object. In
 * case both keys and values are reference types, the default return value must
 * be returned instead, thus violating the {@linkplain java.util.Map standard
 * map interface} when the default return value is not {@code null}.
 *
 * @see Function
 */
@FunctionalInterface
public interface Object2ObjectFunction<K, V> extends Function<K, V> {
	
Adds a pair to the map (optional operation).
Params:
key – 
           the key.
value – 
           the value.
See Also:
Function.put(Object, Object)
Returns:
the old value, or the default
        return value if no value was present for the given key./**
	 * Adds a pair to the map (optional operation).
	 *
	 * @param key
	 *            the key.
	 * @param value
	 *            the value.
	 * @return the old value, or the {@linkplain #defaultReturnValue() default
	 *         return value} if no value was present for the given key.
	 * @see Function#put(Object,Object)
	 */
	default V put(final K key, final V value) {
		throw new UnsupportedOperationException();
	}
	
Returns the value to which the given key is mapped.
Params:
key – 
           the key.
See Also:
Function.get(Object)
Returns:
the corresponding value, or the 
        default return value if no value was present for the given key./**
	 * Returns the value to which the given key is mapped.
	 *
	 * @param key
	 *            the key.
	 * @return the corresponding value, or the {@linkplain #defaultReturnValue()
	 *         default return value} if no value was present for the given key.
	 * @see Function#get(Object)
	 */
	V get(Object key);
	
Removes the mapping with the given key (optional operation).
Params:
key – 
           the key.
See Also:
Function.remove(Object)
Returns:
the old value, or the default
        return value if no value was present for the given key./**
	 * Removes the mapping with the given key (optional operation).
	 * 
	 * @param key
	 *            the key.
	 * @return the old value, or the {@linkplain #defaultReturnValue() default
	 *         return value} if no value was present for the given key.
	 * @see Function#remove(Object)
	 */
	default V remove(final Object key) {
		throw new UnsupportedOperationException();
	}
	
Sets the default return value (optional operation). This value must be returned by type-specific versions of get(), put() and remove() to denote that the map does not contain the specified key. It must be 0/false/null by default. 
Params:
rv – 
           the new default return value.
See Also:
defaultReturnValue()/**
	 * 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}/{@code null} by default.
	 *
	 * @param rv
	 *            the new default return value.
	 * @see #defaultReturnValue()
	 */
	default void defaultReturnValue(V rv) {
		throw new UnsupportedOperationException();
	}
	
Gets the default return value.
 This default implementation just return the default null value of the type (null for objects, 0 for scalars, false for Booleans). 
Returns:
the current default return value./**
	 * Gets the default return value.
	 *
	 * <p>
	 * This default implementation just return the default null value of the type
	 * ({@code null} for objects, 0 for scalars, false for Booleans).
	 *
	 * @return the current default return value.
	 */
	default V defaultReturnValue() {
		return (null);
	}
}