Return types array/list/stream [was: API question for point lambdafication]

Stephen Colebourne scolebourne at
Wed Feb 20 02:15:21 PST 2013

I think there is a broader issue underlying Ben's proposed change to
String/regex that warrants proper discussion.

Currently in the JDK APIs we have variuos kinds of return type for
multiples of stuff. Now we are adding another

- arrays
- List
- Set
- Collection
- Iterable
- Iterator
- Enumeration
- Stream - new in JDK 1.8

I know I've personally found the array return types a right royal pain
on many occasions, and I think the decision to make Enum.values()
return an array was a big mistake.

In general, the Collection, Iterable, Iterator and Enumeration options
are relatively little used AFAICT. List is generally more common than
Set (because its much more useful to the client).

My point is that we need to decide on *why* an API should return
Stream rather than any of the other options.

My preference would be as folows:
- only use array as a return type to match other methods in the same type
- prefer List to Set or Collection
- prefer Stream to Iterator and Enumeration (and probably Iterable)
- prefer List to Stream for small/bounded data sets

Thus, on the last point, I would argue that String.splitAsStream() is
wrong, and should be String.splitToList().  (As a side note, with my
general "arrays are bad" hat on, returning an array here was another
bad choice)

Users wanting a stream can easily get it from the list. The reverse is
not so true, and almost certainly more wasteful.


On 19 February 2013 20:45, Ben Evans <benjamin.john.evans at> wrote:
> Hi,
> I've got my regex point lambdafication patch going against the current
> state of lambda, but now I have an API question I'd like some feedback
> on.
> (Btw, if this is more appropriate for core-libs just let me know, and
> I'll take my carcass over there & bug those guys instead.)
> I currently have this new method on java.util.regex.Pattern:
> public Stream<CharSequence> splitAsStream(final CharSequence input);
> This provides a stream of values from the input CharSequence, split
> around occurrences of this pattern.
> However, as the return type of splitAsStream() is
> Stream<CharSequence>, then we need to map stream values back to String
> to be most useful, like this:
>         List<String> out = p.splitAsStream(s)
>                             .map(cs -> cs.toString())
>                             .collect(Collectors.toList());
> So, my question is this - should I continue to use the above
> signature, or should it be:
> public Stream<String> splitAsStream(final CharSequence input);
> This avoids the need for the intermediate map(), which seems like a
> bit of a wart to me.
> Pattern has a vanilla split() method, which returns String[] - so for
> those 2 reasons I'm minded towards the second form.
> Anyone else have any thoughts about this?
> Ben

More information about the lambda-dev mailing list