Class MapStream<K,​V>

  • Type Parameters:
    K - the key type
    V - the value type
    All Implemented Interfaces:
    AutoCloseable, BaseStream<Map.Entry<K,​V>,​Stream<Map.Entry<K,​V>>>, Stream<Map.Entry<K,​V>>

    public final class MapStream<K,​V>
    extends Object
    implements Stream<Map.Entry<K,​V>>
    A stream implementation based on Map.Entry.

    This stream wraps a Stream&lt;Map.Entry&gt;, providing convenient methods for manipulating the keys and values. Unlike a Map, the keys in a MapStream do not have to be unique, although certain methods will fail if they are not unique.

    • Method Detail

      • of

        public static <K,​V> MapStream<K,​V> of​(Map<K,​V> map)
        Returns a stream over the entries in the map.
        Type Parameters:
        K - the key type
        V - the value type
        Parameters:
        map - the map to wrap
        Returns:
        a stream over the entries in the map
      • of

        public static <K,​V> MapStream<K,​V> of​(Multimap<K,​V> multimap)
        Returns a stream over all the entries in the multimap.

        This will typically create a stream with duplicate keys.

        Type Parameters:
        K - the key type
        V - the value type
        Parameters:
        multimap - the multimap to wrap
        Returns:
        a stream over the entries in the multimap
      • of

        public static <V> MapStream<V,​V> of​(Collection<V> collection)
        Returns a stream of map entries where the keys and values are taken from a collection.
        Type Parameters:
        V - the key and value type
        Parameters:
        collection - the collection
        Returns:
        a stream of map entries derived from the values in the collection
      • of

        public static <V> MapStream<V,​V> of​(Stream<V> stream)
        Returns a stream of map entries where the keys and values are taken from a stream.
        Type Parameters:
        V - the key and value type
        Parameters:
        stream - the stream
        Returns:
        a stream of map entries derived from the values in the stream
      • of

        public static <K,​V> MapStream<K,​V> of​(Collection<V> collection,
                                                          Function<? super V,​? extends K> keyFunction)
        Returns a stream of map entries where the values are taken from a collection and the keys are created by applying a function to each value.
        Type Parameters:
        K - the key type
        V - the value type
        Parameters:
        collection - the collection of values
        keyFunction - a function which returns the key for a value
        Returns:
        a stream of map entries derived from the values in the collection
      • of

        public static <T,​K,​V> MapStream<K,​V> of​(Collection<T> collection,
                                                                  Function<? super T,​? extends K> keyFunction,
                                                                  Function<? super T,​? extends V> valueFunction)
        Returns a stream of map entries where the keys and values are extracted from a collection by applying a function to each item in the collection.
        Type Parameters:
        T - the collection type
        K - the key type
        V - the value type
        Parameters:
        collection - the collection of values
        keyFunction - a function which returns the key
        valueFunction - a function which returns the value
        Returns:
        a stream of map entries derived from the collection
      • of

        public static <K,​V> MapStream<K,​V> of​(Stream<V> stream,
                                                          Function<? super V,​? extends K> keyFunction)
        Returns a stream of map entries where the values are taken from a stream and the keys are created by applying a function to each value.
        Type Parameters:
        K - the key type
        V - the value type
        Parameters:
        stream - the stream of values
        keyFunction - a function which returns the key for a value
        Returns:
        a stream of map entries derived from the values in the stream
      • of

        public static <T,​K,​V> MapStream<K,​V> of​(Stream<T> stream,
                                                                  Function<? super T,​? extends K> keyFunction,
                                                                  Function<? super T,​? extends V> valueFunction)
        Returns a stream of map entries where the keys and values are extracted from a stream by applying a function to each item in the stream.
        Type Parameters:
        T - the collection type
        K - the key type
        V - the value type
        Parameters:
        stream - the stream of values
        keyFunction - a function which returns the key for a value
        valueFunction - a function which returns the value
        Returns:
        a stream of map entries derived from the stream
      • zip

        public static <K,​V> MapStream<K,​V> zip​(Stream<K> keyStream,
                                                           Stream<V> valueStream)
        Returns a map stream that combines two other streams, continuing until either stream ends.

        Note that this can produce a stream with non-unique keys.

        Type Parameters:
        K - the key type
        V - the value type
        Parameters:
        keyStream - the stream of keys
        valueStream - the stream of values
        Returns:
        a stream of map entries derived from the stream
      • zipWithIndex

        public static <V> MapStream<Integer,​V> zipWithIndex​(Stream<V> stream)
        Returns a stream of map entries where each key is the index of the value in the original stream.
        Type Parameters:
        V - the value type
        Parameters:
        stream - the stream of values
        Returns:
        a stream of map entries derived from the stream
      • empty

        public static <K,​V> MapStream<K,​V> empty()
        Returns an empty map stream.
        Type Parameters:
        K - the key type
        V - the value type
        Returns:
        an empty map stream
      • concat

        public static <K,​V> MapStream<K,​V> concat​(MapStream<? extends K,​? extends V> a,
                                                              MapStream<? extends K,​? extends V> b)
        Creates a stream of map entries whose elements are those of the first stream followed by those of the second stream.
        Type Parameters:
        K - the key type
        V - the value type
        Parameters:
        a - the first stream of entries
        b - the second stream of entries
        Returns:
        the concatenation of the two input streams
      • keys

        public Stream<K> keys()
        Returns the keys as a stream, dropping the values.

        A MapStream may contain the same key more than once, so callers may need to call Stream.distinct() on the result.

        Returns:
        a stream of the keys
      • values

        public Stream<V> values()
        Returns the values as a stream, dropping the keys.
        Returns:
        a stream of the values
      • inverse

        public MapStream<V,​K> inverse()
        Returns a stream where the keys and values are swapped.
        Returns:
        a stream with swapped keys and values
      • filter

        public MapStream<K,​V> filter​(BiPredicate<? super K,​? super V> predicate)
        Filters the stream by applying the predicate function to each key and value.

        Entries are included in the returned stream if the predicate function returns true.

        Parameters:
        predicate - a predicate function applied to each key and value in the stream
        Returns:
        a stream including the entries for which the predicate function returned true
      • filterKeys

        public MapStream<K,​V> filterKeys​(Predicate<? super K> predicate)
        Filters the stream by applying the predicate function to each key.

        Entries are included in the returned stream if the predicate function returns true.

        Parameters:
        predicate - a predicate function applied to each key in the stream
        Returns:
        a stream including the entries for which the predicate function returned true
      • filterKeys

        public <R> MapStream<R,​V> filterKeys​(Class<R> castToClass)
        Filters the stream checking the type of each key.

        Entries are included in the returned stream if the key is an instance of the specified type.

        Type Parameters:
        R - the type to filter to
        Parameters:
        castToClass - the class to filter the keys to
        Returns:
        a stream including only those entries where the key is an instance of the specified type
      • filterValues

        public MapStream<K,​V> filterValues​(Predicate<? super V> predicate)
        Filters the stream by applying the predicate function to each value.

        Entries are included in the returned stream if the predicate function returns true.

        Parameters:
        predicate - a predicate function applied to each value in the stream
        Returns:
        a stream including the entries for which the predicate function returned true
      • filterValues

        public <R> MapStream<K,​R> filterValues​(Class<R> castToClass)
        Filters the stream checking the type of each value.

        Entries are included in the returned stream if the value is an instance of the specified type.

        Type Parameters:
        R - the type to filter to
        Parameters:
        castToClass - the class to filter the values to
        Returns:
        a stream including only those entries where the value is an instance of the specified type
      • mapKeys

        public <R> MapStream<R,​V> mapKeys​(Function<? super K,​? extends R> mapper)
        Transforms the keys in the stream by applying a mapper function to each key.

        The values are unchanged.

        Type Parameters:
        R - the type of the new keys
        Parameters:
        mapper - a mapper function whose return value is used as the new key
        Returns:
        a stream of entries with the keys transformed and the values unchanged
      • mapKeys

        public <R> MapStream<R,​V> mapKeys​(BiFunction<? super K,​? super V,​? extends R> mapper)
        Transforms the keys in the stream by applying a mapper function to each key and value.

        The values are unchanged.

        Type Parameters:
        R - the type of the new keys
        Parameters:
        mapper - a mapper function whose return value is used as the new key
        Returns:
        a stream of entries with the keys transformed and the values unchanged
      • mapValues

        public <R> MapStream<K,​R> mapValues​(Function<? super V,​? extends R> mapper)
        Transforms the values in the stream by applying a mapper function to each value.

        The keys are unchanged.

        Type Parameters:
        R - the type of the new values
        Parameters:
        mapper - a mapper function whose return value is used as the new value
        Returns:
        a stream of entries with the values transformed and the keys unchanged
      • mapValues

        public <R> MapStream<K,​R> mapValues​(BiFunction<? super K,​? super V,​? extends R> mapper)
        Transforms the values in the stream by applying a mapper function to each key and value.

        The keys are unchanged.

        Type Parameters:
        R - the type of the new values
        Parameters:
        mapper - a mapper function whose return value is used as the new value
        Returns:
        a stream of entries with the values transformed and the keys unchanged
      • mapBoth

        public <RK,​RV> MapStream<RK,​RV> mapBoth​(BiFunction<? super K,​? super V,​Map.Entry<RK,​RV>> mapper)
        Transforms the entries in the stream by applying a mapper function to each key and value.

        The result of this method is a MapStream, unlike map(BiFunction).

        Type Parameters:
        RK - the type of the new keys
        RV - the type of the new values
        Parameters:
        mapper - a mapper function whose return value is the new key-value entry
        Returns:
        a stream of entries with the keys and values transformed
      • map

        public <R> Stream<R> map​(BiFunction<? super K,​? super V,​? extends R> mapper)
        Transforms the entries in the stream by applying a mapper function to each key and value.
        Type Parameters:
        R - the type of elements in the new stream
        Parameters:
        mapper - a mapper function whose return values are included in the new stream
        Returns:
        a stream containing the values returned from the mapper function
      • mapToDouble

        public DoubleStream mapToDouble​(ToDoubleBiFunction<? super K,​? super V> mapper)
        Transforms the entries in the stream to doubles by applying a mapper function to each key and value.
        Parameters:
        mapper - a mapper function whose return values are included in the new stream
        Returns:
        a stream containing the double values returned from the mapper function
      • mapToInt

        public IntStream mapToInt​(ToIntBiFunction<? super K,​? super V> mapper)
        Transforms the entries in the stream to integers by applying a mapper function to each key and value.
        Parameters:
        mapper - a mapper function whose return values are included in the new stream
        Returns:
        a stream containing the integer values returned from the mapper function
      • flatMapKeys

        public <R> MapStream<R,​V> flatMapKeys​(Function<? super K,​Stream<R>> mapper)
        Transforms the keys in the stream by applying a mapper function to each key.

        The new keys produced will be associated with the original value.

        Type Parameters:
        R - the type of the new keys
        Parameters:
        mapper - a mapper function whose return values are the keys in the new stream
        Returns:
        a stream of entries with new keys from the mapper function assigned to the values
      • flatMapKeys

        public <R> MapStream<R,​V> flatMapKeys​(BiFunction<? super K,​? super V,​Stream<R>> mapper)
        Transforms the keys in the stream by applying a mapper function to each key and value.

        The new keys produced will be associated with the original value.

        For example this could turn a MapStream<List<String>, LocalDate> into a MapStream<String, LocalDate>

        Type Parameters:
        R - the type of the new keys
        Parameters:
        mapper - a mapper function whose return values are the keys in the new stream
        Returns:
        a stream of entries with new keys from the mapper function assigned to the values
      • flatMapValues

        public <R> MapStream<K,​R> flatMapValues​(Function<? super V,​Stream<R>> mapper)
        Transforms the values in the stream by applying a mapper function to each value.

        The new values produced will be associated with the original key.

        For example this could turn a MapStream<LocalDate, List<String>> into a MapStream<LocalDate, String>

        Type Parameters:
        R - the type of the new values
        Parameters:
        mapper - a mapper function whose return values are the values in the new stream
        Returns:
        a stream of entries with new values from the mapper function assigned to the keys
      • flatMapValues

        public <R> MapStream<K,​R> flatMapValues​(BiFunction<? super K,​? super V,​Stream<R>> mapper)
        Transforms the values in the stream by applying a mapper function to each key and value.

        The new values produced will be associated with the original key.

        For example this could turn a MapStream<LocalDate, List<String>> into a MapStream<LocalDate, String>

        Type Parameters:
        R - the type of the new values
        Parameters:
        mapper - a mapper function whose return values are the values in the new stream
        Returns:
        a stream of entries with new values from the mapper function assigned to the keys
      • flatMap

        public <R> Stream<R> flatMap​(BiFunction<? super K,​? super V,​Stream<R>> mapper)
        Transforms the entries in the stream by applying a mapper function to each key and value to produce a stream of elements, and then flattening the resulting stream of streams.
        Type Parameters:
        R - the type of the elements in the new stream
        Parameters:
        mapper - a mapper function whose return values are included in the new stream
        Returns:
        a stream containing the values returned from the mapper function
      • flatMapToDouble

        public DoubleStream flatMapToDouble​(BiFunction<? super K,​? super V,​? extends DoubleStream> mapper)
        Transforms the entries in the stream to doubles by applying a mapper function to each key and value to produce a stream of doubles, and then flattening the resulting stream of streams.
        Parameters:
        mapper - a mapper function whose return values are included in the new stream
        Returns:
        a stream containing the double values returned from the mapper function
      • flatMapToInt

        public IntStream flatMapToInt​(BiFunction<? super K,​? super V,​? extends IntStream> mapper)
        Transforms the entries in the stream to integers by applying a mapper function to each key and value to produce a stream of integers, and then flattening the resulting stream of streams.
        Parameters:
        mapper - a mapper function whose return values are included in the new stream
        Returns:
        a stream containing the integer values returned from the mapper function
      • sortedKeys

        public MapStream<K,​V> sortedKeys()
        Sorts the entries in the stream by comparing the keys using their natural ordering.

        If the keys in this map stream are not Comparable a java.lang.ClassCastException may be thrown. In this case use sortedKeys(Comparator) instead.

        Returns:
        the sorted stream
      • sortedKeys

        public MapStream<K,​V> sortedKeys​(Comparator<? super K> comparator)
        Sorts the entries in the stream by comparing the keys using the supplied comparator.
        Parameters:
        comparator - a comparator of keys
        Returns:
        the sorted stream
      • sortedValues

        public MapStream<K,​V> sortedValues()
        Sorts the entries in the stream by comparing the values using their natural ordering.

        If the values in this map stream are not Comparable a java.lang.ClassCastException may be thrown. In this case use sortedValues(Comparator) instead.

        Returns:
        the sorted stream
      • sortedValues

        public MapStream<K,​V> sortedValues​(Comparator<? super V> comparator)
        Sorts the entries in the stream by comparing the values using the supplied comparator.
        Parameters:
        comparator - a comparator of values
        Returns:
        the sorted stream
      • minKeys

        public Optional<Map.Entry<K,​V>> minKeys​(Comparator<? super K> comparator)
        Finds the minimum entry in the stream by comparing the keys using the supplied comparator.

        This is a terminal operation.

        Parameters:
        comparator - a comparator of keys
        Returns:
        the minimum entry
      • minValues

        public Optional<Map.Entry<K,​V>> minValues​(Comparator<? super V> comparator)
        Finds the minimum entry in the stream by comparing the values using the supplied comparator.

        This is a terminal operation.

        Parameters:
        comparator - a comparator of values
        Returns:
        the minimum entry
      • maxKeys

        public Optional<Map.Entry<K,​V>> maxKeys​(Comparator<? super K> comparator)
        Finds the maximum entry in the stream by comparing the keys using the supplied comparator.

        This is a terminal operation.

        Parameters:
        comparator - a comparator of keys
        Returns:
        the maximum entry
      • maxValues

        public Optional<Map.Entry<K,​V>> maxValues​(Comparator<? super V> comparator)
        Finds the maximum entry in the stream by comparing the values using the supplied comparator.

        This is a terminal operation.

        Parameters:
        comparator - a comparator of values
        Returns:
        the maximum entry
      • anyMatch

        public boolean anyMatch​(BiPredicate<? super K,​? super V> predicate)
        Returns whether any elements of this stream match the provided predicate.

        This is a short-circuiting terminal operation.

        Parameters:
        predicate - the predicate to apply to the entries
        Returns:
        whether any of the entries matched the predicate
      • allMatch

        public boolean allMatch​(BiPredicate<? super K,​? super V> predicate)
        Returns whether all elements of this stream match the provided predicate.

        This is a short-circuiting terminal operation.

        Parameters:
        predicate - the predicate to apply to the entries
        Returns:
        whether all of the entries matched the predicate
      • noneMatch

        public boolean noneMatch​(BiPredicate<? super K,​? super V> predicate)
        Returns whether no elements of this stream match the provided predicate.

        This is a short-circuiting terminal operation.

        Parameters:
        predicate - the predicate to apply to the entries
        Returns:
        whether none of the entries matched the predicate
      • toMap

        public ImmutableMap<K,​V> toMap()
        Returns an immutable map built from the entries in the stream.

        The keys must be unique or an exception will be thrown. Duplicate keys can be handled using toMap(BiFunction).

        This is a terminal operation.

        Returns:
        an immutable map built from the entries in the stream
        Throws:
        IllegalArgumentException - if the same key occurs more than once
      • toMap

        public ImmutableMap<K,​V> toMap​(BiFunction<? super V,​? super V,​? extends V> mergeFn)
        Returns an immutable map built from the entries in the stream.

        If the same key maps to multiple values the merge function is invoked with both values and the return value is used in the map.

        Can be used with concat(MapStream, MapStream) to merge immutable maps with duplicate keys.

        For example, to merge immutable maps with duplicate keys preferring values in the first map:

           MapStream.concat(mapStreamA, mapStreamB).toMap((a,b) -> a);
         

        This is a terminal operation.

        Parameters:
        mergeFn - function used to merge values when the same key appears multiple times in the stream
        Returns:
        an immutable map built from the entries in the stream
      • toMapGrouping

        public ImmutableMap<K,​List<V>> toMapGrouping()
        Returns an immutable map built from the entries in the stream, grouping by key.

        Entries are grouped based on the equality of the key.

        This is a terminal operation.

        Returns:
        an immutable map built from the entries in the stream
      • groupingAndThen

        public MapStream<K,​List<V>> groupingAndThen()
        Returns a stream built from a map of the entries in the stream, grouped by key.

        Entries are grouped based on the equality of the key.

        Returns:
        a stream where the values have been grouped
      • toMapGrouping

        public <A,​R> ImmutableMap<K,​R> toMapGrouping​(Collector<? super V,​A,​R> valueCollector)
        Returns an immutable map built from the entries in the stream, grouping by key.

        Entries are grouped based on the equality of the key. The collector allows the values to be flexibly combined.

        This is a terminal operation.

        Type Parameters:
        A - the internal collector type
        R - the type of the combined values
        Parameters:
        valueCollector - the collector used to combined the values
        Returns:
        an immutable map built from the entries in the stream
      • groupingAndThen

        public <A,​R> MapStream<K,​R> groupingAndThen​(Collector<? super V,​A,​R> valueCollector)
        Returns a stream built from a map of the entries in the stream, grouped by key.

        Entries are grouped based on the equality of the key. The collector allows the values to be flexibly combined.

        Type Parameters:
        A - the internal collector type
        R - the type of the combined values
        Parameters:
        valueCollector - the collector used to combined the values
        Returns:
        a stream where the values have been grouped
      • toListMultimap

        public ImmutableListMultimap<K,​V> toListMultimap()
        Returns an immutable list multimap built from the entries in the stream.

        This is a terminal operation.

        Returns:
        an immutable list multimap built from the entries in the stream
      • toSetMultimap

        public ImmutableSetMultimap<K,​V> toSetMultimap()
        Returns an immutable set multimap built from the entries in the stream.

        This is a terminal operation.

        Returns:
        an immutable set multimap built from the entries in the stream
      • forEach

        public void forEach​(BiConsumer<? super K,​? super V> action)
        Performs an action for each entry in the stream, passing the key and value to the action.

        This is a terminal operation.

        Parameters:
        action - an action performed for each entry in the stream
      • count

        public long count()
        Specified by:
        count in interface Stream<K>