net.openhft.koloboke.collect.map.ByteObjMap Maven / Gradle / Ivy
Show all versions of koloboke-api-jdk8 Show documentation
/*
* Copyright 2014 the original author or authors.
*
* 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 net.openhft.koloboke.collect.map;
import net.openhft.koloboke.collect.Container;
import net.openhft.koloboke.collect.Equivalence;
import java.util.function.BiConsumer;
import java.util.function.BiFunction;
import net.openhft.koloboke.function.ByteObjConsumer;
import net.openhft.koloboke.function.ByteObjPredicate;
import net.openhft.koloboke.function.ByteObjFunction;
import net.openhft.koloboke.function.ByteFunction;
import java.util.function.Function;
import java.util.function.BiFunction;
import net.openhft.koloboke.collect.ObjCollection;
import net.openhft.koloboke.collect.set.ByteSet;
import net.openhft.koloboke.collect.set.ObjSet;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import java.util.Map;
/**
*
* A {@link Map} specialization with {@code byte} keys and {@code Object} values.
*
*
* @see ByteObjMapFactory
*/
public interface ByteObjMap extends Map, Container {
/**
* Returns the equivalence strategy for values in this map. All methods in the {@link Map}
* interface which defined in terms of {@link Object#equals(Object)} equality of value objects,
* for example, {@link #containsValue(Object)} and {@link #remove(byte, Object)},
* are supposed to use this equivalence instead.
*
* @return the equivalence strategy for values in this map
* @see ByteObjMapFactory#withValueEquivalence
*/
@Nonnull
Equivalence valueEquivalence();
/**
* {@inheritDoc}
* @deprecated Use specialization {@link #containsKey(byte)} instead
*/
@Override
@Deprecated
boolean containsKey(Object key);
/**
* Returns {@code true} if this map contains a mapping for the specified key.
*
* @param key the {@code byte} key whose presence in this map is to be tested
* @return {@code true} if this map contains a mapping for the specified key
*/
boolean containsKey(byte key);
/**
* {@inheritDoc}
* @deprecated Use specialization {@link #get(byte)} instead
*/
@Nullable
@Override
@Deprecated
V get(Object key);
/**
* Returns the value to which the specified key is mapped, or {@code null} if this map
* contains no mapping for the key.
*
*
*
*
* If this map permits null values, then a return value of {@code null} does not
* necessarily indicate that the map contains no mapping for the key; it's also possible
* that the map explicitly maps the key to {@code null}. The {@link #containsKey}
* operation may be used to distinguish these two cases.
*
* @param key the key whose associated value is to be returned
* @return the value to which the specified key is mapped, or {@code null} if this map
* contains no mapping for the key
*/
@Nullable
V get(byte key);
/**
* {@inheritDoc}
* @deprecated Use specialization {@link #getOrDefault(byte, Object)} instead
*/
@Override
@Deprecated
V getOrDefault(Object key, V defaultValue);
/**
* Returns the value to which the specified key is mapped, or {@code defaultValue} if this map
* contains no mapping for the key.
*
* @param key the key whose associated value is to be returned
* @param defaultValue the value to return if the specified {@code key} is absent in the map
* @return the value to which the specified key is mapped, or
* {@code defaultValue} if this map contains no mapping for the key
*/
V getOrDefault(byte key, V defaultValue);
/**
* {@inheritDoc}
* @deprecated Use specialization {@link #forEach(ByteObjConsumer)} instead
*/
@Override
@Deprecated
void forEach(@Nonnull BiConsumer action);
/**
* Performs the given {@code action} on each entry in this map until all entries
* have been processed or the action throws an {@code Exception}.
* Exceptions thrown by the action are relayed to the caller. The entries
* will be processed in the same order as the entry set iterator unless that
* order is unspecified in which case implementations may use an order which
* differs from the entry set iterator.
*
* @param action The action to be performed for each entry
* @see
* Comparison of iteration options in the library
*/
void forEach(@Nonnull ByteObjConsumer action);
/**
* Checks the given {@code predicate} on each entry in this map until all entries
* have been processed or the predicate returns {@code false} for some entry,
* or throws an {@code Exception}. Exceptions thrown by the predicate are relayed to the caller.
*
*
The entries will be processed in the same order as the entry set iterator unless that
* order is unspecified in which case implementations may use an order which differs from
* the entry set iterator.
*
*
If the map is empty, this method returns {@code true} immediately.
*
* @return {@code true} if the predicate returned {@code true} for all entries of the map,
* {@code false} if it returned {@code false} for the entry
* @param predicate the predicate to be checked for each entry
* @see
* Comparison of iteration options in the library
*/
boolean forEachWhile(@Nonnull ByteObjPredicate predicate);
/**
* Returns a new cursor over the entries of this map. It's order is always correspond to the
* entry set iterator order.
*
* @return a new cursor over the entries of this map
* @see
* Comparison of iteration options in the library
*/
@Nonnull
ByteObjCursor cursor();
@Override
@Nonnull
ByteSet keySet();
@Override
@Nonnull
ObjCollection values();
@Override
@Nonnull
ObjSet> entrySet();
/**
* {@inheritDoc}
* @deprecated Use specialization {@link #put(byte, Object)} instead
*/
@Override
@Deprecated
V put(Byte key, V value);
/**
* Associates the specified value with the specified key in this map (optional operation).
* If the map previously contained a mapping for the key, the old value is replaced
* by the specified value. (A map {@code m} is said to contain a mapping for a key {@code k}
* if and only if {@link #containsKey(byte) m.containsKey(k)} would return {@code true}.)
*
* @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 {@code key}, or {@code null} if there was
* no mapping for {@code key}. (A {@code null} return can also indicate that the map
* previously associated {@code null} with {@code key}.)
* @throws UnsupportedOperationException if the {@code put} operation
* is not supported by this map
* @throws ClassCastException if the class of the specified value
* prevents it from being stored in this map
* @throws NullPointerException if the specified value is null,
* and this map does not permit null values * @throws IllegalArgumentException if some property of a specified key
* or value prevents it from being stored in this map
*/
V put(byte key, V value);
/**
* If the specified key is not already associated with a value (or is mapped to {@code null}), associates
* it with the given value and returns {@code null}, 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
* {@code null} if there was no mapping for the key.
* (A {@code null} return can also indicate that the map
* previously associated {@code null} with the key,
* if the implementation supports null values.)
* @throws UnsupportedOperationException if the {@code put} operation
* is not supported by this map
* @throws ClassCastException if the key or value is of an inappropriate type for this map
* @throws NullPointerException if the specified key is null
* @throws IllegalArgumentException if some property of the specified key
* or value prevents it from being stored in this map
* @deprecated Use specialization {@link #putIfAbsent(byte, Object)} instead
*/
@Override
@Nullable
@Deprecated
V putIfAbsent(Byte key, V value);
/**
* If the specified key is not already associated with a value (or is mapped to {@code null}), associates
* it with the given value and returns {@code null}, 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 {@code null}
* if there was no mapping for the key. (A {@code null} return
* can also indicate that the map previously associated {@code null}
* with the key, if the implementation supports such values.)
* @throws UnsupportedOperationException if the {@code put} operation
* is not supported by this map
* @throws ClassCastException if the class of the specified value
* prevents it from being stored in this map
* @throws NullPointerException if the specified value is null,
* and this map does not permit null values * @throws IllegalArgumentException if some property of a specified key
* or value prevents it from being stored in this map
*/
@Nullable
V putIfAbsent(byte key, V value);
/**
* {@inheritDoc}
* @deprecated Use specialization
* {@link #compute(byte, ByteObjFunction)} instead
*/
@Override
@Deprecated
V compute(Byte key,
@Nonnull BiFunction remappingFunction
);
/**
* Attempts to compute a mapping for the specified key and its current mapped value
* (or {@code null} if there is no current mapping).
*
* 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
* @throws ClassCastException if the class of the
* computed value
* prevents it from being stored in this map (optional restriction)
* @throws UnsupportedOperationException if the {@code put} operation
* is not supported by this map
*/
V compute(byte key, @Nonnull ByteObjFunction remappingFunction);
/**
* {@inheritDoc}
* @deprecated Use specialization
* {@link #computeIfAbsent(byte, ByteFunction)} instead
*/
@Override
@Deprecated
V computeIfAbsent(Byte key,
@Nonnull Function mappingFunction);
/**
* If the specified key is not already associated with a value (or is mapped to {@code null}), attempts
* to compute its value using the given mapping function and enters it into this map
* unless {@code null}. The most common usage is to construct
* a new object serving as an initial mapped value or memoized result.
*
*
If the function returns {@code null} no mapping is recorded.
*
*
If the function itself throws an (unchecked) exception, the exception is rethrown,
* and no mapping is recorded.
*
* @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
* @throws ClassCastException if the class of the
* computed value
* prevents it from being stored in this map (optional restriction)
* @throws UnsupportedOperationException if the {@code put} operation
* is not supported by this map
*/
V computeIfAbsent(byte key, @Nonnull ByteFunction mappingFunction);
/**
* {@inheritDoc}
* @deprecated Use specialization
* {@link #computeIfPresent(byte, ByteObjFunction)} instead
*/
@Override
@Deprecated
V computeIfPresent(Byte key,
@Nonnull BiFunction remappingFunction
);
/**
* If the value for the specified key is present and non-null,
* attempts to compute a new mapping given the key and its current mapped value.
*
*
If the function returns {@code null}, the mapping is removed.
*
*
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 "no entry" value
* @throws ClassCastException if the class of the
* computed value
* prevents it from being stored in this map (optional restriction)
* @throws UnsupportedOperationException if the {@code put} operation
* is not supported by this map
*/
V computeIfPresent(byte key, @Nonnull ByteObjFunction remappingFunction);
/**
* {@inheritDoc}
* @deprecated Use specialization
* {@link #merge(byte, Object, BiFunction)} instead
*/
@Override
@Deprecated
V merge(Byte key, V value,
@Nonnull BiFunction remappingFunction);
/**
* If the specified key is not already associated with a value (or is mapped to {@code null}), associates
* it with the given value, otherwise, replaces the value with the results of the given
* remapping function.
*
* This method may be of use when combining multiple mapped values for a key.
*
*
If the function returns {@code null}, the mapping is removed.
*
*
If the remappingFunction 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 value the value to use if absent
* @param remappingFunction the function to recompute a value if present
* @return the new value associated with the specified key
* @throws NullPointerException if the {@code remappingFunction} is null
* @throws ClassCastException if the class of the
* computed value
* prevents it from being stored in this map (optional restriction)
* @throws UnsupportedOperationException if the {@code put} operation
* is not supported by this map
*/
V merge(byte key, V value, @Nonnull BiFunction remappingFunction);
/**
* 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 {@code null} if there was
* no mapping for the key. (A {@code null} return can also indicate
* that the map previously associated {@code null} with the key,
* if the implementation supports null values.)
* @throws UnsupportedOperationException if the {@code put} operation
* is not supported by this map
* @throws NullPointerException if the specified key is null
* @throws IllegalArgumentException if some property of the specified value
* prevents it from being stored in this map
* @deprecated Use specialization {@link #replace(byte, Object)} instead
*/
@Override
@Nullable
@Deprecated
V replace(Byte key, V value);
/**
* 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 {@code null} if there was no mapping for the key.
* (A {@code null} return can also indicate that the map
* previously associated {@code null} with the key,
* if the implementation supports such values.)
* @throws ClassCastException if the class of the specified value
* prevents it from being stored in this map
* @throws NullPointerException if the specified value is null,
* and this map does not permit null values * @throws IllegalArgumentException if some property of a specified key
* or value prevents it from being stored in this map
* @throws UnsupportedOperationException if the {@code put} operation
* is not supported by this map
*/
@Nullable
V replace(byte key, V value);
/**
* 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
* @throws UnsupportedOperationException if the {@code put} operation
* is not supported by this map
* @throws NullPointerException if the specified key is null
* @throws IllegalArgumentException if some property of the specified value
* prevents it from being stored in this map
* @deprecated Use specialization
* {@link #replace(byte, Object, Object)} instead
*/
@Override
@Deprecated
boolean replace(Byte key, V oldValue, V newValue);
/**
* 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
* @throws ClassCastException if the class of the specified value
* prevents it from being stored in this map
* @throws NullPointerException if the specified value is null,
* and this map does not permit null values * @throws IllegalArgumentException if some property of a specified key
* or value prevents it from being stored in this map
* @throws UnsupportedOperationException if the {@code put} operation
* is not supported by this map
*/
boolean replace(byte key, V oldValue, V newValue);
/**
* {@inheritDoc}
* @deprecated Use specialization {@link #replaceAll(ByteObjFunction)} instead
*/
@Override
@Deprecated
void replaceAll(
@Nonnull BiFunction function);
/**
* Replaces each entry's value with the result of invoking the given function on that entry,
* in the order entries are returned by an entry set iterator, until all entries have been
* processed or the function throws an exception.
*
* @param function the function to apply to each entry
* @throws UnsupportedOperationException if the {@code set} operation
* is not supported by this map's entry set iterator
* or the specified replacement value is null, and this map does not permit
* null values (optional restriction)
* @throws ClassCastException if the class of a replacement value
* prevents it from being stored in this map
* @throws IllegalArgumentException if some property of a replacement value
* prevents it from being stored in this map (optional restriction)
*/
void replaceAll(@Nonnull ByteObjFunction function);
/**
* {@inheritDoc}
* @deprecated Use specialization
* {@link #remove(byte)} instead
*/
@Override
@Nullable
@Deprecated
V remove(Object key);
/**
* Removes the mapping for a key from this map if it is present (optional operation).
*
*
*
Returns the value to which this map previously associated the key, or {@code null}
* if the map contained no mapping for the key.
*
*
A return value of {@code null} does not necessarily indicate that the map
* contained no mapping for the key; it's also possible that the map
* explicitly mapped the key to {@code null}.
*
*
The map will not contain a mapping for the specified key once the
* call returns.
*
* @param key key whose mapping is to be removed from the map
* @return the previous value associated with {@code key}, or {@code null} if there was
* no mapping for {@code key}
* @throws ClassCastException if the class of the specified value
* prevents it from being stored in this map (optional restriction)
* @throws NullPointerException if the specified value is null,
* and this map does not permit null values (optional restriction)
* @throws UnsupportedOperationException if the {@code remove} operation
* is not supported by this map
*/
@Nullable
V remove(byte key);
/**
* 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
* @throws NullPointerException if the specified key is null
, or if the specified value is null,
* and this map does not permit null values (optional restriction)
* @throws ClassCastException if the class of the specified value
* prevents it from being stored in this map (optional restriction)
* @throws UnsupportedOperationException if the {@code remove} operation
* is not supported by this map
* @deprecated Use specialization {@link #remove(byte, Object)} instead
*/
@Override
@Deprecated
boolean remove(Object key, Object value);
/**
* 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
* @throws ClassCastException if the class of the specified value
* prevents it from being stored in this map (optional restriction)
* @throws NullPointerException if the specified value is null,
* and this map does not permit null values (optional restriction)
* @throws UnsupportedOperationException if the {@code remove} operation
* is not supported by this map
*/
boolean remove(byte key, Object value);
/**
* Removes all of the entries of this collection that satisfy the given predicate.
* Errors or runtime exceptions thrown during iteration or by the predicate are relayed
* to the caller.
*
* @param filter a predicate which returns {@code true} for elements to be removed
* @return {@code true} if any elements were removed
* @throws NullPointerException if the specified filter is null
* @throws UnsupportedOperationException if elements cannot be removed from this collection.
* Implementations may throw this exception if a matching element cannot be removed
* or if, in general, removal is not supported.
* @see
* Comparison of iteration options in the library
*/
boolean removeIf(@Nonnull ByteObjPredicate filter);
}