Add SubnetInfo.streamAddressStrings()

src/changes/changes.xml

@@ -83,8 +83,9 @@ The <action> type attribute can be add,update,fix,remove.
       <!-- ADD -->
       <action type="add" dev="ggregory" due-to="Gary Gregory">org.apache.commons.net.nntp.Article#getChild().</action>
       <action type="add" dev="ggregory" due-to="Gary Gregory">org.apache.commons.net.nntp.Article#getNext().</action>
-      <action type="add" dev="ggregory" due-to="Lixiongyou, Gary Gregory">Add SubnetAddressStringIterable and SubnetAddressStringIterator #298.</action> 
+      <action type="add" dev="ggregory" due-to="Lixiongyou, Gary Gregory">Add private SubnetAddressStringIterable and private SubnetAddressStringIterator to implement SubnetInfo.iterableAddressStrings() and SubnetInfo.streamAddressStrings() #298.</action> 
       <action type="add" dev="ggregory" due-to="Gary Gregory">Add SubnetInfo.iterableAddressStrings().</action> 
+      <action type="add" dev="ggregory" due-to="Gary Gregory">Add SubnetInfo.streamAddressStrings().</action> 
       <!-- UPDATE -->
       <action type="update" dev="ggregory" due-to="Gary Gregory, Dependabot">Bump org.apache.commons:commons-parent from 70 to 77 #261, #278, #280, #285, #298, #293.</action>
       <action type="update" dev="ggregory" due-to="Gary Gregory, Dependabot">Bump org.apache.commons:commons-lang3 from 3.14.0 to 3.17.0 #268, #273, #281.</action>

src/main/java/org/apache/commons/net/util/SubnetUtils.java

@@ -20,6 +20,8 @@
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
+import org.apache.commons.io.function.IOStream;
+
 /**
  * Performs subnet calculations given a network address and a subnet mask.
  *
@@ -81,7 +83,7 @@ public String next() {
     }
 
     /**
-     * Convenience container for subnet summary information.
+     * Contains subnet summary information.
      */
     public final class SubnetInfo {
 
@@ -146,8 +148,13 @@ public long getAddressCountLong() {
 
         /**
          * Gets all addresses in this subnet, the return array could be huge.
+         * <p>
+         * For large ranges, you can iterate or stream over the addresses instead using {@link #iterableAddressStrings()} or {@link #streamAddressStrings()}.
+         * </p>
          *
          * @return all addresses in this subnet.
+         * @see #iterableAddressStrings()
+         * @see #streamAddressStrings()
          */
         public String[] getAllAddresses() {
             final int ct = getAddressCount();
@@ -271,6 +278,8 @@ public boolean isInRange(final String address) {
          * Creates a new Iterable of address Strings.
          *
          * @return a new Iterable of address Strings
+         * @see #getAllAddresses()
+         * @see #streamAddressStrings()
          * @since 3.12.0
          */
         public Iterable<String> iterableAddressStrings() {
@@ -286,6 +295,18 @@ private long networkLong() {
             return network & UNSIGNED_INT_MASK;
         }
 
+        /**
+         * Creates a new IOStream of address Strings.
+         *
+         * @return a new IOStream of address Strings
+         * @see #getAllAddresses()
+         * @see #iterableAddressStrings()
+         * @since 3.12.0
+         */
+        public IOStream<String> streamAddressStrings() {
+            return IOStream.of(iterableAddressStrings());
+        }
+
         /**
          * {@inheritDoc}
          *

src/test/java/org/apache/commons/net/util/SubnetUtilsTest.java

@@ -28,6 +28,7 @@
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.List;
+import java.util.stream.Collectors;
 import java.util.stream.LongStream;
 
 import org.apache.commons.collections4.IterableUtils;
@@ -484,6 +485,32 @@ public void testSubnetAddressIterableCount(final ImmutablePair<String, Long> pai
         assertEquals(max, IterableUtils.size(subnetUtils.getInfo().iterableAddressStrings()));
     }
 
+    @Test
+    public void testSubnetAddressStream() {
+        testSubnetAddressStream("192.168.1.0/24", 254);
+    }
+
+    private void testSubnetAddressStream(final String cidrNotation, final long max) {
+        final SubnetUtils subnetUtils = new SubnetUtils(cidrNotation);
+        @SuppressWarnings("resource")
+        final List<String> addressList = subnetUtils.getInfo().streamAddressStrings().collect(Collectors.toList());
+        assertEquals(max, addressList.size());
+        LongStream.rangeClosed(1, max).forEach(i -> addressList.contains("192.168.1." + i));
+        assertFalse(addressList.contains("192.168.1.0"));
+        assertFalse(addressList.contains("192.168.1.255"));
+    }
+
+    @ParameterizedTest
+    @FieldSource("CIDR_SIZES")
+    public void testSubnetAddressStreamCount(final ImmutablePair<String, Long> pair) {
+        final String cidrNotation = pair.getKey();
+        final long max = pair.getValue();
+        final SubnetUtils subnetUtils = new SubnetUtils(cidrNotation);
+        // Fixture values includes counting the host
+        subnetUtils.setInclusiveHostCount(true);
+        assertEquals(max, subnetUtils.getInfo().streamAddressStrings().count());
+    }
+
     @Test
     public void testToString() {
         final SubnetUtils utils = new SubnetUtils("192.168.0.1/29");