Summary

Introduce a new method to java.util.Currency that returns a Stream of the available Currencies.

Problem

Currency provides the method, getAvailableCurrencies() which returns a Set of the available Currencies. While producing a Stream from a Set is simple enough for users, the method makes a defensive copy on the internal set of Currencies. While acting as a convenience, providing a direct stream method also gets rid of the need to perform a intermediate defensive copy operation, as the internal set is streamed directly.

Solution

Directly stream the internal set, avoiding the need and overhead of creating a defensive copy. In the specification of the new method, provide an implementation note that makes it clear no such copy is made to alert users of performance differences.

Specification

Add the new method availableCurrencies()

+    /**
+     * {@return a stream of available currencies} The returned stream of currencies
+     * contains all the available currencies, which may include currencies
+     * that represent obsolete ISO 4217 codes. If there is no currency
+     * available in the runtime, the returned stream is empty.
+     *
+     * @implNote Unlike {@link #getAvailableCurrencies()}, this method does
+     * not create a defensive copy of the {@code Currency} set.
+     * @see #getAvailableCurrencies()
+     * @since 25
+     */
+    public static Stream<Currency> availableCurrencies() {

Some small changes to the existing getAvailableCurrencies() method. The apiNote makes no mention of the defensive copy, as that is an implementation specific caveat.

     /**
-     * Gets the set of available currencies.  The returned set of currencies
-     * contains all of the available currencies, which may include currencies
-     * that represent obsolete ISO 4217 codes.  The set can be modified
+     * {@return a set of available currencies} The returned set of currencies
+     * contains all the available currencies, which may include currencies
+     * that represent obsolete ISO 4217 codes. If there is no currency available
+     * in the runtime, the returned set is empty. The set can be modified
      * without affecting the available currencies in the runtime.
      *
-     * @return the set of available currencies.  If there is no currency
-     *    available in the runtime, the returned set is empty.
+     * @apiNote Consider using {@link #availableCurrencies()} which returns
+     * a stream of the available currencies.
+     * @see #availableCurrencies()
      * @since 1.7
      */
     public static Set<Currency> getAvailableCurrencies() {