com.gs.collections.api.map

Interface MapIterable<K,V>

All Superinterfaces:

InternalIterable<V>, java.lang.Iterable<V>, RichIterable<V>

All Known Subinterfaces:

BiMap<K,V>, ConcurrentMutableMap<K,V>, FixedSizeMap<K,V>, ImmutableBiMap<K,V>, ImmutableMap<K,V>, ImmutableSortedMap<K,V>, MutableBiMap<K,V>, MutableMap<K,V>, MutableSortedMap<K,V>, SortedMapIterable<K,V>, UnsortedMapIterable<K,V>

public interface MapIterable<K,V>
extends RichIterable<V>

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

Methods

Modifier and Type	Method and Description
<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.
<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.
boolean	containsKey(java.lang.Object key)
boolean	containsValue(java.lang.Object value)
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.
boolean	equals(java.lang.Object o) Follows the same general contract as Map.equals(Object).
Multimap<V,K>	flip() Given a map from Domain -> Range return a multimap from Range -> Domain.
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.
void	forEachKey(Procedure<? super K> procedure) Calls the procedure with each key of the map.
void	forEachKeyValue(Procedure2<? super K,? super V> procedure) Calls the procedure with each key-value pair of the map.
void	forEachValue(Procedure<? super V> procedure) Calls the procedure with each value of the map.
V	get(java.lang.Object key)
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.
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.
<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.
int	hashCode() Follows the same general contract as Map.hashCode().
<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.
RichIterable<K>	keysView() Returns an unmodifiable lazy iterable wrapped around the keySet for the map
RichIterable<Pair<K,V>>	keyValuesView() Returns an unmodifiable lazy iterable of key/value pairs wrapped around the entrySet for the map
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<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.
java.lang.String	toString() Returns a string representation of this MapIterable.
RichIterable<V>	valuesView() Returns an unmodifiable lazy iterable wrapped around the values for the map

Methods inherited from interface com.gs.collections.api.RichIterable

aggregateBy, aggregateInPlaceBy, allSatisfy, allSatisfyWith, anySatisfy, anySatisfyWith, appendString, appendString, appendString, asLazy, chunk, collect, collect, collectBoolean, collectBoolean, collectByte, collectByte, collectChar, collectChar, collectDouble, collectDouble, collectFloat, collectFloat, collectIf, collectIf, collectInt, collectInt, collectLong, collectLong, collectShort, collectShort, collectWith, collectWith, contains, containsAll, containsAllArguments, containsAllIterable, count, countWith, detect, detectIfNone, detectWith, detectWithIfNone, flatCollect, flatCollect, getFirst, getLast, groupBy, groupBy, groupByEach, groupByEach, groupByUniqueKey, injectInto, injectInto, injectInto, injectInto, injectInto, isEmpty, makeString, makeString, makeString, max, max, maxBy, min, min, minBy, noneSatisfy, noneSatisfyWith, notEmpty, partition, partitionWith, reject, reject, rejectWith, rejectWith, select, select, selectInstancesOf, selectWith, selectWith, size, sumOfDouble, sumOfFloat, sumOfInt, sumOfLong, toArray, toArray, toBag, toList, toMap, toSet, toSortedList, toSortedList, toSortedListBy, toSortedMap, toSortedMap, toSortedSet, toSortedSet, toSortedSetBy, zip, zip, zipWithIndex, zipWithIndex

Methods inherited from interface com.gs.collections.api.InternalIterable

forEach, forEachWith, forEachWithIndex

Methods inherited from interface java.lang.Iterable

iterator

Method Detail

get

V get(java.lang.Object key)

See Also:

Map.get(Object)

containsKey

boolean containsKey(java.lang.Object key)

See Also:

Map.containsKey(Object)

containsValue

boolean containsValue(java.lang.Object value)

See Also:

Map.containsValue(Object)

forEachValue

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);
 

forEachKey

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);
 

forEachKeyValue

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(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");
 

flipUniqueValues

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 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:

java.lang.IllegalStateException - if the MapIterable contains duplicate values.

Since:

5.0

getIfAbsent

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.

getIfAbsentValue

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.

getIfAbsentWith

<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.

ifPresentApply

<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.

keysView

RichIterable<K> keysView()

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

valuesView

RichIterable<V> valuesView()

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

keyValuesView

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

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

flip

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.

select

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.

e.g.
 peopleByCity.select(new Predicate2<City, Person>()
 {
     public boolean accept(City city, Person person)
     {
         return city.getName().equals("Anytown") && person.getLastName().equals("Smith");
     }
 });
 

collectValues

<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.

e.g.
 peopleByCity.collectValues(new Function2<City, Person, String>()
 {
     public String value(City city, Person person)
     {
         return person.getFirstName() + " " + person.getLastName();
     }
 });
 

collect

<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.

e.g.
 peopleByCity.collect(new Function2<City, Person, String>()
 {
     public String value(City city, Person person)
     {
         return Pair.of(city.getCountry(), person.getAddress().getCity());
     }
 });
 

reject

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.

e.g.
 peopleByCity.reject(new Predicate2<City, Person>()
 {
     public boolean accept(City city, Person person)
     {
         return city.getName().equals("Anytown") && person.getLastName().equals("Smith");
     }
 });
 

detect

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 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");
     }
 });
 

equals

boolean equals(java.lang.Object o)

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

Overrides:

equals in class java.lang.Object

hashCode

int hashCode()

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

Overrides:

hashCode in class java.lang.Object

toString

java.lang.String toString()

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 String.valueOf(Object).

Specified by:

toString in interface RichIterable<V>

Overrides:

toString in class java.lang.Object

Returns:

a string representation of this MapIterable