• Home
• org.eclipse.collections
• eclipse-collections-api
• 10.3.0.M3
• source code
• MapIterable.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

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

/*
 * Copyright (c) 2018 Goldman Sachs.
 * 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.Optional;
import java.util.Spliterator;
import java.util.Spliterators;
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.predicate.Predicate2;
import org.eclipse.collections.api.block.procedure.Procedure;
import org.eclipse.collections.api.block.procedure.Procedure2;
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);

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

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