net.openhft.koloboke.collect.map.ObjObjMapFactory 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.*;
import java.util.function.Consumer;
import javax.annotation.Nonnull;
import java.util.Map;
/**
* An immutable factory of {@code ObjObjMap}s.
*
* @param the most general key type of the maps that could be constructed
* by this factory
* @param the most general value type of the maps that could be constructed
* by this factory
* @param the concrete factory type which extends this interface
* @see ObjObjMap
*/
public interface ObjObjMapFactory>
extends ContainerFactory {
/**
* Returns the equivalence to which {@linkplain ObjObjMap#keyEquivalence() key equivalence}
* of the maps constructed by this factory is set.
*
* @return the key equivalence of the maps constructed by this factory
*/
@Nonnull Equivalence getKeyEquivalence();
/**
* Returns the equivalence to which {@linkplain ObjObjMap#valueEquivalence() value
* equivalence} of the maps constructed by this factory is set. Defaults
* to {@link Equivalence#defaultEquality()}.
*
* @return the value equivalence of the maps constructed by this factory
*/
@Nonnull Equivalence getValueEquivalence();
/**
* Returns a copy of this factory, with exception that it constructs maps with
* {@linkplain ObjObjMap#valueEquivalence() value equivalence} set to the given
* {@code Equivalence}.
*
* @param valueEquivalence the new value equivalence
* @return a copy of this factory, which constructs maps with the given {@code valueEquivalence}
*/
@Nonnull
F withValueEquivalence(@Nonnull Equivalence valueEquivalence);
/**
* Constructs a new empty mutable map of the {@linkplain #getDefaultExpectedSize()
* default expected size}.
*
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new empty mutable map
*/
@Nonnull
ObjObjMap newMutableMap();
/**
* Constructs a new empty mutable map of the given expected size.
*
* @param expectedSize the expected size of the returned map
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new empty mutable map of the given expected size
*/
@Nonnull
ObjObjMap newMutableMap(int expectedSize);
/**
* Constructs a new mutable map with the same mappings as the specified {@code map}.
*
*
* If the specified map is an instance of {@code ObjObjMap} and has the same
* {@linkplain ObjObjMap#keyEquivalence() key equivalence} with this factory (and thus
* the constructed map), the {@code expectedSize} argument is ignored.
*
*
* @param map the map whose mappings are to be placed in the returned map
* @param expectedSize the expected size of the returned map
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new mutable map with the same mappings as the specified {@code map}
*/
@Nonnull
ObjObjMap newMutableMap(@Nonnull Map map, int expectedSize);
/**
* Constructs a new mutable map which merge the mappings of the specified maps. On conflict,
* mappings from the {@code map2} have priority over mappings from the {@code map1} with
* the same keys.
*
* @param map1 the first map to merge
* @param map2 the second map to merge
* @param expectedSize the expected size of the returned map
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new mutable map which merge the mappings of the specified maps
*/
@Nonnull
ObjObjMap newMutableMap(@Nonnull Map map1,
@Nonnull Map map2, int expectedSize);
/**
* Constructs a new mutable map which merge the mappings of the specified maps. On conflict,
* mappings from the maps passed later in the argument list have priority over mappings
* from the maps passed earlier with the same keys.
*
* @param map1 the first map to merge
* @param map2 the second map to merge
* @param map3 the third map to merge
* @param expectedSize the expected size of the returned map
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new mutable map which merge the mappings of the specified maps
*/
@Nonnull
ObjObjMap newMutableMap(@Nonnull Map map1,
@Nonnull Map map2,
@Nonnull Map map3, int expectedSize);
/**
* Constructs a new mutable map which merge the mappings of the specified maps. On conflict,
* mappings from the maps passed later in the argument list have priority over mappings
* from the maps passed earlier with the same keys.
*
* @param map1 the first map to merge
* @param map2 the second map to merge
* @param map3 the third map to merge
* @param map4 the fourth map to merge
* @param expectedSize the expected size of the returned map
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new mutable map which merge the mappings of the specified maps
*/
@Nonnull
ObjObjMap newMutableMap(@Nonnull Map map1,
@Nonnull Map map2,
@Nonnull Map map3,
@Nonnull Map map4, int expectedSize);
/**
* Constructs a new mutable map which merge the mappings of the specified maps. On conflict,
* mappings from the maps passed later in the argument list have priority over mappings
* from the maps passed earlier with the same keys.
*
* @param map1 the first map to merge
* @param map2 the second map to merge
* @param map3 the third map to merge
* @param map4 the fourth map to merge
* @param map5 the fifth map to merge
* @param expectedSize the expected size of the returned map
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new mutable map which merge the mappings of the specified maps
*/
@Nonnull
ObjObjMap newMutableMap(@Nonnull Map map1,
@Nonnull Map map2,
@Nonnull Map map3,
@Nonnull Map map4,
@Nonnull Map map5, int expectedSize);
/**
* Constructs a new mutable map filled with mappings consumed by the callback within the given
* closure. Mappings supplied later within the closure have priority over the mappings
* passed earlier with the same keys.
*
* Example: TODO
*
* @param entriesSupplier the function which supply mappings for the returned map via
* the callback passed in
* @param expectedSize the expected size of the returned map
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new mutable map with mappings consumed by the callback within the given closure
*/
@Nonnull
ObjObjMap newMutableMap(@Nonnull
Consumer> entriesSupplier
, int expectedSize);
/**
* Constructs a new mutable map with the given mappings, i. e. pairs of elements from
* the {@code keys} and {@code values} arrays at the same index. If {@code keys} array have
* duplicate elements, value corresponding the key with the highest index is left
* in the returned map.
*
* @param keys the keys of the returned map
* @param values the values of the returned map, each value is associated with the element
* of the {@code keys} array at the same index
* @param expectedSize the expected size of the returned map
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new mutable map with the given mappings
* @throws IllegalArgumentException if {@code keys} and {@code values} arrays have different
* length
*/
@Nonnull
ObjObjMap newMutableMap(
@Nonnull K2[] keys, @Nonnull V2[] values, int expectedSize);
/**
* Constructs a new mutable map with the given mappings, i. e. pairs of elements from
* the {@code keys} and {@code values} iterables at the same iteration position. If {@code keys}
* have duplicate elements, value corresponding the key appeared last in the iteration is left
* in the returned map.
*
* @param keys the keys of the returned map
* @param values the values of the returned map, each value is associated with the element
* of the {@code keys} iterable at the same iteration position
* @param expectedSize the expected size of the returned map
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new mutable map with the given mappings
* @throws IllegalArgumentException if {@code keys} and {@code values} have different size
*/
@Nonnull
ObjObjMap newMutableMap(@Nonnull Iterable keys,
@Nonnull Iterable values, int expectedSize);
/**
* Constructs a new mutable map with the same mappings as the specified {@code map}.
*
*
*
* @param map the map whose mappings are to be placed in the returned map
*
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new mutable map with the same mappings as the specified {@code map}
*/
@Nonnull
ObjObjMap newMutableMap(@Nonnull Map map);
/**
* Constructs a new mutable map which merge the mappings of the specified maps. On conflict,
* mappings from the {@code map2} have priority over mappings from the {@code map1} with
* the same keys.
*
* @param map1 the first map to merge
* @param map2 the second map to merge
*
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new mutable map which merge the mappings of the specified maps
*/
@Nonnull
ObjObjMap newMutableMap(@Nonnull Map map1,
@Nonnull Map map2);
/**
* Constructs a new mutable map which merge the mappings of the specified maps. On conflict,
* mappings from the maps passed later in the argument list have priority over mappings
* from the maps passed earlier with the same keys.
*
* @param map1 the first map to merge
* @param map2 the second map to merge
* @param map3 the third map to merge
*
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new mutable map which merge the mappings of the specified maps
*/
@Nonnull
ObjObjMap newMutableMap(@Nonnull Map map1,
@Nonnull Map map2,
@Nonnull Map map3);
/**
* Constructs a new mutable map which merge the mappings of the specified maps. On conflict,
* mappings from the maps passed later in the argument list have priority over mappings
* from the maps passed earlier with the same keys.
*
* @param map1 the first map to merge
* @param map2 the second map to merge
* @param map3 the third map to merge
* @param map4 the fourth map to merge
*
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new mutable map which merge the mappings of the specified maps
*/
@Nonnull
ObjObjMap newMutableMap(@Nonnull Map map1,
@Nonnull Map map2,
@Nonnull Map map3,
@Nonnull Map map4);
/**
* Constructs a new mutable map which merge the mappings of the specified maps. On conflict,
* mappings from the maps passed later in the argument list have priority over mappings
* from the maps passed earlier with the same keys.
*
* @param map1 the first map to merge
* @param map2 the second map to merge
* @param map3 the third map to merge
* @param map4 the fourth map to merge
* @param map5 the fifth map to merge
*
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new mutable map which merge the mappings of the specified maps
*/
@Nonnull
ObjObjMap newMutableMap(@Nonnull Map map1,
@Nonnull Map map2,
@Nonnull Map map3,
@Nonnull Map map4,
@Nonnull Map map5);
/**
* Constructs a new mutable map filled with mappings consumed by the callback within the given
* closure. Mappings supplied later within the closure have priority over the mappings
* passed earlier with the same keys.
*
* Example: TODO
*
* @param entriesSupplier the function which supply mappings for the returned map via
* the callback passed in
*
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new mutable map with mappings consumed by the callback within the given closure
*/
@Nonnull
ObjObjMap newMutableMap(@Nonnull
Consumer> entriesSupplier
);
/**
* Constructs a new mutable map with the given mappings, i. e. pairs of elements from
* the {@code keys} and {@code values} arrays at the same index. If {@code keys} array have
* duplicate elements, value corresponding the key with the highest index is left
* in the returned map.
*
* @param keys the keys of the returned map
* @param values the values of the returned map, each value is associated with the element
* of the {@code keys} array at the same index
*
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new mutable map with the given mappings
* @throws IllegalArgumentException if {@code keys} and {@code values} arrays have different
* length
*/
@Nonnull
ObjObjMap newMutableMap(
@Nonnull K2[] keys, @Nonnull V2[] values);
/**
* Constructs a new mutable map with the given mappings, i. e. pairs of elements from
* the {@code keys} and {@code values} iterables at the same iteration position. If {@code keys}
* have duplicate elements, value corresponding the key appeared last in the iteration is left
* in the returned map.
*
* @param keys the keys of the returned map
* @param values the values of the returned map, each value is associated with the element
* of the {@code keys} iterable at the same iteration position
*
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new mutable map with the given mappings
* @throws IllegalArgumentException if {@code keys} and {@code values} have different size
*/
@Nonnull
ObjObjMap newMutableMap(@Nonnull Iterable keys,
@Nonnull Iterable values);
/**
* Constructs a new mutable map of the single specified mapping.
*
* @param k1 the key of the sole mapping
* @param v1 the value of the sole mapping
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new mutable map of the single specified mapping
*/
@Nonnull
ObjObjMap newMutableMapOf(K2 k1, V2 v1);
/**
* Constructs a new mutable map of the two specified mappings.
*
* @param k1 the key of the first mapping
* @param v1 the value of the first mapping
* @param k2 the key of the second mapping
* @param v2 the value of the second mapping
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new mutable map of the two specified mappings
*/
@Nonnull
ObjObjMap newMutableMapOf(K2 k1, V2 v1,
K2 k2, V2 v2);
/**
* Constructs a new mutable map of the three specified mappings.
*
* @param k1 the key of the first mapping
* @param v1 the value of the first mapping
* @param k2 the key of the second mapping
* @param v2 the value of the second mapping
* @param k3 the key of the third mapping
* @param v3 the value of the third mapping
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new mutable map of the three specified mappings
*/
@Nonnull
ObjObjMap newMutableMapOf(K2 k1, V2 v1,
K2 k2, V2 v2, K2 k3, V2 v3);
/**
* Constructs a new mutable map of the four specified mappings.
*
* @param k1 the key of the first mapping
* @param v1 the value of the first mapping
* @param k2 the key of the second mapping
* @param v2 the value of the second mapping
* @param k3 the key of the third mapping
* @param v3 the value of the third mapping
* @param k4 the key of the fourth mapping
* @param v4 the value of the fourth mapping
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new mutable map of the four specified mappings
*/
@Nonnull
ObjObjMap newMutableMapOf(K2 k1, V2 v1,
K2 k2, V2 v2, K2 k3, V2 v3,
K2 k4, V2 v4);
/**
* Constructs a new mutable map of the five specified mappings.
*
* @param k1 the key of the first mapping
* @param v1 the value of the first mapping
* @param k2 the key of the second mapping
* @param v2 the value of the second mapping
* @param k3 the key of the third mapping
* @param v3 the value of the third mapping
* @param k4 the key of the fourth mapping
* @param v4 the value of the fourth mapping
* @param k5 the key of the fifth mapping
* @param v5 the value of the fifth mapping
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new mutable map of the five specified mappings
*/
@Nonnull
ObjObjMap newMutableMapOf(K2 k1, V2 v1,
K2 k2, V2 v2, K2 k3, V2 v3,
K2 k4, V2 v4, K2 k5, V2 v5);
/**
* Constructs a new empty updatable map of the {@linkplain #getDefaultExpectedSize()
* default expected size}.
*
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new empty updatable map
*/
@Nonnull
ObjObjMap newUpdatableMap();
/**
* Constructs a new empty updatable map of the given expected size.
*
* @param expectedSize the expected size of the returned map
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new empty updatable map of the given expected size
*/
@Nonnull
ObjObjMap newUpdatableMap(int expectedSize);
/**
* Constructs a new updatable map with the same mappings as the specified {@code map}.
*
*
* If the specified map is an instance of {@code ObjObjMap} and has the same
* {@linkplain ObjObjMap#keyEquivalence() key equivalence} with this factory (and thus
* the constructed map), the {@code expectedSize} argument is ignored.
*
*
* @param map the map whose mappings are to be placed in the returned map
* @param expectedSize the expected size of the returned map
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new updatable map with the same mappings as the specified {@code map}
*/
@Nonnull
ObjObjMap newUpdatableMap(@Nonnull Map map, int expectedSize);
/**
* Constructs a new updatable map which merge the mappings of the specified maps. On conflict,
* mappings from the {@code map2} have priority over mappings from the {@code map1} with
* the same keys.
*
* @param map1 the first map to merge
* @param map2 the second map to merge
* @param expectedSize the expected size of the returned map
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new updatable map which merge the mappings of the specified maps
*/
@Nonnull
ObjObjMap newUpdatableMap(@Nonnull Map map1,
@Nonnull Map map2, int expectedSize);
/**
* Constructs a new updatable map which merge the mappings of the specified maps. On conflict,
* mappings from the maps passed later in the argument list have priority over mappings
* from the maps passed earlier with the same keys.
*
* @param map1 the first map to merge
* @param map2 the second map to merge
* @param map3 the third map to merge
* @param expectedSize the expected size of the returned map
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new updatable map which merge the mappings of the specified maps
*/
@Nonnull
ObjObjMap newUpdatableMap(@Nonnull Map map1,
@Nonnull Map map2,
@Nonnull Map map3, int expectedSize);
/**
* Constructs a new updatable map which merge the mappings of the specified maps. On conflict,
* mappings from the maps passed later in the argument list have priority over mappings
* from the maps passed earlier with the same keys.
*
* @param map1 the first map to merge
* @param map2 the second map to merge
* @param map3 the third map to merge
* @param map4 the fourth map to merge
* @param expectedSize the expected size of the returned map
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new updatable map which merge the mappings of the specified maps
*/
@Nonnull
ObjObjMap newUpdatableMap(@Nonnull Map map1,
@Nonnull Map map2,
@Nonnull Map map3,
@Nonnull Map map4, int expectedSize);
/**
* Constructs a new updatable map which merge the mappings of the specified maps. On conflict,
* mappings from the maps passed later in the argument list have priority over mappings
* from the maps passed earlier with the same keys.
*
* @param map1 the first map to merge
* @param map2 the second map to merge
* @param map3 the third map to merge
* @param map4 the fourth map to merge
* @param map5 the fifth map to merge
* @param expectedSize the expected size of the returned map
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new updatable map which merge the mappings of the specified maps
*/
@Nonnull
ObjObjMap newUpdatableMap(@Nonnull Map map1,
@Nonnull Map map2,
@Nonnull Map map3,
@Nonnull Map map4,
@Nonnull Map map5, int expectedSize);
/**
* Constructs a new updatable map filled with mappings consumed by the callback within the given
* closure. Mappings supplied later within the closure have priority over the mappings
* passed earlier with the same keys.
*
* Example: TODO
*
* @param entriesSupplier the function which supply mappings for the returned map via
* the callback passed in
* @param expectedSize the expected size of the returned map
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new updatable map with mappings consumed by the callback within the given closure
*/
@Nonnull
ObjObjMap newUpdatableMap(@Nonnull
Consumer> entriesSupplier
, int expectedSize);
/**
* Constructs a new updatable map with the given mappings, i. e. pairs of elements from
* the {@code keys} and {@code values} arrays at the same index. If {@code keys} array have
* duplicate elements, value corresponding the key with the highest index is left
* in the returned map.
*
* @param keys the keys of the returned map
* @param values the values of the returned map, each value is associated with the element
* of the {@code keys} array at the same index
* @param expectedSize the expected size of the returned map
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new updatable map with the given mappings
* @throws IllegalArgumentException if {@code keys} and {@code values} arrays have different
* length
*/
@Nonnull
ObjObjMap newUpdatableMap(
@Nonnull K2[] keys, @Nonnull V2[] values, int expectedSize);
/**
* Constructs a new updatable map with the given mappings, i. e. pairs of elements from
* the {@code keys} and {@code values} iterables at the same iteration position. If {@code keys}
* have duplicate elements, value corresponding the key appeared last in the iteration is left
* in the returned map.
*
* @param keys the keys of the returned map
* @param values the values of the returned map, each value is associated with the element
* of the {@code keys} iterable at the same iteration position
* @param expectedSize the expected size of the returned map
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new updatable map with the given mappings
* @throws IllegalArgumentException if {@code keys} and {@code values} have different size
*/
@Nonnull
ObjObjMap newUpdatableMap(@Nonnull Iterable keys,
@Nonnull Iterable values, int expectedSize);
/**
* Constructs a new updatable map with the same mappings as the specified {@code map}.
*
*
*
* @param map the map whose mappings are to be placed in the returned map
*
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new updatable map with the same mappings as the specified {@code map}
*/
@Nonnull
ObjObjMap newUpdatableMap(@Nonnull Map map);
/**
* Constructs a new updatable map which merge the mappings of the specified maps. On conflict,
* mappings from the {@code map2} have priority over mappings from the {@code map1} with
* the same keys.
*
* @param map1 the first map to merge
* @param map2 the second map to merge
*
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new updatable map which merge the mappings of the specified maps
*/
@Nonnull
ObjObjMap newUpdatableMap(@Nonnull Map map1,
@Nonnull Map map2);
/**
* Constructs a new updatable map which merge the mappings of the specified maps. On conflict,
* mappings from the maps passed later in the argument list have priority over mappings
* from the maps passed earlier with the same keys.
*
* @param map1 the first map to merge
* @param map2 the second map to merge
* @param map3 the third map to merge
*
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new updatable map which merge the mappings of the specified maps
*/
@Nonnull
ObjObjMap newUpdatableMap(@Nonnull Map map1,
@Nonnull Map map2,
@Nonnull Map map3);
/**
* Constructs a new updatable map which merge the mappings of the specified maps. On conflict,
* mappings from the maps passed later in the argument list have priority over mappings
* from the maps passed earlier with the same keys.
*
* @param map1 the first map to merge
* @param map2 the second map to merge
* @param map3 the third map to merge
* @param map4 the fourth map to merge
*
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new updatable map which merge the mappings of the specified maps
*/
@Nonnull
ObjObjMap newUpdatableMap(@Nonnull Map map1,
@Nonnull Map map2,
@Nonnull Map map3,
@Nonnull Map map4);
/**
* Constructs a new updatable map which merge the mappings of the specified maps. On conflict,
* mappings from the maps passed later in the argument list have priority over mappings
* from the maps passed earlier with the same keys.
*
* @param map1 the first map to merge
* @param map2 the second map to merge
* @param map3 the third map to merge
* @param map4 the fourth map to merge
* @param map5 the fifth map to merge
*
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new updatable map which merge the mappings of the specified maps
*/
@Nonnull
ObjObjMap newUpdatableMap(@Nonnull Map map1,
@Nonnull Map map2,
@Nonnull Map map3,
@Nonnull Map map4,
@Nonnull Map map5);
/**
* Constructs a new updatable map filled with mappings consumed by the callback within the given
* closure. Mappings supplied later within the closure have priority over the mappings
* passed earlier with the same keys.
*
* Example: TODO
*
* @param entriesSupplier the function which supply mappings for the returned map via
* the callback passed in
*
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new updatable map with mappings consumed by the callback within the given closure
*/
@Nonnull
ObjObjMap newUpdatableMap(@Nonnull
Consumer> entriesSupplier
);
/**
* Constructs a new updatable map with the given mappings, i. e. pairs of elements from
* the {@code keys} and {@code values} arrays at the same index. If {@code keys} array have
* duplicate elements, value corresponding the key with the highest index is left
* in the returned map.
*
* @param keys the keys of the returned map
* @param values the values of the returned map, each value is associated with the element
* of the {@code keys} array at the same index
*
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new updatable map with the given mappings
* @throws IllegalArgumentException if {@code keys} and {@code values} arrays have different
* length
*/
@Nonnull
ObjObjMap newUpdatableMap(
@Nonnull K2[] keys, @Nonnull V2[] values);
/**
* Constructs a new updatable map with the given mappings, i. e. pairs of elements from
* the {@code keys} and {@code values} iterables at the same iteration position. If {@code keys}
* have duplicate elements, value corresponding the key appeared last in the iteration is left
* in the returned map.
*
* @param keys the keys of the returned map
* @param values the values of the returned map, each value is associated with the element
* of the {@code keys} iterable at the same iteration position
*
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new updatable map with the given mappings
* @throws IllegalArgumentException if {@code keys} and {@code values} have different size
*/
@Nonnull
ObjObjMap newUpdatableMap(@Nonnull Iterable keys,
@Nonnull Iterable values);
/**
* Constructs a new updatable map of the single specified mapping.
*
* @param k1 the key of the sole mapping
* @param v1 the value of the sole mapping
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new updatable map of the single specified mapping
*/
@Nonnull
ObjObjMap newUpdatableMapOf(K2 k1, V2 v1);
/**
* Constructs a new updatable map of the two specified mappings.
*
* @param k1 the key of the first mapping
* @param v1 the value of the first mapping
* @param k2 the key of the second mapping
* @param v2 the value of the second mapping
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new updatable map of the two specified mappings
*/
@Nonnull
ObjObjMap newUpdatableMapOf(K2 k1, V2 v1,
K2 k2, V2 v2);
/**
* Constructs a new updatable map of the three specified mappings.
*
* @param k1 the key of the first mapping
* @param v1 the value of the first mapping
* @param k2 the key of the second mapping
* @param v2 the value of the second mapping
* @param k3 the key of the third mapping
* @param v3 the value of the third mapping
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new updatable map of the three specified mappings
*/
@Nonnull
ObjObjMap newUpdatableMapOf(K2 k1, V2 v1,
K2 k2, V2 v2, K2 k3, V2 v3);
/**
* Constructs a new updatable map of the four specified mappings.
*
* @param k1 the key of the first mapping
* @param v1 the value of the first mapping
* @param k2 the key of the second mapping
* @param v2 the value of the second mapping
* @param k3 the key of the third mapping
* @param v3 the value of the third mapping
* @param k4 the key of the fourth mapping
* @param v4 the value of the fourth mapping
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new updatable map of the four specified mappings
*/
@Nonnull
ObjObjMap newUpdatableMapOf(K2 k1, V2 v1,
K2 k2, V2 v2, K2 k3, V2 v3,
K2 k4, V2 v4);
/**
* Constructs a new updatable map of the five specified mappings.
*
* @param k1 the key of the first mapping
* @param v1 the value of the first mapping
* @param k2 the key of the second mapping
* @param v2 the value of the second mapping
* @param k3 the key of the third mapping
* @param v3 the value of the third mapping
* @param k4 the key of the fourth mapping
* @param v4 the value of the fourth mapping
* @param k5 the key of the fifth mapping
* @param v5 the value of the fifth mapping
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new updatable map of the five specified mappings
*/
@Nonnull
ObjObjMap newUpdatableMapOf(K2 k1, V2 v1,
K2 k2, V2 v2, K2 k3, V2 v3,
K2 k4, V2 v4, K2 k5, V2 v5);
/**
* Constructs a new immutable map with the same mappings as the specified {@code map}.
*
*
* If the specified map is an instance of {@code ObjObjMap} and has the same
* {@linkplain ObjObjMap#keyEquivalence() key equivalence} with this factory (and thus
* the constructed map), the {@code expectedSize} argument is ignored.
*
*
* @param map the map whose mappings are to be placed in the returned map
* @param expectedSize the expected size of the returned map
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new immutable map with the same mappings as the specified {@code map}
*/
@Nonnull
ObjObjMap newImmutableMap(@Nonnull Map map, int expectedSize);
/**
* Constructs a new immutable map which merge the mappings of the specified maps. On conflict,
* mappings from the {@code map2} have priority over mappings from the {@code map1} with
* the same keys.
*
* @param map1 the first map to merge
* @param map2 the second map to merge
* @param expectedSize the expected size of the returned map
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new immutable map which merge the mappings of the specified maps
*/
@Nonnull
ObjObjMap newImmutableMap(@Nonnull Map map1,
@Nonnull Map map2, int expectedSize);
/**
* Constructs a new immutable map which merge the mappings of the specified maps. On conflict,
* mappings from the maps passed later in the argument list have priority over mappings
* from the maps passed earlier with the same keys.
*
* @param map1 the first map to merge
* @param map2 the second map to merge
* @param map3 the third map to merge
* @param expectedSize the expected size of the returned map
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new immutable map which merge the mappings of the specified maps
*/
@Nonnull
ObjObjMap newImmutableMap(@Nonnull Map map1,
@Nonnull Map map2,
@Nonnull Map map3, int expectedSize);
/**
* Constructs a new immutable map which merge the mappings of the specified maps. On conflict,
* mappings from the maps passed later in the argument list have priority over mappings
* from the maps passed earlier with the same keys.
*
* @param map1 the first map to merge
* @param map2 the second map to merge
* @param map3 the third map to merge
* @param map4 the fourth map to merge
* @param expectedSize the expected size of the returned map
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new immutable map which merge the mappings of the specified maps
*/
@Nonnull
ObjObjMap newImmutableMap(@Nonnull Map map1,
@Nonnull Map map2,
@Nonnull Map map3,
@Nonnull Map map4, int expectedSize);
/**
* Constructs a new immutable map which merge the mappings of the specified maps. On conflict,
* mappings from the maps passed later in the argument list have priority over mappings
* from the maps passed earlier with the same keys.
*
* @param map1 the first map to merge
* @param map2 the second map to merge
* @param map3 the third map to merge
* @param map4 the fourth map to merge
* @param map5 the fifth map to merge
* @param expectedSize the expected size of the returned map
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new immutable map which merge the mappings of the specified maps
*/
@Nonnull
ObjObjMap newImmutableMap(@Nonnull Map map1,
@Nonnull Map map2,
@Nonnull Map map3,
@Nonnull Map map4,
@Nonnull Map map5, int expectedSize);
/**
* Constructs a new immutable map filled with mappings consumed by the callback within the given
* closure. Mappings supplied later within the closure have priority over the mappings
* passed earlier with the same keys.
*
* Example: TODO
*
* @param entriesSupplier the function which supply mappings for the returned map via
* the callback passed in
* @param expectedSize the expected size of the returned map
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new immutable map with mappings consumed by the callback within the given closure
*/
@Nonnull
ObjObjMap newImmutableMap(@Nonnull
Consumer> entriesSupplier
, int expectedSize);
/**
* Constructs a new immutable map with the given mappings, i. e. pairs of elements from
* the {@code keys} and {@code values} arrays at the same index. If {@code keys} array have
* duplicate elements, value corresponding the key with the highest index is left
* in the returned map.
*
* @param keys the keys of the returned map
* @param values the values of the returned map, each value is associated with the element
* of the {@code keys} array at the same index
* @param expectedSize the expected size of the returned map
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new immutable map with the given mappings
* @throws IllegalArgumentException if {@code keys} and {@code values} arrays have different
* length
*/
@Nonnull
ObjObjMap newImmutableMap(
@Nonnull K2[] keys, @Nonnull V2[] values, int expectedSize);
/**
* Constructs a new immutable map with the given mappings, i. e. pairs of elements from
* the {@code keys} and {@code values} iterables at the same iteration position. If {@code keys}
* have duplicate elements, value corresponding the key appeared last in the iteration is left
* in the returned map.
*
* @param keys the keys of the returned map
* @param values the values of the returned map, each value is associated with the element
* of the {@code keys} iterable at the same iteration position
* @param expectedSize the expected size of the returned map
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new immutable map with the given mappings
* @throws IllegalArgumentException if {@code keys} and {@code values} have different size
*/
@Nonnull
ObjObjMap newImmutableMap(@Nonnull Iterable keys,
@Nonnull Iterable values, int expectedSize);
/**
* Constructs a new immutable map with the same mappings as the specified {@code map}.
*
*
*
* @param map the map whose mappings are to be placed in the returned map
*
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new immutable map with the same mappings as the specified {@code map}
*/
@Nonnull
ObjObjMap newImmutableMap(@Nonnull Map map);
/**
* Constructs a new immutable map which merge the mappings of the specified maps. On conflict,
* mappings from the {@code map2} have priority over mappings from the {@code map1} with
* the same keys.
*
* @param map1 the first map to merge
* @param map2 the second map to merge
*
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new immutable map which merge the mappings of the specified maps
*/
@Nonnull
ObjObjMap newImmutableMap(@Nonnull Map map1,
@Nonnull Map map2);
/**
* Constructs a new immutable map which merge the mappings of the specified maps. On conflict,
* mappings from the maps passed later in the argument list have priority over mappings
* from the maps passed earlier with the same keys.
*
* @param map1 the first map to merge
* @param map2 the second map to merge
* @param map3 the third map to merge
*
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new immutable map which merge the mappings of the specified maps
*/
@Nonnull
ObjObjMap newImmutableMap(@Nonnull Map map1,
@Nonnull Map map2,
@Nonnull Map map3);
/**
* Constructs a new immutable map which merge the mappings of the specified maps. On conflict,
* mappings from the maps passed later in the argument list have priority over mappings
* from the maps passed earlier with the same keys.
*
* @param map1 the first map to merge
* @param map2 the second map to merge
* @param map3 the third map to merge
* @param map4 the fourth map to merge
*
* @param the key type of the returned map
* @param the value type of the returned map
* @return a new immutable map which merge the mappings of the specified maps
*/
@Nonnull