com.gs.collections.api.map.MapIterable Maven / Gradle / Ivy

Go to download
/*
 * Copyright 2015 Goldman Sachs.
 *
 * 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 com.gs.collections.api.map;

import java.util.Map;

import com.gs.collections.api.RichIterable;
import com.gs.collections.api.block.function.Function;
import com.gs.collections.api.block.function.Function0;
import com.gs.collections.api.block.function.Function2;
import com.gs.collections.api.block.predicate.Predicate2;
import com.gs.collections.api.block.procedure.Procedure;
import com.gs.collections.api.block.procedure.Procedure2;
import com.gs.collections.api.multimap.Multimap;
import com.gs.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}.
     * 
     * 
e.g.
     * return peopleByCity.tap(new Procedure()
     * {
     *     public void value(Person person)
     *     {
     *         LOGGER.info(person.getName());
     *     }
     * });
     * 
     *
     * @see #forEach(Procedure)
     * @since 6.0
     */
    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(new Procedure2<Integer, String>()
     *     {
     *         public void value(final Integer key, final 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 map = this.newMapWithKeysValues(1, "1", 2, "2", 3, "3");
     *     MapIterable 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 -> 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
     */
    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.
     * 

     * 
e.g.
     * peopleByCity.select(new Predicate2<City, Person>()
     * {
     *     public boolean accept(City city, Person person)
     *     {
     *         return 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.
     * 
     * 
e.g.
     * peopleByCity.reject(new Predicate2<City, Person>()
     * {
     *     public boolean accept(City city, Person person)
     *     {
     *         return 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.
     * 
     * 
e.g.
     * peopleByCity.collect(new Function2<City, Person, String>()
     * {
     *     public String value(City city, Person person)
     *     {
     *         return 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.
     * 
     * 
e.g.
     * peopleByCity.collectValues(new Function2<City, Person, String>()
     * {
     *     public String value(City city, Person person)
     *     {
     *         return 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.
     * 
     * 
e.g.
     * peopleByCity.detect(new Predicate2<City, Person>()
     * {
     *     public boolean accept(City city, Person person)
     *     {
     *         return city.getName().equals("Anytown") && person.getLastName().equals("Smith");
     *     }
     * });
     * 
     */
    Pair detect(Predicate2 predicate);

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

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

    /**
     * Returns a string representation of this MapIterable. The string representation consists of a list of the
     * map's key-value pairs in the order they are returned by its iterator. The key and value in each key-value pair are separated
     * by a colon (":") and each pair is enclosed in square brackets ("[]"). Adjacent key-value pairs
     * are separated by the characters ", " (comma and space). Keys and values are converted to strings as by
     * {@link String#valueOf(Object)}.
     *
     * @return a string representation of this MapIterable
     */
    String toString();

    ImmutableMapIterable toImmutable();
}