Add ImmutableRangeMap.toImmutableRangeMap(Function keyFunction, Function valueFunction, BinaryOperator mergeFunction)

[perceptron8]

1. What are you trying to do?

I'd like to (be able to) build ImmutableRangeMap from stream using collector given that some of the resulting ranges overlap.

record Job(Instant start, Instant end) {
	Job {
		Objects.requireNonNull(start);
		Objects.requireNonNull(end);
	}
	
	Range<Instant> span() {
		return Range.closedOpen(start, end);
	}
}

2. What's the best code you can write to accomplish that without the new feature?

RangeMap<Instant, Integer> load(List<Job> jobs) {
	RangeMap<Instant, Integer> load = TreeRangeMap.create();
	for (Job job : jobs) {
		load.merge(job.span(), 1, Integer::sum);
	}
	return ImmutableRangeMap.copyOf(load);
}

3. What would that same code look like if we added your feature?

RangeMap<Instant, Integer> load(List<Job> jobs) {
	return jobs.stream().collect(ImmutableRangeMap
		.toImmutableRangeMap(Job::span, always -> 1, Integer::sum));
}

(Optional) What would the method signatures for your feature look like?

public static <T extends @Nullable Object, K extends Comparable<? super K>, V>
Collector<T, ?, ImmutableRangeMap<K, V>> toImmutableRangeMap(
          Function<? super T, Range<K>> keyFunction,
          Function<? super T, ? extends V> valueFunction,
          BinaryOperator<V> mergeFunction
)

Concrete Use Cases

Real use case involves checking if given family is entitled to receive social care. This is based on number of members, their health, income, several legal documents and so on. All conditions are time based and so are the grants.

Packages

com.google.common.collect

Checklist

• I agree to follow the code of conduct.

• I have read and understood the contribution guidelines.

• I have read and understood Guava's philosophy, and I strongly believe that this proposal aligns with it.

• I have visited the idea graveyard, and did not see anything similar to this idea.