Typos and possible small errors in the Streams articles ( https://dev.java/learn/api/streams/ )

[willy-b]

Hello dev.java team!
Thanks for the excellent https://dev.java/learn/api/streams/ series of articles on Java Streams.

I would like to report a few typos and other small possible mistakes.

---

In the latest version of article "Adding a Terminal Operation on a Stream", https://dev.java/learn/api/streams/terminal-operations/ (archived at https://web.archive.org/web/20260225004953/https://dev.java/learn/api/streams/terminal-operations/ ):

• A verbatim duplicated code block is introduced with the expectation of being distinct.
  After the code block:

Stream<String> strings = Stream.of("one", "two", "three", "four");

List<String> result =
    strings.filter(s -> s.length() == 3)
           .map(String::toUpperCase)
           .toList();
IO.println("result = " + result);

is presented,
it is said "Starting with Java SE 16, you have a second, even simpler, pattern."
followed by a code block with:

Stream<String> strings = Stream.of("one", "two", "three", "four");

List<String> result =
    strings.filter(s -> s.length() == 3)
           .map(String::toUpperCase)
           .toList();
IO.println("result = " + result);

Which is identical, and thus cannot be "even simpler", suggesting this was repeated in error, see screenshot below:

Maybe the first block was supposed to use ".collect(Collectors.toList())" and the 2nd block ".toList()" (which is newer and simpler)?

However, the article also says the first pattern produces a modifiable list in contrast to the 2nd, but in fact .collect(Collectors.toList()), while not guaranteed to produce an unmodifiable list (unlike .toList),
has no guarantee on modifiability at all, with the documentation stating "there are no guarantees on the type, mutability, serializability, or thread-safety of the List returned; if more control over the returned List is required, use toCollection(Supplier)." (https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/stream/Collectors.html#toList() ).
So the sentence "If what you need is a modifiable list, you should stick to the first collector pattern" must be referring to something else, like .forEach(someList::add) for a manually created mutable list, someList, or should refer to Collectors.toCollection .

• In the next section, when introducing the ".collect(Collectors.toList())" approach, the text states "You already used this pattern in a previous example", when no previous example in this article used this approach. (This also suggests that in the duplicated block above, maybe one of the blocks was intended to be using ".collect(Collectors.toList())" instead of ".toList()"? I think .toList() came in SE 16, so maybe that was supposed to be the second example and ".collect(Collectors.toList())" the first?)

• Not a mistake, but repetition worth reviewing for possible consolidation:
  "Starting with Java SE 16, there is a better way to collect your data in an immutable list, which can be more efficient on some cases. [Same code block as presented 2x above, showing Stream.toList() again]"
  "This optimization has been implemented in the Stream.toList() method, which has been added to Java SE 16. If what you need is an immutable list, then you should be using this pattern."

• Re: "The supplier you used to tune the initial size of you instance of ArrayList can also be used to build any implementation of Collection, including implementations that are not part of the JDK."
  In "used to tune the initial size of you instance", "you instance" should be "your instance".

• Re: "We already covered the max() and min() methods from the specialized streams of numbers: IntStream, LongStream and DoubleStream. You know that these operations do not have an identity element, so you should not be surprised to discover that there are all returning optional objects."
  "there are all returning optional objects" should be "they are all returning optional objects"

• In "You may have noticed an important difference between the different terminal operation that we have covered here.", "operation" should be plural.

---

In the latest version of the "Creating Streams" article, https://dev.java/learn/api/streams/creating/ (as archived at https://web.archive.org/web/20260224131949/https://dev.java/learn/api/streams/creating/ ):

• In the sentence "The random numbers depends on that seed", "depends" should be "depend".

• Potentially confusing: random.ints() described with a range which might not be recognized as matching the code
  (endpoints excluded range; English typically uses endpoints inclusive; and the APIs, including Random.ints(), half-open / half-closed intervals, specifically right-open aka start-inclusive-end-exclusive)

Specifically, it is written "Here is a first pattern of code that generates 10 random integers between 0 and 5."
when the associated code snippet uses

random.ints(10, 1, 5)
          .boxed()
          .toList();

which would return random integers between 1 (inclusive) and 5 (exclusive) (the right-open interval [1, 5)), which is between 0 and 5 only if both endpoints are treated as exclusive (open integer interval (0, 5)) (the text does not specify that both endpoints are excluded).

Endpoints excluded integer intervals/ranges are unusual in both plain English (typically inclusive) and programming (typically half-open / half-closed).

E.g. the Java language specification v25 in English gives numeric ranges typically inclusive, like "an integer between [Emin] and [Emax], inclusive" or "the components of the array are referenced using integer indices from 0 to n - 1, inclusive" or "the shift distance actually used is therefore always in the range 0 to 31, inclusive", etc, while the Java APIs usually use half-open / half-closed intervals (which combine well without double counting), e.g. as in the API used here Random.ints() but also String.substring(), Time APIs like Duration.between, or many other places.

(Many applications use half-open intervals (typically right-open inclusive-exclusive) as any interval can be subdivided easily into half-open intervals without overlap or double counting; intervals excluding both endpoints do not combine well and are usually not used; that is e.g. the right-open interval [1, 3) can be combined with [3, 5) to intuitively get the new half-open interval spanning both, [1, 5). Whereas combining open intervals (both endpoints excluded) with the same endpoints does not even result in an interval, e.g. (1,3) combined with (3, 5) gives the disconnected integers 2 and 4 ({2, 4})).

• "Being able to process these lines with the Stream API gives you a more readable and more maintainable code."
  "gives you a more readable and more maintainable code" should be "gives you more readable and maintainable code"

• "To run it, you need to copy it, paste it in your IDE, and adjust de path to fit your local installation."
  "adjust de path" should be "adjust the path"

• "Note that you cannot run this code in your brower." "brower" should be "browser".

---

In the latest version of an article "Reducing a Stream", https://dev.java/learn/api/streams/reducing/ (archived at https://web.archive.org/web/20260224224658/https://dev.java/learn/api/streams/reducing/ )

• In the sentence "There are two caveats you need to understand though. Let us the first one here and the second one in the next section. ",
  "Let us the first one here" is missing a word after "us". Maybe it was intended to read "Let us discuss the first one here" or something similar.

• Re: "A way to check for that property can be just to run your binary operator on random data and verify if you always get the same result. If you do not, then you know your binary operator is not associative. If you do, then, unfortunately, you cannot conclude reliably." Not a mistake but the last sentence seems unclear. It might be clearer if the last sentence were replaced with something like "If you do, then the operator might be associative but it still may not be, as such a result is inconclusive."

• Re: "Let us an example with a reduction that does not have an identity element."
  "Let us an" should be "Let us do an".

• Re: "The combiner combines two integers: the partial sums of the lengths of the strings processed so far. So the identity element you need to provide is the identity element: O."
  "O" should be the number "0".

• In the sentence: "This way of writing thing clearly shows the fusion of the mapping, modeled by the mapper and the reduction, modeled by the binary operator":
  "thing" should be "things", and I think there should be a comma after "mapper".

---

In the latest version of the article "Adding Intermediate Operations on a Stream", https://dev.java/learn/api/streams/intermediate-operation/ (archived at https://web.archive.org/web/20260224062952/https://dev.java/learn/api/streams/intermediate-operation/ ),

• In the sentence, "This mapToInt() method takes a ToIntFuction as an argument." , "ToIntFuction" should be "ToIntFunction"

• Under "Filtering a Stream",
  "This method is available on streams of objects and stream of primitive types." , it should read "and streams of primitive types" with a plural streams for both types of streams.

In the next example's code block it is written:

Country uk = new Country("United Kindgom", List.of(london, manchester));

with a typo in "United Kindgom".

• Re: "The reason why it is better to use the flatMap() way is that concat() creates intermediates streams during the concatenation." This should use "intermediate" instead of "intermediates".

Thanks so much for all this content!

(If these typo/error reports continue to be desired, it is fine to leave this issue open even after fixing what is reported above so I can add any additional items found, as I am still working through the Streams articles.)

[JosePaumard]

Thank you Willy for your report! I just pushed a fix.
As for the collect(Collectors.toList()). It is not stated that it returns an ArrayList. But it does, and changing this implementation would be a breaking change. It is now set in stone, it will never change. Especially to a list that would be non-modifiable.
And yes, you can totally keep sending reports, many thanks for them!

[willy-b]

Great! Here's another batch of little issues found in these Streams articles.

In the "Using Collectors" article at https://dev.java/learn/api/streams/using-collectors (archived at https://web.archive.org/web/20260225070958/https://dev.java/learn/api/streams/using-collectors/ ),

• "This second example creates a HashSet with only even numbers and without duplicates"
  produces a result that does not match that description (includes non-evens).

The following code snippet is shown:

Set<Integer> evenNumbers =
   IntStream.range(0, 10)
            .map(number -> number / 2)
            .boxed()
            .collect(Collectors.toSet());
IO.println("evenNumbers = " + evenNumbers);

with output:

evenNumbers = [0, 1, 2, 3, 4]

Which are not all even numbers, e.g. 1 and 3 are included.

The result is without duplicates,
but to give even numbers, it would need to be updated, one way would be to have .filter(number -> number % 2 == 0) instead of .map(number -> number / 2).

An updated version of the code could be:

Set<Integer> evenNumbers =
   IntStream.range(0, 10)
            .filter(number -> number % 2 == 0)
            .boxed()
            .collect(Collectors.toSet());
IO.println("evenNumbers = " + evenNumbers);

e.g.:

jshell> Set<Integer> evenNumbers =
  ...>    IntStream.range(0, 10)
  ...>             .filter(number -> number % 2 == 0)
  ...>             .boxed()
  ...>             .collect(Collectors.toSet());
evenNumbers ==> [0, 2, 4, 6, 8]

• In the sentence, "The first one we cover creates map with boolean keys. It is created with the partitionningBy() factory method. "
  "creates map" should be "creates a map", and "partitionningBy()" should be "partitioningBy()".

• In the sentence, "The collector you can use to create histogram is created with the Collectors.groupingBy() method", "to create histogram" should be "to create histograms".

• In the sentence, "The groupingBy() collector supports this, and gather all these elements in a list, bound to that key. ", "and gather all" should be "and gathers all"

• In the sentence, "Let examine the following example.", "Let examine" should be "Let us examine"

• In the sentence, "(element1, element2) -> element1 + ", " + element2) is the merge function, called with the two elements that have generated the same key."
  there is an extra ) at the end of the lambda

• In the sentence, "The Collectors.mappping() factory method creates a regular collector." , "Collectors.mappping()" should be "Collectors.mapping()"

---

In the article on "Finding the Characteristics of a Stream", https://dev.java/learn/api/streams/characteristics/ (archived at: https://web.archive.org/web/20260225071047/https://dev.java/learn/api/streams/characteristics/ ),

• In the sentence, "Covering this spliterator object in details is beyond the scope of this tutorial", "in details" should be "in detail".

• In the sentence, "Let us present each characteristic in more details", it seems "details" should be "detail."

• In the sentence "To check is a stream has a given characteristics, you need to check for a given bit in a word within the spliterator of a stream"
  "To check is a stream has a given characteristics" should probably read "To check IF a stream has given characteristics",
  and "check for a given bit in a word within the spliterator of a stream" might be replaced with "call the hasCharacteristics() method of the spliterator of the stream with the characteristic values to check or directly check for a given bit within the bitmap returned by the .characteristics() method"

• In the sentence "Keeping track of the order of the elements of a stream may lead to overheads for parallel streams", "overheads" should be "overhead."

• In the sentence "strings.stream() is not DISTINCT as it is build from an instance of List.", "as it is build from" should be "as it is built from."

• In the text, "the parallelization mechanism splits a stream in two parts and distribute the computation", (1) "distribute" should be "distributes" and (2) it might be an improvement to write "splits a stream INTO two parts" instead of "in two parts", but (2) is a matter of taste.

• In the sentence, "It is always better to have SIZED and SUBSIZED stream for parallel computations.", "stream" should be "streams".

Thanks!

[JosePaumard]

Thank you again for your report! I just pushed a fix.
I rephrased the part on the characteristic, I hope it's more clear as it is.