Top Description Methods
org.eclipse.collections.api.map

public Interface MapIterable<K, V>

extends RichIterable<V>
Known Direct Subinterfaces
org.eclipse.collections.api.map.MutableMapIterable, org.eclipse.collections.api.map.OrderedMap, org.eclipse.collections.api.map.UnsortedMapIterable, org.eclipse.collections.api.map.sorted.SortedMapIterable, org.eclipse.collections.api.bimap.BiMap, org.eclipse.collections.api.map.ImmutableMapIterable
Imports
java.util.Map, .Objects, .Optional, .Spliterator, .Spliterators, java.util.function.BiConsumer, java.util.stream.Stream, .StreamSupport, org.eclipse.collections.api.RichIterable, org.eclipse.collections.api.block.function.Function, .Function0, .Function2, .Function3, org.eclipse.collections.api.block.predicate.Predicate2, org.eclipse.collections.api.block.procedure.Procedure, .Procedure2, org.eclipse.collections.api.factory.Maps, org.eclipse.collections.api.multimap.Multimap, org.eclipse.collections.api.tuple.Pair

A Read-only Map API, with the minor exception inherited from java.lang.Iterable. The method map.iterator().remove() will throw an UnsupportedOperationException.

Method Summary

Modifier and TypeMethod and Description
public default <K1, V1, V2> MapIterable<K1, V2>
aggregateBy(Function<? super K, ? extends K1> keyFunction, Function<? super V, ? extends V1> valueFunction, Function0<? extends V2> zeroValueFactory, Function2<? super V2, ? super V1, ? extends V2> nonMutatingAggregator)

Applies an aggregate function over the map grouping results into a map based on the specific key and value groupBy functions.

public <K2, V2> MapIterable<K2, V2>
collect(Function2<? super K, ? super V, Pair<K2, V2>> function)

For each key and value of the map the function is evaluated.

public <R> MapIterable<R, V>
collectKeysUnique(Function2<? super K, ? super V, ? extends R> function)

For each key and value of the map the function is evaluated.

public <R> MapIterable<K, R>
collectValues(Function2<? super K, ? super V, ? extends R> function)

For each key and value of the map the function is evaluated.

public boolean
public boolean
public Pair<K, V>
detect(Predicate2<? super K, ? super V> predicate)

Return the first key and value of the map for which the predicate evaluates to true when they are given as arguments.

public Optional<Pair<K, V>>
detectOptional(Predicate2<? super K, ? super V> predicate)

Return the first key and value of the map as an Optional for which the predicate evaluates to true when they are given as arguments.

public boolean
equals(Object o)

Follows the same general contract as Map#equals(Object).

public Multimap<V, K>
flip()

Given a map from Domain -> Range return a multimap from Range -> Domain.

public MapIterable<V, K>
flipUniqueValues()

Return the MapIterable that is obtained by flipping the direction of this map and making the associations from value to key.

public default void
forEach(BiConsumer<? super K, ? super V> action)

public void
forEachKey(Procedure<? super K> procedure)

Calls the procedure with each key of the map.

public void
forEachKeyValue(Procedure2<? super K, ? super V> procedure)

Calls the procedure with each key-value pair of the map.

public void
forEachValue(Procedure<? super V> procedure)

Calls the procedure with each value of the map.

public V
get(Object key)

public V
getIfAbsent(K key, Function0<? extends V> function)

Return the value in the Map that corresponds to the specified key, or if there is no value at the key, return the result of evaluating the specified Function0.

public V
getIfAbsentValue(K key, V value)

Return the value in the Map that corresponds to the specified key, or if there is no value at the key, return value.

public <P> V
getIfAbsentWith(K key, Function<? super P, ? extends V> function, P parameter)

Return the value in the Map that corresponds to the specified key, or if there is no value at the key, return the result of evaluating the specified function and parameter.

public default V
getOrDefault(Object key, V defaultValue)

public int
hashCode()

Follows the same general contract as Map#hashCode().

public <A> A
ifPresentApply(K key, Function<? super V, ? extends A> function)

If there is a value in the Map that corresponds to the specified key return the result of applying the specified Function on the value, otherwise return null.

public default <IV> IV
injectIntoKeyValue(IV injectedValue, Function3<? super IV, ? super K, ? super V, ? extends IV> function)

Implements the injectInto pattern with each key-value pair of the map.

public RichIterable<K>
keysView()

Returns an unmodifiable lazy iterable wrapped around the keySet for the map.

public RichIterable<Pair<K, V>>
keyValuesView()

Returns an unmodifiable lazy iterable of key/value pairs wrapped around the entrySet for the map.

public default Stream<V>
public MapIterable<K, V>
reject(Predicate2<? super K, ? super V> predicate)

For each key and value of the map the predicate is evaluated, if the result of the evaluation is false, that key and value are returned in a new map.

public MapIterable<K, V>
select(Predicate2<? super K, ? super V> predicate)

For each key and value of the map the predicate is evaluated, if the result of the evaluation is true, that key and value are returned in a new map.

public default Spliterator<V>
spliterator()

Overrides default java.lang.Iterable.spliterator.

Creates a Spliterator over the elements described by this Iterable.

public default Stream<V>
public MapIterable<K, V>
tap(Procedure<? super V> procedure)

Redeclares org.eclipse.collections.api.RichIterable.tap.

Executes the Procedure for each value of the map and returns this.

public ImmutableMapIterable<K, V>
public String

Returns:

a string representation of this MapIterable
toString
()

Redeclares org.eclipse.collections.api.RichIterable.toString.

Returns a string with the keys and values of this map separated by commas with spaces and enclosed in curly braces.

public RichIterable<V>
valuesView()

Returns an unmodifiable lazy iterable wrapped around the values for the map.

Inherited from org.eclipse.collections.api.RichIterable:
aggregateByaggregateByaggregateInPlaceByallSatisfyallSatisfyWithanySatisfyanySatisfyWithappendStringappendStringappendStringasLazychunkcollectcollectcollectBooleancollectBooleancollectBytecollectBytecollectCharcollectCharcollectDoublecollectDoublecollectFloatcollectFloatcollectIfcollectIfcollectIntcollectIntcollectLongcollectLongcollectShortcollectShortcollectWithcollectWithcontainscontainsAllcontainsAllArgumentscontainsAllIterablecontainsAnycontainsAnyIterablecontainsBycontainsNonecontainsNoneIterablecountcountBycountBycountByEachcountByEachcountByWithcountByWithcountWithdetectdetectIfNonedetectOptionaldetectWithdetectWithIfNonedetectWithOptionaleachflatCollectflatCollectflatCollectBooleanflatCollectByteflatCollectCharflatCollectDoubleflatCollectFloatflatCollectIntflatCollectLongflatCollectShortflatCollectWithflatCollectWithforEachgetAnygetFirstgetLastgetOnlygroupBygroupBygroupByAndCollectgroupByEachgroupByEachgroupByUniqueKeygroupByUniqueKeyinjectIntoinjectIntoinjectIntoinjectIntoinjectIntoinjectIntoDoubleinjectIntoFloatinjectIntoIntinjectIntoLongintoisEmptymakeStringmakeStringmakeStringmakeStringmaxmaxmaxBymaxByOptionalmaxOptionalmaxOptionalminminminByminByOptionalminOptionalminOptionalnoneSatisfynoneSatisfyWithnotEmptypartitionpartitionWithreducereduceByreduceByreduceInPlacereduceInPlacerejectrejectrejectWithrejectWithselectselectselectInstancesOfselectWithselectWithsizesumByDoublesumByFloatsumByIntsumByLongsummarizeDoublesummarizeFloatsummarizeIntsummarizeLongsumOfDoublesumOfFloatsumOfIntsumOfLongtoArraytoArraytoBagtoBiMaptoImmutableBagtoImmutableBiMaptoImmutableListtoImmutableMaptoImmutableSettoImmutableSortedBagtoImmutableSortedBagtoImmutableSortedBagBytoImmutableSortedListtoImmutableSortedListtoImmutableSortedListBytoImmutableSortedSettoImmutableSortedSettoImmutableSortedSetBytoListtoMaptoMaptoSettoSortedBagtoSortedBagtoSortedBagBytoSortedListtoSortedListtoSortedListBytoSortedMaptoSortedMaptoSortedMapBytoSortedSettoSortedSettoSortedSetByzipzipzipWithIndexzipWithIndex

Method Detail

aggregateByback to summary
public default <K1, V1, V2> MapIterable<K1, V2> aggregateBy(Function<? super K, ? extends K1> keyFunction, Function<? super V, ? extends V1> valueFunction, Function0<? extends V2> zeroValueFactory, Function2<? super V2, ? super V1, ? extends V2> nonMutatingAggregator)

Applies an aggregate function over the map grouping results into a map based on the specific key and value groupBy functions. Aggregate results are allowed to be immutable as they will be replaced in place in the map. A second function specifies the initial "zero" aggregate value to work with.

MapIterable<String, Interval> map = Maps.mutable.with("oneToFive", Interval.fromTo(1, 5), "sixToNine", Interval.fromTo(6, 9));

MapIterable<String, Long> result = map.aggregateBy(
        eachKey -> {
            return eachKey.equals("oneToFive")  ? "lessThanSix" : "greaterOrEqualsToSix";
        },
        each -> each.sumOfInt(Integer::intValue),
        () -> 0L,
        (argument1, argument2) -> argument1 + argument2);

MapIterable<String, Long> expected =
        Maps.mutable.with("lessThanSix", Interval.fromTo(1, 5).sumOfInt(Integer::intValue),
                "greaterOrEqualsToSix", Interval.fromTo(6, 9).sumOfInt(Integer::intValue));
Assert.assertEquals(expected, result);
Since
10.3.0
collectback to summary
public <K2, V2> MapIterable<K2, V2> collect(Function2<? super K, ? super V, Pair<K2, V2>> function)

For each key and value of the map the function is evaluated. The results of these evaluations are returned in a new map. The map returned will use the values projected from the function rather than the original values.

MapIterable<String, String> collected =
    peopleByCity.collect((City city, Person person) -> Pair.of(city.getCountry(), person.getAddress().getCity()));
collectKeysUniqueback to summary
public <R> MapIterable<R, V> collectKeysUnique(Function2<? super K, ? super V, ? extends R> function)

For each key and value of the map the function is evaluated. The results of these evaluations are returned in a new map. The map returned will use the keys projected from the function rather than the original keys.

Exceptions
IllegalStateException:
if the keys returned by the function are not unique
Since
12.0
collectValuesback to summary
public <R> MapIterable<K, R> collectValues(Function2<? super K, ? super V, ? extends R> function)

For each key and value of the map the function is evaluated. The results of these evaluations are returned in a new map. The map returned will use the values projected from the function rather than the original values.

MapIterable<City, String> collected =
    peopleByCity.collectValues((City city, Person person) -> person.getFirstName() + " " + person.getLastName());
containsKeyback to summary
public boolean containsKey(Object key)
See Also
Map#containsKey(Object)
containsValueback to summary
public boolean containsValue(Object value)
See Also
Map#containsValue(Object)
detectback to summary
public Pair<K, V> detect(Predicate2<? super K, ? super V> predicate)

Return the first key and value of the map for which the predicate evaluates to true when they are given as arguments. The predicate will only be evaluated until such pair is found or until all the keys and values of the map have been used as arguments. That is, there may be keys and values of the map that are never used as arguments to the predicate. The result is null if predicate does not evaluate to true for any key/value combination.

Pair<City, Person> detected =
    peopleByCity.detect((City city, Person person) -> city.getName().equals("Anytown") && person.getLastName().equals("Smith"));
detectOptionalback to summary
public Optional<Pair<K, V>> detectOptional(Predicate2<? super K, ? super V> predicate)

Return the first key and value of the map as an Optional for which the predicate evaluates to true when they are given as arguments. The predicate will only be evaluated until such pair is found or until all the keys and values of the map have been used as arguments. That is, there may be keys and values of the map that are never used as arguments to the predicate.

Optional<Pair<City, Person>> detected =
    peopleByCity.detectOptional((city, person)
         -> city.getName().equals("Anytown") && person.getLastName().equals("Smith"));
equalsback to summary
public boolean equals(Object o)

Follows the same general contract as Map#equals(Object).

Annotations
@Override
flipback to summary
public Multimap<V, K> flip()

Given a map from Domain -> Range return a multimap from Range -> Domain. We chose the name 'flip' rather than 'invert' or 'transpose' since this method does not have the property of applying twice returns the original.

Since the keys in the input are unique, the values in the output are unique, so the return type should be a SetMultimap. However, since SetMultimap and SortedSetMultimap don't inherit from one another, SetMultimap here does not allow SortedMapIterable to have a SortedSetMultimap return. Thus, we compromise and call this Multimap, even though all implementations will be a SetMultimap or SortedSetMultimap.

Since
5.0
flipUniqueValuesback to summary
public MapIterable<V, K> flipUniqueValues()

Return the MapIterable that is obtained by flipping the direction of this map and making the associations from value to key.

    MapIterable<Integer, String> map = this.newMapWithKeysValues(1, "1", 2, "2", 3, "3");
    MapIterable<String, Integer> result = map.flipUniqueValues();
    Assert.assertTrue(result.equals(UnifiedMap.newWithKeysValues("1", 1, "2", 2, "3", 3)));
Exceptions
IllegalStateException:
if the MapIterable contains duplicate values.
Since
5.0
forEachback to summary
public default void forEach(BiConsumer<? super K, ? super V> action)
forEachKeyback to summary
public void forEachKey(Procedure<? super K> procedure)

Calls the procedure with each key of the map.

    final Collection<Integer> result = new ArrayList<Integer>();
    MutableMap<Integer, String> map = this.newMapWithKeysValues(1, "1", 2, "2", 3, "3");
    map.forEachKey(new CollectionAddProcedure<Integer>(result));
    Verify.assertContainsAll(result, 1, 2, 3);
forEachKeyValueback to summary
public void forEachKeyValue(Procedure2<? super K, ? super V> procedure)

Calls the procedure with each key-value pair of the map.

    final Collection<String> collection = new ArrayList<String>();
    MutableMap<Integer, String> map = this.newMapWithKeysValues(1, "One", 2, "Two", 3, "Three");
    map.forEachKeyValue((Integer key, String value) -> collection.add(String.valueOf(key) + value));
    Verify.assertContainsAll(collection, "1One", "2Two", "3Three");
forEachValueback to summary
public void forEachValue(Procedure<? super V> procedure)

Calls the procedure with each value of the map.

    Set<String> result = UnifiedSet.newSet();
    MutableMap<Integer, String> map = this.newMapWithKeysValues(1, "One", 2, "Two", 3, "Three", 4, "Four");
    map.forEachValue(new CollectionAddProcedure<String>(result));
    Verify.assertSetsEqual(UnifiedSet.newSetWith("One", "Two", "Three", "Four"), result);
getback to summary
public V get(Object key)
See Also
Map#get(Object)
getIfAbsentback to summary
public V getIfAbsent(K key, Function0<? extends V> function)

Return the value in the Map that corresponds to the specified key, or if there is no value at the key, return the result of evaluating the specified Function0.

getIfAbsentValueback to summary
public V getIfAbsentValue(K key, V value)

Return the value in the Map that corresponds to the specified key, or if there is no value at the key, return value.

getIfAbsentWithback to summary
public <P> V getIfAbsentWith(K key, Function<? super P, ? extends V> function, P parameter)

Return the value in the Map that corresponds to the specified key, or if there is no value at the key, return the result of evaluating the specified function and parameter.

getOrDefaultback to summary
public default V getOrDefault(Object key, V defaultValue)
hashCodeback to summary
public int hashCode()

Follows the same general contract as Map#hashCode().

Annotations
@Override
ifPresentApplyback to summary
public <A> A ifPresentApply(K key, Function<? super V, ? extends A> function)

If there is a value in the Map that corresponds to the specified key return the result of applying the specified Function on the value, otherwise return null.

injectIntoKeyValueback to summary
public default <IV> IV injectIntoKeyValue(IV injectedValue, Function3<? super IV, ? super K, ? super V, ? extends IV> function)

Implements the injectInto pattern with each key-value pair of the map.

    MapIterable<Integer, Integer> map1 = Maps.immutable.with(3, 3, 2, 2, 1, 1);
    Integer sum1 = map1.injectIntoKeyValue(0, (sum, key, value) -> sum + key + value);
    assertEquals(12, sum1);
Since
11.1
keysViewback to summary
public RichIterable<K> keysView()

Returns an unmodifiable lazy iterable wrapped around the keySet for the map.

keyValuesViewback to summary
public RichIterable<Pair<K, V>> keyValuesView()

Returns an unmodifiable lazy iterable of key/value pairs wrapped around the entrySet for the map.

parallelStreamback to summary
public default Stream<V> parallelStream()
Since
9.0
rejectback to summary
public MapIterable<K, V> reject(Predicate2<? super K, ? super V> predicate)

For each key and value of the map the predicate is evaluated, if the result of the evaluation is false, that key and value are returned in a new map.

MapIterable<City, Person> rejected =
    peopleByCity.reject((city, person) -> city.getName().equals("Anytown") && person.getLastName().equals("Smith"));
selectback to summary
public MapIterable<K, V> select(Predicate2<? super K, ? super V> predicate)

For each key and value of the map the predicate is evaluated, if the result of the evaluation is true, that key and value are returned in a new map.

MapIterable<City, Person> selected =
    peopleByCity.select((city, person) -> city.getName().equals("Anytown") && person.getLastName().equals("Smith"));
spliteratorback to summary
public default Spliterator<V> spliterator()

Overrides default java.lang.Iterable.spliterator.

Doc from java.lang.Iterable.spliterator.

Creates a Spliterator over the elements described by this Iterable.

Annotations
@Override
Since
9.0
streamback to summary
public default Stream<V> stream()
Since
9.0
tapback to summary
public MapIterable<K, V> tap(Procedure<? super V> procedure)

Redeclares org.eclipse.collections.api.RichIterable.tap.

Executes the Procedure for each value of the map and returns this.

return peopleByCity.tap(person -> LOGGER.info(person.getName()));
Annotations
@Override
Since
6.0
See Also
forEach(Procedure)
toImmutableback to summary
public ImmutableMapIterable<K, V> toImmutable()
toStringback to summary
public String toString()

Redeclares org.eclipse.collections.api.RichIterable.toString.

Returns a string with the keys and values of this map separated by commas with spaces and enclosed in curly braces. Each key and value is separated by an equals sign.

Assert.assertEquals("{1=1, 2=2, 3=3}", Maps.mutable.with(1, 1, 2, 2, 3, 3).toString());
Returns:String

a string representation of this MapIterable

Annotations
@Override
See Also
java.util.AbstractMap#toString()
valuesViewback to summary
public RichIterable<V> valuesView()

Returns an unmodifiable lazy iterable wrapped around the values for the map.