Feature / Use Case
↓
.map()
↓
.flatMap()
Purpose
↓
Transforms each element into exactly one new element
↓
Transforms each element into zero, one, or many elements, then flattens into a single stream
Return type of mapper
↓
Function<T, R> → returns a single value
↓
Function<T, Stream<R>> → returns a stream for each element
Output Stream
↓
Stream of transformed elements
↓
Stream of flattened elements
When to use
↓
One-to-one mapping (e.g., String → Integer)
↓
One-to-many mapping (e.g., String → List<String>)
Example Input
↓
["apple", "banana"]
↓
["apple banana", "cherry date"]
Example Output
↓
[5, 6] (lengths)
↓
["apple", "banana", "cherry", "date"] (split words)
Example 1 — .map() (One-to-One)
import java.util.*;
import java.util.stream.*;
public class MapVsFlatMap1 {
public static void main(String[] args) {
List<String> words = Arrays.asList("apple", "banana");
List<Integer> lengths = words.stream()
.map(String::length) // String → Integer
.collect(Collectors.toList());
System.out.println(lengths); // [5, 6]
}
}
Example 2 — .flatMap() (One-to-Many)
import java.util.*;
import java.util.stream.*;
public class MapVsFlatMap2 {
public static void main(String[] args) {
List<String> phrases = Arrays.asList("apple banana", "cherry date");
List<String> allWords = phrases.stream()
.flatMap(p -> Arrays.stream(p.split(" "))) // String → Stream<String>
.collect(Collectors.toList());
System.out.println(allWords); // [apple, banana, cherry, date]
}
}
- Quick Rule of Thumb
.map()→ You end up with Stream<R> .flatMap()→ You end up with Stream<R> but flattened from multiple sub-streams
💡 Pro Tips:
If your mapping function returns a collection, array, or another stream, you almost always need.flatMap()to avoid nested structures likeStream<List<T>>.
If you want, I can also make a visual diagram showing how.map()and.flatMap()transform data step-by-step — that’s often the easiest way to remember the difference.