GEOMETRY-108: adding BoundaryList classes

commons-geometry-core/src/main/java/org/apache/commons/geometry/core/partitioning/AbstractConvexHyperplaneBoundedRegion.java

@@ -144,7 +144,8 @@ public String toString() {
         final StringBuilder sb = new StringBuilder();
         sb.append(this.getClass().getSimpleName())
             .append("[boundaries= ")
-            .append(boundaries);
+            .append(boundaries)
+            .append(']');
 
         return sb.toString();
     }

commons-geometry-core/src/main/java/org/apache/commons/geometry/core/partitioning/BoundaryList.java

@@ -0,0 +1,82 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.geometry.core.partitioning;
+
+import java.util.Collections;
+import java.util.List;
+import java.util.stream.Stream;
+
+import org.apache.commons.geometry.core.Point;
+
+/** Simple implementation of {@link BoundarySource} containing boundaries stored in a list.
+ * Lists given during construction are used directly; no copies are made. Thread safety and
+ * immutability therefore depend on the underlying list and its usage outside of this class.
+ * The boundary list cannot be modified through this class.
+ * @param <P> Point implementation type
+ * @param <S> Hyperplane convex subset implementation type
+ */
+public class BoundaryList<P extends Point<P>, S extends HyperplaneConvexSubset<P>>
+    implements BoundarySource<S> {
+
+    /** List of boundaries. */
+    private final List<S> boundaries;
+
+    /** Construct a new instance containing the given boundaries. The input list is
+     * used directly; no copy is made.
+     * @param boundaries boundary list
+     */
+    public BoundaryList(final List<? extends S> boundaries) {
+        this.boundaries = Collections.unmodifiableList(boundaries);
+    }
+
+    /** Get the boundaries for the instance. The returned list cannot be modified.
+     * @return boundaries for the instance
+     */
+    public List<S> getBoundaries() {
+        return boundaries;
+    }
+
+    /** Get the number of boundaries in the instance. This is exactly
+     * equivalent to {@code boundaryList.getBoundaries().size()} but the
+     * word "size" is avoided here to prevent confusion with geometric
+     * size.
+     * @return number of boundaries in the instance
+     */
+    public int count() {
+        return boundaries.size();
+    }
+
+    /** {@inheritDoc} */
+    @Override
+    public Stream<S> boundaryStream() {
+        return boundaries.stream();
+    }
+
+    /** {@inheritDoc} */
+    @Override
+    public String toString() {
+        final StringBuilder sb = new StringBuilder();
+        sb.append(this.getClass().getSimpleName())
+            // only display the count and not the actual boundaries
+            // since the list could be huge
+            .append("[count= ")
+            .append(count())
+            .append(']');
+
+        return sb.toString();
+    }
+}

commons-geometry-core/src/test/java/org/apache/commons/geometry/core/partitioning/AbstractConvexHyperplaneBoundedRegionTest.java

@@ -646,8 +646,7 @@ public void testToString() {
         final String str = region.toString();
 
         // assert
-        Assertions.assertTrue(str.contains("StubRegion"));
-        Assertions.assertTrue(str.contains("boundaries= "));
+        Assertions.assertEquals("StubRegion[boundaries= []]", str);
     }
 
     private static void checkClassify(final Region<TestPoint2D> region, final RegionLocation loc, final TestPoint2D... pts) {

commons-geometry-core/src/test/java/org/apache/commons/geometry/core/partitioning/BoundaryListTest.java

@@ -0,0 +1,87 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.geometry.core.partitioning;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+import java.util.stream.Collectors;
+
+import org.apache.commons.geometry.core.partitioning.test.TestLineSegment;
+import org.apache.commons.geometry.core.partitioning.test.TestPoint2D;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+
+public class BoundaryListTest {
+
+    @Test
+    public void testBoundaries() {
+        // arrange
+        final List<TestLineSegment> boundaries = new ArrayList<>();
+        boundaries.add(new TestLineSegment(0, 0, 1, 1));
+        boundaries.add(new TestLineSegment(1, 1, 0, 2));
+
+        // act
+        final BoundaryList<TestPoint2D, TestLineSegment> list = new BoundaryList<>(boundaries);
+
+        // assert
+        Assertions.assertNotSame(boundaries, list.getBoundaries());
+        Assertions.assertEquals(boundaries, list.getBoundaries());
+        Assertions.assertEquals(boundaries, list.boundaryStream().collect(Collectors.toList()));
+    }
+
+    @Test
+    public void testGetBoundaries_listCannotBeModified() {
+        // arrange
+        final List<TestLineSegment> boundaries = new ArrayList<>();
+        boundaries.add(new TestLineSegment(0, 0, 1, 1));
+
+        final BoundaryList<TestPoint2D, TestLineSegment> list = new BoundaryList<>(boundaries);
+
+        // act/assert
+        Assertions.assertThrows(UnsupportedOperationException.class, () -> {
+            list.getBoundaries().add(new TestLineSegment(1, 1, 0, 2));
+        });
+    }
+
+    @Test
+    public void testCount() {
+        // act/assert
+        Assertions.assertEquals(0, new BoundaryList<>(Collections.emptyList()).count());
+        Assertions.assertEquals(1, new BoundaryList<>(Arrays.asList(
+                    new TestLineSegment(0, 0, 1, 1)
+                )).count());
+        Assertions.assertEquals(2, new BoundaryList<>(Arrays.asList(
+                new TestLineSegment(0, 0, 1, 1),
+                new TestLineSegment(1, 1, 0, 2)
+            )).count());
+    }
+
+    @Test
+    public void testToString() {
+        // arrange
+        final BoundaryList<TestPoint2D, TestLineSegment> empty = new BoundaryList<>(Collections.emptyList());
+        final BoundaryList<TestPoint2D, TestLineSegment> single = new BoundaryList<>(Arrays.asList(
+                    new TestLineSegment(0, 0, 1, 1)
+                ));
+
+        // act
+        Assertions.assertEquals("BoundaryList[count= 0]", empty.toString());
+        Assertions.assertEquals("BoundaryList[count= 1]", single.toString());
+    }
+}

commons-geometry-euclidean/src/main/java/org/apache/commons/geometry/euclidean/threed/BoundaryList3D.java

@@ -0,0 +1,47 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.geometry.euclidean.threed;
+
+import java.util.List;
+
+import org.apache.commons.geometry.core.partitioning.BoundaryList;
+
+/** {@link BoundarySource3D} implementation that uses boundaries stored in
+ * a list. Lists given during construction are used directly; no copies are made.
+ * Thread safety and immutability therefore depend on the underlying list and its
+ * usage outside of this class. The boundary list cannot be modified through this
+ * class.
+ */
+public class BoundaryList3D extends BoundaryList<Vector3D, PlaneConvexSubset>
+    implements BoundarySource3D {
+
+    /** Construct a new instance with the given list of boundaries. The
+     * argument is used directly; no copy is made.
+     * @param boundaries list of boundaries for the instance
+     */
+    public BoundaryList3D(final List<? extends PlaneConvexSubset> boundaries) {
+        super(boundaries);
+    }
+
+    /** Return this instance.
+     * @return this instance
+     */
+    @Override
+    public BoundaryList3D toList() {
+        return this;
+    }
+}

commons-geometry-euclidean/src/main/java/org/apache/commons/geometry/euclidean/threed/BoundarySource3D.java

@@ -19,6 +19,7 @@
 import java.util.Arrays;
 import java.util.Collection;
 import java.util.List;
+import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
 import org.apache.commons.geometry.core.partitioning.BoundarySource;
@@ -33,6 +34,16 @@
  */
 public interface BoundarySource3D extends BoundarySource<PlaneConvexSubset>, Linecastable3D {
 
+    /** Return a {@link BoundaryList3D} containing the boundaries in this instance.
+     * @return a {@link BoundaryList3D} containing the boundaries in this instance
+     */
+    default BoundaryList3D toList() {
+        final List<PlaneConvexSubset> boundaries = boundaryStream()
+                .collect(Collectors.toList());
+
+        return new BoundaryList3D(boundaries);
+    }
+
     /** Return a BSP tree constructed from the boundaries contained in this instance. This is
      * a convenience method for quickly constructing BSP trees and may produce unbalanced trees
      * with unacceptable performance characteristics when used with large numbers of boundaries.

commons-geometry-euclidean/src/main/java/org/apache/commons/geometry/euclidean/twod/BoundaryList2D.java

@@ -0,0 +1,47 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.geometry.euclidean.twod;
+
+import java.util.List;
+
+import org.apache.commons.geometry.core.partitioning.BoundaryList;
+
+/** {@link BoundarySource2D} implementation that uses boundaries stored in
+ * a list. Lists given during construction are used directly; no copies are made.
+ * Thread safety and immutability therefore depend on the underlying list and its
+ * usage outside of this class. The boundary list cannot be modified through this
+ * class.
+ */
+public class BoundaryList2D extends BoundaryList<Vector2D, LineConvexSubset>
+    implements BoundarySource2D {
+
+    /** Construct a new instance with the given list of boundaries. The
+     * argument is used directly; no copy is made.
+     * @param boundaries list of boundaries for the instance
+     */
+    public BoundaryList2D(final List<? extends LineConvexSubset> boundaries) {
+        super(boundaries);
+    }
+
+    /** Return this instance.
+     * @return this instance
+     */
+    @Override
+    public BoundaryList2D toList() {
+        return this;
+    }
+}

commons-geometry-euclidean/src/main/java/org/apache/commons/geometry/euclidean/twod/BoundarySource2D.java

@@ -19,13 +19,24 @@
 import java.util.Arrays;
 import java.util.Collection;
 import java.util.List;
+import java.util.stream.Collectors;
 
 import org.apache.commons.geometry.core.partitioning.BoundarySource;
 
 /** Extension of the {@link BoundarySource} interface for Euclidean 2D space.
  */
 public interface BoundarySource2D extends BoundarySource<LineConvexSubset>, Linecastable2D {
 
+    /** Return a {@link BoundaryList2D} containing the boundaries in this instance.
+     * @return a {@link BoundaryList2D} containing the boundaries in this instance
+     */
+    default BoundaryList2D toList() {
+        final List<LineConvexSubset> boundaries = boundaryStream()
+                .collect(Collectors.toList());
+
+        return new BoundaryList2D(boundaries);
+    }
+
     /** Return a BSP tree constructed from the boundaries contained in this instance. This is
      * a convenience method for quickly constructing BSP trees and may produce unbalanced trees
      * with unacceptable performance characteristics when used with large numbers of boundaries.