http://fastutil.di.unimi.it/: fastutil extends the Java Collections Framework by providing type-specific maps, sets, lists and priority queues with a small memory footprint and fast access and insertion; provides also big (64-bit) arrays, sets and lists, and fast, practical I/O classes for binary and text files.
  • Sebastiano Vigna 
/*
	* 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.bytes;
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:
/**
 * 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 Byte2CharFunction extends Function<Byte, Character>, java.util.function.IntUnaryOperator {
	
{@inheritDoc}

 In this default implementation, the key gets narrowed down to the actual key type, throwing an exception if the given key can't be represented in the restricted domain. This is done for interoperability with the Java 8 function environment. Its use is discouraged, as unexpected errors can occur. Instead, the corresponding classes should be used (e.g., Int2IntFunction instead of Short2IntFunction). 
Throws:
Since:8.0.0
Deprecated:Please use primitive types which don't have to be widened as
            keys.
/**
	 * {@inheritDoc}
	 *
	 * <p>
	 * In this default implementation, the key gets narrowed down to the actual key
	 * type, throwing an exception if the given key can't be represented in the
	 * restricted domain. This is done for interoperability with the Java 8 function
	 * environment. Its use is discouraged, as unexpected errors can occur. Instead,
	 * the corresponding classes should be used (e.g.,
	 * {@link it.unimi.dsi.fastutil.ints.Int2IntFunction} instead of
	 * {@link it.unimi.dsi.fastutil.shorts.Short2IntFunction}).
	 *
	 * @throws IllegalArgumentException
	 *             If the given operand is not an element of the key domain.
	 * @since 8.0.0
	 * @deprecated Please use primitive types which don't have to be widened as
	 *             keys.
	 */
	@Deprecated
	@Override
	default int applyAsInt(int operand) {
		return get(it.unimi.dsi.fastutil.SafeMath.safeIntToByte(operand));
	}
	
Adds a pair to the map (optional operation).

Params:
  • key – 
           the key.
  • value – 
           the value.
See Also:
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 char put(final byte key, final char value) {
		throw new UnsupportedOperationException();
	}
	
Returns the value to which the given key is mapped.

Params:
  • key – 
           the key.
See Also:
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)
	 */
	char get(byte key);
	
Removes the mapping with the given key (optional operation).

Params:
  • key – 
           the key.
See Also:
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 char remove(final byte key) {
		throw new UnsupportedOperationException();
	}
	
{@inheritDoc}

Deprecated:Please use the corresponding type-specific method instead.
/**
	 * {@inheritDoc}
	 * 
	 * @deprecated Please use the corresponding type-specific method instead.
	 */
	@Deprecated
	@Override
	default Character put(final Byte key, final Character value) {
		final byte k = (key).byteValue();
		final boolean containsKey = containsKey(k);
		final char v = put(k, (value).charValue());
		return containsKey ? Character.valueOf(v) : null;
	}
	
{@inheritDoc}

Deprecated:Please use the corresponding type-specific method instead.
/**
	 * {@inheritDoc}
	 * 
	 * @deprecated Please use the corresponding type-specific method instead.
	 */
	@Deprecated
	@Override
	default Character get(final Object key) {
		if (key == null)
			return null;
		final byte k = ((Byte) (key)).byteValue();
		final char v = get(k);
		return (v != defaultReturnValue() || containsKey(k)) ? Character.valueOf(v) : null;
	}
	
{@inheritDoc}

Deprecated:Please use the corresponding type-specific method instead.
/**
	 * {@inheritDoc}
	 * 
	 * @deprecated Please use the corresponding type-specific method instead.
	 */
	@Deprecated
	@Override
	default Character remove(final Object key) {
		if (key == null)
			return null;
		final byte k = ((Byte) (key)).byteValue();
		return containsKey(k) ? Character.valueOf(remove(k)) : null;
	}
	
Returns true if this function contains a mapping for the specified key.


Note that for some kind of functions (e.g., hashes) this method will always
return true. In particular, this default implementation always returns true.

Params:
  • key – 
           the key.
See Also:
Returns:true if this function associates a value to key.
/**
	 * Returns true if this function contains a mapping for the specified key.
	 *
	 * <p>
	 * Note that for some kind of functions (e.g., hashes) this method will always
	 * return true. In particular, this default implementation always returns true.
	 *
	 * @param key
	 *            the key.
	 * @return true if this function associates a value to {@code key}.
	 * @see Function#containsKey(Object)
	 */
	default boolean containsKey(byte key) {
		return true;
	}
	
{@inheritDoc}

Deprecated:Please use the corresponding type-specific method instead.
/**
	 * {@inheritDoc}
	 * 
	 * @deprecated Please use the corresponding type-specific method instead.
	 */
	@Deprecated
	@Override
	default boolean containsKey(final Object key) {
		return key == null ? false : containsKey(((Byte) (key)).byteValue());
	}
	
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:
/**
	 * 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(char 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 char defaultReturnValue() {
		return ((char) 0);
	}
}