@FunctionalInterface
public interface Function<K,V>
extends java.util.function.Function<K,V>
Instances of this class represent functions: the main difference with Map
is that functions do not in principle allow enumeration of their domain or range. The need for
this interface lies in the existence of several highly optimized implementations of
functions (e.g., minimal perfect hashes) which do not actually store their domain or range explicitly.
In case the domain is known, containsKey(Object)
can be used to perform membership queries.
The choice of naming all methods exactly as in Map
makes it possible
for all type-specific maps to extend type-specific functions (e.g., Int2IntMap
extends Int2IntFunction
). However, size()
is allowed to return -1 to denote
that the number of keys is not available (e.g., in the case of a string hash function).
Note that there is an Object2ObjectFunction
that
can also set its default return value.
Function
This interface predates Java 8's Function
and it was conceived with
a different purpose. To ease interoperability, we extend Function
and
implement a default method for apply(Object)
that delegates to get(Object)
. However,
while the argument of a Function
with keys of type T
is of type
T
, the argument of get(Object)
is unparameterized (see the example below).
No attempt will be made at creating type-specific versions of Function
as
the JDK already provides several specializations, such as IntToLongFunction
.
Rather, type-specific versions of this class do implement the corresponding classes in java.util.function
:
for example, Int2LongFunction
extends IntToLongFunction
and Int2IntFunction
extends
IntUnaryOperator
. For functions that do not have a corresponding JDK function we extend the
closest possible function (widening input and output types): for example, Byte2CharFunction
extends
IntUnaryOperator
.
All optional operations have default methods throwing an UnsupportedOperationException
, except
for containsKey(Object)
, which returns true, and size()
, which return -1.
Thus, it is possible to define an instance of this class using a lambda expression that will specify
get(Object)
. Note that the type signature of get(Object)
might lead to slightly
counter-intuitive behaviour. For example, to define the identity function on Integer
objects
you need to write
it.unimi.dsi.fastutil.Function<Integer, Integer> f = (x) -> (Integer)x;as the argument to
get(Object)
is unparameterized.
Warning: Equality of functions is not specified by contract, and it will usually be by reference, as there is no way to enumerate the keys and establish whether two functions represent the same mathematical entity.
Map
,
Function
Modifier and Type | Method and Description |
---|---|
default V |
apply(K key)
This is equivalent to calling
get(Object) . |
default void |
clear()
Removes all associations from this function (optional operation).
|
default boolean |
containsKey(java.lang.Object key)
Returns true if this function contains a mapping for the specified key.
|
V |
get(java.lang.Object key)
Returns the value associated by this function to the specified key.
|
default V |
getOrDefault(java.lang.Object key,
V defaultValue)
Returns the value associated by this function to the specified key, or give the specified
value if not present.
|
default V |
put(K key,
V value)
Associates the specified value with the specified key in this function (optional operation).
|
default V |
remove(java.lang.Object key)
Removes this key and the associated value from this function if it is present (optional operation).
|
default int |
size()
Returns the intended number of keys in this function, or -1 if no such number exists.
|
default V apply(K key)
get(Object)
.apply
in interface java.util.function.Function<K,V>
key
- Function.apply(Object)
,
get(Object)
default V put(K key, V value)
key
- the key.value
- the value.null
if no value was present for the given key.Map.put(Object,Object)
V get(java.lang.Object key)
key
- the key.null
if no value was present for the given key.Map.get(Object)
default V getOrDefault(java.lang.Object key, V defaultValue)
key
- the key.defaultValue
- the default value to return if not present.defaultValue
if no value was present for the
given key.Map.getOrDefault(Object, Object)
default boolean containsKey(java.lang.Object key)
Note that for some kind of functions (e.g., hashes) this method will always return true. This default implementation, in particular, always return true.
key
- the key.key
.Map.containsKey(Object)
default V remove(java.lang.Object key)
key
- the key.null
if no value was present for the given key.Map.remove(Object)
default int size()
Most function implementations will have some knowledge of the intended number of keys in their domain. In some cases, however, this might not be possible. This default implementation, in particular, returns -1.
default void clear()
Map.clear()