comments + Face.Status.EXTERIOR => Status.BOUNDARY

Author: pierre-b-geom

src/hgeom/hmesh/core/CycleGraphToHFaces.java

@@ -137,7 +137,7 @@ private List<HFace> cyclesToFaces(List<HEdge> cycles) {
 				}
 
 				else {
-					face = elementFactory.createFace(cycleEdge, Status.EXTERIOR,
+					face = elementFactory.createFace(cycleEdge, Status.BOUNDARY,
 							false);
 
 					faceIndices.set(face, -1);

src/hgeom/hmesh/core/HEdgeImpl.java

@@ -1,5 +1,6 @@
 package hgeom.hmesh.core;
 
+import java.util.Objects;
 import java.util.Optional;
 import java.util.function.Predicate;
 import java.util.function.UnaryOperator;
@@ -167,6 +168,7 @@ public final HEdge next() {
 
 	@Override
 	public final Optional<HEdge> next(Predicate<? super HEdge> predicate) {
+		Objects.requireNonNull(predicate);
 		requireNotDiscarded();
 		return Loops.findFirst(this, HEdge::next, predicate);
 	}

src/hgeom/hmesh/core/HFaceImpl.java

@@ -31,6 +31,7 @@ public InteriorHFaceImpl(int id, HEdge edge) {
 
 		@Override
 		public Status status() {
+			requireNotDiscarded();
 			return Status.INTERIOR;
 		}
 	}
@@ -50,7 +51,8 @@ public ExteriorHFaceImpl(int id, HEdge edge) {
 
 		@Override
 		public Status status() {
-			return Status.EXTERIOR;
+			requireNotDiscarded();
+			return Status.BOUNDARY;
 		}
 	}
 
@@ -87,7 +89,7 @@ public static HFace create(int id, HEdge edge, Status status,
 			return new InteriorHFaceImpl(id, edge);
 		}
 
-		if (status == Status.EXTERIOR) {
+		if (status == Status.BOUNDARY) {
 			return new ExteriorHFaceImpl(id, edge);
 		}
 
@@ -122,6 +124,7 @@ public static void setEdge(HFace face, HEdge edge) {
 
 	@Override
 	public Status status() {
+		requireNotDiscarded();
 		return Status.UNKNOWN;
 	}
 

src/hgeom/hmesh/elements/HEdge.java

@@ -14,12 +14,14 @@ public interface HEdge extends HElement {
 
 	/**
 	 * @return the face to which this half-edge belongs
+	 * @throws IllegalStateException if this half-edge is discarded
 	 */
 	HFace face();
 
 	/**
 	 * @return the vertex at the head of this edge (the vertex to which this
 	 *         half-edge points)
+	 * @throws IllegalStateException if this half-edge is discarded
 	 */
 	HVertex head();
 
@@ -33,57 +35,65 @@ default HVertex tail() {
 	/**
 	 * @return the half-edge following this half-edge in the half-edge cycle
 	 *         this half-edge is part of
+	 * @throws IllegalStateException if this half-edge is discarded
 	 */
 	HEdge next();
 
 	/**
 	 * Starts from this half-edge and iterate over the cycle this edge belongs
-	 * to by successive calls to {@link HEdge#next()} until a half-edge is found
-	 * matching the specified predicate. If no half-edge is found, stops when
-	 * the iteration leads back to this edge
+	 * to until a half-edge is found matching the specified predicate. If no
+	 * half-edge is found, stops when the iteration leads back to this edge
 	 * <p>
 	 * Equivalent to, but faster than
 	 * <code>this.cycle().filter(predicate).findFirst()</code>
 	 *
 	 * @param predicate a predicate used to test every encountered half-edge
 	 *                  along the cycle
-	 * @return an {@link Optional} on a half-edge found matching the predicate
-	 *         or {@link Optional#empty()} if the cycle was completly parsed and
-	 *         no half-edge was found
+	 * @return an {@link Optional} on the first half-edge found matching the
+	 *         predicate or {@link Optional#empty()} if the cycle was completly
+	 *         parsed and no half-edge was found
+	 * @throws IllegalStateException if this half-edge is discarded
+	 * @throws NullPointerException  if null argument
+	 * @see HEdge#cycle()
 	 */
 	Optional<HEdge> next(Predicate<? super HEdge> predicate);
 
 	/**
 	 * @return the previous half-edge on the cycle this half-edge belongs to
+	 * @throws IllegalStateException if this half-edge is discarded
 	 */
 	HEdge previous();
 
 	/**
 	 * @return the opposite (or sibling) half-edge
+	 * @throws IllegalStateException if this half-edge is discarded
 	 */
 	HEdge opposite();
 
 	/**
-	 * @return a sequence over all the elements of the cycle this half-edge
-	 *         belongs to (along the border of a face). The first element of the
-	 *         sequence is this half-Edge, the 2nd element is the
-	 *         {@link HEdge#next() next} half-edge and so on
+	 * @return a ordered circular sequence over all the elements of the cycle
+	 *         this half-edge belongs to (along the boundary of a face). The
+	 *         first element of the sequence is this half-Edge, the 2nd element
+	 *         is the {@link HEdge#next() next} half-edge and so on
+	 * @throws IllegalStateException if this half-edge is discarded
 	 */
 	Sequence<HEdge> cycle();
 
 	/**
-	 * @return a sequence over all the half-edges whose tail are this edge's
-	 *         head. The {@link HEdge#opposite() opposite} of this half-edge is
-	 *         included in the sequence
+	 * @return a ordered sequence over all the half-edges whose tail are this
+	 *         edge's head. The {@link HEdge#opposite() opposite} of this
+	 *         half-edge is included in the sequence
+	 * @throws IllegalStateException if this half-edge is discarded
 	 */
 	default Sequence<HEdge> outgoingEdges() {
 		return head().outgoingEdges();
 	}
 
 	/**
-	 * @return a sequence over all the half-edges whose head are this edge's
-	 *         tail. The {@link HEdge#opposite() opposite} of this half-edge is
-	 *         included in the sequence
+	 * @return a ordered sequence over all the half-edges whose head are this
+	 *         edge's tail. The {@link HEdge#opposite() opposite} of this
+	 *         half-edge is included in the sequence
+	 * @throws IllegalStateException if this half-edge is discarded
 	 */
 	default Sequence<HEdge> incomingEdges() {
 		return tail().incomingEdges();

src/hgeom/hmesh/elements/HFace.java

@@ -20,42 +20,47 @@ public enum Status {
 	INTERIOR,
 
 	/**
-	 * The face is an external border of the {@link HMesh mesh} it is part of.
-	 * An external border is a face that surrounds the {@link HMesh mesh} (an
-	 * outer border) or a face that surrounds a hole within the {@link HMesh
-	 * mesh} (an inner border)
+	 * The face is a boundary of the {@link HMesh mesh} it is part of. A
+	 * boundary is a face that surrounds the {@link HMesh mesh} (an outer
+	 * border) or a face that surrounds a hole within the {@link HMesh mesh} (an
+	 * inner border)
 	 */
-	EXTERIOR,
+	BOUNDARY,
 
 	/**
 	 * Unknown status. The face could be either inside or on the border of the
-	 * {@link HMesh mesh} it is part of. when a {@link HMesh mesh} is built from
+	 * {@link HMesh mesh} it is part of. When a {@link HMesh mesh} is built from
 	 * a set of edges, all its faces have an unknown status
 	 */
 	UNKNOWN
 	}
 
 	/**
-	 * @return whether this face is a primary or a complementary face
+	 * @return the {@link Status status} of this face
+	 * @throws IllegalStateException if this face is discarded
 	 */
 	Status status();
 
 	/**
 	 * @return one of the half-edges located on the border of this face
+	 * @throws IllegalStateException if this face is discarded
 	 */
 	HEdge edge();
 
 	/**
-	 * @return a ordered sequence over the half-edges located on the border of
-	 *         this face. Half-edges are ordered in the sequence so that a
-	 *         half-edge is the {@link HEdge#next} of its preceeding half-edge
+	 * @return a ordered circular sequence over the half-edges located along the
+	 *         border of this face. Half-edges are ordered in the sequence so
+	 *         that a half-edge is the {@link HEdge#next} of its preceeding
+	 *         half-edge
+	 * @throws IllegalStateException if this face is discarded
 	 */
 	Sequence<HEdge> edges();
 
 	/**
-	 * @return a ordered sequence over the vertices located on the border of
-	 *         this face. Vertices are ordered so that 2 consecutive vertices in
-	 *         the sequence are neighbors
+	 * @return a ordered circular sequence over the vertices located along the
+	 *         border of this face. Vertices are ordered so that 2 consecutive
+	 *         vertices in the sequence are neighbors
+	 * @throws IllegalStateException if this face is discarded
 	 */
 	Sequence<HVertex> vertices();
 
@@ -71,9 +76,9 @@ public enum Status {
 	boolean isNeighborOf(HFace other);
 
 	/**
-	 * Returns a sequence over the neighbors of this face. The neighbors are the
-	 * faces in contact with this face via a shared border conisiting of at
-	 * least one pair of twin half-edges
+	 * Returns a orderd circular sequence over the neighbors of this face. The
+	 * neighbors are the faces in contact with this face via a shared border
+	 * consisting of at least one pair of twin half-edges
 	 * <p>
 	 * In the particular case of a face being in contact with this face via two
 	 * (or more) distinct borders, the neighbor face will appear twice (or more)

src/hgeom/hmesh/elements/HMesh.java

@@ -16,17 +16,17 @@
 public interface HMesh {
 
 	/**
-	 * @return a sequential stream of this mesh's faces
+	 * @return a sequential stream over this mesh's faces
 	 */
 	Stream<HFace> faces();
 
 	/**
-	 * @return a sequential stream of this mesh's edges
+	 * @return a sequential stream over this mesh's edges
 	 */
 	Stream<HEdge> edges();
 
 	/**
-	 * @return a sequential stream of this mesh's vertices
+	 * @return a sequential stream over this mesh's vertices
 	 */
 	Stream<HVertex> vertices();
 
@@ -46,8 +46,8 @@ static Optional<HEdge> edge(HVertex tail, HVertex head) {
 	 * <p>
 	 * The split:
 	 * <p>
-	 * 1/ creates a pair of twin half-edges joining 2 vertices located o the
-	 * border of the face and dividing the specified face into 2 zones
+	 * 1/ creates a pair of twin half-edges joining 2 vertices located on the
+	 * boundary of the face and dividing the face into 2 zones
 	 * <p>
 	 * 2/ makes the face become one of the 2 zones
 	 * <p>
@@ -95,7 +95,7 @@ static Optional<HEdge> edge(HVertex tail, HVertex head) {
 	 *    v1 <-------------------------------------> v2<p>
 	 * <p>
 	 * After:<p>
-	 * 1 new vertex v, 4 half-edges: he[v1 -> v], heopp[v -> v1]<p>
+	 * 1 new vertex v,<p> 4 half-edges: he[v1 -> v], heopp[v -> v1]
 	 * he2[v2 -> v], h2opp[v -> v2]<p>
 	 * <p>
 	 *    v1 <----------------> v <----------------> v2<p>
@@ -113,13 +113,14 @@ static Optional<HEdge> edge(HVertex tail, HVertex head) {
 	/**
 	 * Collapse a half-edge (and its opposite). Equivalent to "merge" the head
 	 * and the tail of the half-edge. After the collapse, the edge and its
-	 * opposite will be removed from this mesh. The head will be removed as well
-	 * and its incoming and outgoing half-edges will be reconnected to the tail
+	 * opposite will be removed from this mesh and discarded. The head will be
+	 * removed as well and its incoming and outgoing half-edges will be
+	 * reconnected to the tail
 	 *
 	 * @param edge the edge to collapse
 	 * @return {@code true} if successfull collapse ; {@code false} otherwise.
 	 *         The collapse will not take place if the specified edge or its
-	 *         opposite is part of a cycle / face containing only 3 elements.
+	 *         opposite is part of a half-edge cycle containing only 3 elements.
 	 *         Collapse would otherwise result in degenerate faces containing
 	 *         only 2 half-edges
 	 * @throws IllegalStateException if the given half-edge is discarded
@@ -138,12 +139,12 @@ static Optional<HEdge> edge(HVertex tail, HVertex head) {
 	 * <p>
 	 * <code>
 	 * Before:<p>
-	 * 3 vertices, 4 half-edges: h1[v1 -> v], h1opp[v -> v1], h2[v2 -> v], h2opp[v -> v1]<p>
+	 * 3 vertices: v1, v, v2,<p>4 half-edges: h1[v1 -> v], h1opp[v -> v1], h2[v2 -> v], h2opp[v -> v1]<p>
 	 * <p>
 	 *    v1 <----------------> v <----------------> v2<p>
 	 * <p>
 	 * After:<p>
-	 * 2 vertices, 2 half-edges with theirs heads changed: h1[v1 -> v2], h2[v2 -> v1]<p>
+	 * 2 vertices: v1, v2,<p>2 half-edges with theirs heads changed: h1[v1 -> v2], h2[v2 -> v1]<p>
 	 * <p>
 	 *    v1 <-------------------------------------> v2<p>
 	 * <p>

src/hgeom/hmesh/elements/HVertex.java

@@ -11,6 +11,7 @@ public interface HVertex extends HElement {
 
 	/**
 	 * @return one of the edges pointing at this vertex
+	 * @throws IllegalStateException if this vertex is discarded
 	 */
 	HEdge edge();
 
@@ -19,6 +20,7 @@ public interface HVertex extends HElement {
 	 * pointing at this vertex.
 	 *
 	 * @return the degree of this vertex. Always >= 2
+	 * @throws IllegalStateException if this vertex is discarded
 	 */
 	int degree();
 
@@ -28,7 +30,9 @@ public interface HVertex extends HElement {
 	 *
 	 * @param other
 	 * @return {@code true} if yhis vertex and the specified one are neighbors
-	 * @throws NullPointerException if argument is {@code null}
+	 * @throws IllegalStateException if this half-edge or the specified one is
+	 *                               discarded
+	 * @throws NullPointerException  if argument is {@code null}
 	 * @see HVertex#neighbors()
 	 */
 	boolean isNeighborOf(HVertex other);
@@ -38,21 +42,20 @@ public interface HVertex extends HElement {
 	 * vertex connected to this vertex by a pair of twin half-edges
 	 *
 	 * @return
+	 * @throws IllegalStateException if this vertex is discarded
 	 * @see HVertex#isNeighborOf(HVertex)
 	 */
 	Sequence<HVertex> neighbors();
 
 	/**
-	 * Returns a sequence over the half-edges pointing at this vertex
-	 *
-	 * @return
+	 * @return an ordered sequence over the half-edges pointing at this vertex
+	 * @throws IllegalStateException if this vertex is discarded
 	 */
 	Sequence<HEdge> incomingEdges();
 
 	/**
-	 * Returns a sequence over the half-edges whose tail is this vertex
-	 *
-	 * @return
+	 * @return an ordered sequence over the half-edges whose tail is this vertex
+	 * @throws IllegalStateException if this vertex is discarded
 	 */
 	Sequence<HEdge> outgoingEdges();
 }