org.eclipse.collections.api.map.MapIterable Maven / Gradle / Ivy

Go to download
/*
 * Copyright (c) 2022 Goldman Sachs and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * and Eclipse Distribution License v. 1.0 which accompany this distribution.
 * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html
 * and the Eclipse Distribution License is available at
 * http://www.eclipse.org/org/documents/edl-v10.php.
 */

package org.eclipse.collections.api.map;

import java.util.Map;
import java.util.Objects;
import java.util.Optional;
import java.util.Spliterator;
import java.util.Spliterators;
import java.util.function.BiConsumer;
import java.util.stream.Stream;
import java.util.stream.StreamSupport;

import org.eclipse.collections.api.RichIterable;
import org.eclipse.collections.api.block.function.Function;
import org.eclipse.collections.api.block.function.Function0;
import org.eclipse.collections.api.block.function.Function2;
import org.eclipse.collections.api.block.function.Function3;
import org.eclipse.collections.api.block.predicate.Predicate2;
import org.eclipse.collections.api.block.procedure.Procedure;
import org.eclipse.collections.api.block.procedure.Procedure2;
import org.eclipse.collections.api.factory.Maps;
import org.eclipse.collections.api.multimap.Multimap;
import 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.
 */
public interface MapIterable extends RichIterable
{
    /**
     * @see Map#get(Object)
     */
    V get(Object key);

    /**
     * @see Map#containsKey(Object)
     */
    boolean containsKey(Object key);

    /**
     * @see Map#containsValue(Object)
     */
    boolean containsValue(Object value);

    /**
     * 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);
     * 
     */
    void forEachValue(Procedure procedure);

    /**
     * Executes the Procedure for each value of the map and returns {@code this}.
     *
     *      * return peopleByCity.tap(person -> LOGGER.info(person.getName()));
     * 
     *
     * @see #forEach(Procedure)
     * @since 6.0
     */
    @Override
    MapIterable tap(Procedure procedure);

    /**
     * Calls the {@code 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);
     * 
     */
    void forEachKey(Procedure procedure);

    /**
     * Calls the {@code 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");
     * 
     */
    void forEachKeyValue(Procedure2 procedure);

    /**
     * Implements the {@code 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
     */
    default  IV injectIntoKeyValue(
            IV injectedValue,
            Function3 function)
    {
        IV[] result = (IV[]) new Object[]{injectedValue};
        this.forEachKeyValue((key, value) -> result[0] = function.value(result[0], key, value));
        return result[0];
    }

    /**
     * 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)));
     * 
     *
     * @throws IllegalStateException if the MapIterable contains duplicate values.
     * @since 5.0
     */
    MapIterable flipUniqueValues();

    default V getOrDefault(Object key, V defaultValue)
    {
        return this.getIfAbsentValue((K) key, defaultValue);
    }

    /**
     * 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.
     */
    V getIfAbsent(K key, Function0 function);

    /**
     * Return the value in the Map that corresponds to the specified key, or if there is no value at the key, return {@code value}.
     */
    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 the
     * result of evaluating the specified function and parameter.
     */
     V getIfAbsentWith(K key, Function function, P parameter);

    /**
     * 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.
     */
     A ifPresentApply(K key, Function function);

    /**
     * Returns an unmodifiable lazy iterable wrapped around the keySet for the map.
     */
    RichIterable keysView();

    /**
     * Returns an unmodifiable lazy iterable wrapped around the values for the map.
     */
    RichIterable valuesView();

    /**
     * Returns an unmodifiable lazy iterable of key/value pairs wrapped around the entrySet for the map.
     */
    RichIterable> keyValuesView();

    /**
     * Given a map from Domain {@code ->} Range return a multimap from Range {@code ->} 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
     */
    Multimap flip();

    /**
     * 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"));
     * 

     */
    MapIterable select(Predicate2 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"));
     * 
     */
    MapIterable reject(Predicate2 predicate);

    /**
     * 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()));
     * 
     */
     MapIterable collect(Function2> 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());
     * 
     */
     MapIterable collectValues(Function2 function);

    /**
     * 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"));
     * 
     */
    Pair detect(Predicate2 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"));
     * 
     */
    Optional> detectOptional(Predicate2 predicate);

    /**
     * Follows the same general contract as {@link Map#equals(Object)}.
     */
    @Override
    boolean equals(Object o);

    /**
     * Follows the same general contract as {@link Map#hashCode()}.
     */
    @Override
    int hashCode();

    /**
     * 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());
     * 
     *
     * @return a string representation of this MapIterable
     * @see java.util.AbstractMap#toString()
     */
    @Override
    String toString();

    ImmutableMapIterable toImmutable();

    /**
     * @since 9.0
     */
    default Stream stream()
    {
        return StreamSupport.stream(this.spliterator(), false);
    }

    /**
     * @since 9.0
     */
    default Stream parallelStream()
    {
        return StreamSupport.stream(this.spliterator(), true);
    }

    /**
     * @since 9.0
     */
    @Override
    default Spliterator spliterator()
    {
        return Spliterators.spliterator(this.iterator(), (long) this.size(), 0);
    }

    /**
     * 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
     */
    default  MapIterable aggregateBy(
            Function keyFunction,
            Function valueFunction,
            Function0 zeroValueFactory,
            Function2 nonMutatingAggregator)
    {
        MutableMap map = Maps.mutable.empty();
        this.forEachKeyValue((key, value) -> map.updateValueWith(
                keyFunction.valueOf(key),
                zeroValueFactory,
                nonMutatingAggregator,
                valueFunction.valueOf(value)));
        return map;
    }

    default void forEach(BiConsumer action)
    {
        Objects.requireNonNull(action);
        this.forEachKeyValue(action::accept);
    }
}