Main content

Library Design: Naming Conventions

Part 5: Streaming

Published on 2022-06-08. Last updated on 2025-12-14

Projections

Function Name Code Example Explanation
map(<fun>) List(1, 2, 3).map(_ + 1) --> List(2, 3, 4) Returns a stream in which fun is applied to each element.

mapMany(<fun>)

mapMulti

flatMap

mapFlat

mapAndFlatten

 List(1, 2).mapMany(x -> List(x, x)) --> List(1, 1, 2, 2) List(1, 2).mapMany(x -> Some(x)) --> List(1, 2) List(1, 2).mapMany(x -> None) --> List() Returns a stream in which fun is applied to each element, producing a sequence of elements that is subsequently flattened.

Filters

Function Name Code Example Explanation
first List(1, 2, 3).first --> Option(1) Returns the first element of the stream.
last List(1, 2, 3).last --> Option(3) Returns the last element of the stream.

retainFirst(<num>)

take

keep

pick

 List(1, 2, 3, 4).retainFirst(2) --> List(1, 2) Returns a stream that produces the first num elements of the input stream.

retain(<pred>)

accept

select

filter

 List(1, 2, 3, 1).retain(_ < 2) --> List(1, 2, 1) Returns a stream that produces only elements for which pred evaluates to true.
Alternatives considered:
  • filter is a poor name as it's unclear (especially for non-native speakers) whether "filtered elements" are those retained, or those "filtered out".
  • accept is not ideal, as the visitor pattern also makes use of this name.
  • select is even less ideal, as SQL uses the name for a completely different purpose.

retainIndex(<pred>)

 List("a", "b", "c").retainIndex(_ % 2 == 0) --> List("a", "c") Returns a stream that produces only elements for which pred evaluates to true.

retainWhile(<pred>)

takeWhile

keepWhile

pickWhile

 List(1, 2, 3, 1).retainWhile(_ < 3) --> List(1, 2) Returns a stream that produces elements of the input stream until the pred evaluates to false.

retainUntil(<pred>)

takeUntil

keepUntil

pickUntil

 List(4, 3, 2, 4).retainUntil(_ < 3) --> List(4, 3) Returns a stream that produces elements of the input stream until the pred evaluates to true.
  • Redundant, equivalent to retainWhile(pred.not).

rejectFirst(<num>)

skip

drop

 List(1, 2, 3, 4).rejectFirst(1) --> List(2, 3, 4) Returns a stream without the first num elements of the input stream.

reject(<pred>)

filterNot

 List(1, 2, 3, 1).reject(_ < 2) --> List(3) Returns a stream that produces only elements for which pred evaluates to false.
Alternatives considered:
  • filterNot is a poor name as it's unclear (especially for non-native speakers) whether "filtered elements" are those retained, or those "filtered out".

rejectIndex(<pred>)

 List("a", "b", "c").rejectIndex(_ % 2 == 0) --> List("b") Returns a stream that produces only elements for which pred evaluates to false.

rejectWhile(<pred>)

skipWhile

dropWhile

 List(2, 3, 4, 1).rejectWhile(_ < 2) --> List(3, 4, 1) Returns a stream that skips elements of the input stream until pred evaluates to false.

rejectUntil(<pred>)

skipUntil

dropUntil

 List(3, 2, 1, 4).rejectUntil(_ < 2) --> List(1, 4) Returns a stream that skips elements of the input stream until pred evaluates to true.
Alternatives considered:
  • Redundant, equivalent to rejectWhile(pred.not).
distinct List(1, 2, 3, 1).distinct --> List(1, 2, 3) Returns a stream that produces only the first occurrence of elements occurring multiple times.

Folds

Function Name Code Example Explanation
fold(<num>, <start>)
reduce(<fun>)
combine[Monoid]
sum[Numeric] List(1.0, 2.0, 3.0, 4.0).sum --> 10.0 Computes the sum of the list of numbers.
product[Numeric] List(1.0, 2.0, 3.0, 4.0).product --> 24.0 Computes the product of the list of numbers.
average[Numeric] List(1.0, 2.0, 3.0, 4.0).average --> 2.5 Computes the average of the list of numbers.

all(<pred>)

forAll

 Returns true if pred returns true for all elements.

any(<pred>)

forAny

 Returns true if pred returns true for any element.

none(<pred>)

forNone

 Returns true if pred returns false for all elements.

Injects

Function Name Code Example Explanation
joinInner[Record]
joinLeft[Record]
joinRight[Record]
joinFull[Record]
groupBy(<fun>)
partitionBy(<fun>)

Fan-Ins

Function Name Code Example Explanation
concat Returns a stream that produces the values from the first stream and then the values of the second stream.
interleave Returns a stream that produces a value, alternating between the first and second stream.
  • Likely requires multiple method variants that handle streams of different lengths in different ways.
zip Returns a stream that produces a tuple value, where the first element is from the first stream and the second element is from the second stream.
  • Likely requires multiple method variants that handle streams of different lengths in different ways.
zipWithIndex Returns a stream that produces a tuple value, where the first element is from the stream and the second element is the index at which the value was produced.