(calcite) branch main updated: [CALCITE-6698] Add Javadoc to PartiallyOrderedSet#getNonChildren and getNonParents to clarify their behavior

[zabetak]

This is an automated email from the ASF dual-hosted git repository.

zabetak pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/calcite.git


The following commit(s) were added to refs/heads/main by this push:
     new b635174180 [CALCITE-6698] Add Javadoc to 
PartiallyOrderedSet#getNonChildren and getNonParents to clarify their behavior
b635174180 is described below

commit b6351741809a5c06cbf7cb5f0e98602b0bd9316f
Author: Stamatis Zampetakis <zabe...@gmail.com>
AuthorDate: Mon Nov 18 16:41:48 2024 +0100

    [CALCITE-6698] Add Javadoc to PartiallyOrderedSet#getNonChildren and 
getNonParents to clarify their behavior
    
    1. Add Javadoc to clarify the results of each method and avoid potential 
misinterpretation of their name.
    2. Add test cases with explicit tests for the aforementioned methods.
    
    Close apache/calcite#4054
---
 .../apache/calcite/util/PartiallyOrderedSet.java   | 16 +++++++++++++
 .../calcite/util/PartiallyOrderedSetTest.java      | 27 ++++++++++++++++++++++
 2 files changed, 43 insertions(+)

diff --git 
a/core/src/main/java/org/apache/calcite/util/PartiallyOrderedSet.java 
b/core/src/main/java/org/apache/calcite/util/PartiallyOrderedSet.java
index 94df762bc8..0a307e1e41 100644
--- a/core/src/main/java/org/apache/calcite/util/PartiallyOrderedSet.java
+++ b/core/src/main/java/org/apache/calcite/util/PartiallyOrderedSet.java
@@ -90,6 +90,10 @@ public class PartiallyOrderedSet<E> extends AbstractSet<E> {
    * in the set.
    */
   private final Node<E> topNode;
+  /**
+   * Synthetic node to hold all nodes that have no children. It does not appear
+   * in the set.
+   */
   private final Node<E> bottomNode;
 
   /**
@@ -681,10 +685,22 @@ public class PartiallyOrderedSet<E> extends 
AbstractSet<E> {
     }
   }
 
+  /**
+   * Returns all elements in the set that are not children. These elements 
appear at the top of
+   * the poset, and they usually referred to as roots/maximal elements of the 
poset.
+   *
+   * @return a list of elements that are not children.
+   */
   public List<E> getNonChildren() {
     return strip(topNode.childList);
   }
 
+  /**
+   * Returns all elements in the set that are not parents. These elements 
appear at the bottom of
+   * the poset, and they usually referred to as leafs/minimal elements of the 
poset.
+   *
+   * @return a list of elements that are not parents.
+   */
   public List<E> getNonParents() {
     return strip(bottomNode.parentList);
   }
diff --git 
a/core/src/test/java/org/apache/calcite/util/PartiallyOrderedSetTest.java 
b/core/src/test/java/org/apache/calcite/util/PartiallyOrderedSetTest.java
index 05a48fde57..45126b6d33 100644
--- a/core/src/test/java/org/apache/calcite/util/PartiallyOrderedSetTest.java
+++ b/core/src/test/java/org/apache/calcite/util/PartiallyOrderedSetTest.java
@@ -20,6 +20,7 @@ import org.junit.jupiter.api.Test;
 
 import java.util.AbstractList;
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.Collection;
 import java.util.LinkedHashSet;
 import java.util.List;
@@ -180,6 +181,30 @@ class PartiallyOrderedSetTest {
     assertEqualsList("['ab', 'abcd']", poset.getAncestors("'a'"));
   }
 
+  @Test void testGetNonParentsOnLteIntPosetReturnsMinValue() {
+    PartiallyOrderedSet<Integer> poset =
+        new PartiallyOrderedSet<>((i, j) -> i <= j, Arrays.asList(20, 30, 40));
+    assertThat(poset.getNonParents(), hasToString("[20]"));
+  }
+
+  @Test void testGetNonChildrenOnLteIntPosetReturnsMaxValue() {
+    PartiallyOrderedSet<Integer> poset =
+        new PartiallyOrderedSet<>((i, j) -> i <= j, Arrays.asList(20, 30, 40));
+    assertThat(poset.getNonChildren(), hasToString("[40]"));
+  }
+
+  @Test void testGetNonParentsOnGteIntPosetReturnsMaxValue() {
+    PartiallyOrderedSet<Integer> poset =
+        new PartiallyOrderedSet<>((i, j) -> i >= j, Arrays.asList(20, 30, 40));
+    assertThat(poset.getNonParents(), hasToString("[40]"));
+  }
+
+  @Test void testGetNonChildrenOnGteIntPosetReturnsMinValue() {
+    PartiallyOrderedSet<Integer> poset =
+        new PartiallyOrderedSet<>((i, j) -> i >= j, Arrays.asList(20, 30, 40));
+    assertThat(poset.getNonChildren(), hasToString("[20]"));
+  }
+
   @Test void testPosetTricky() {
     final PartiallyOrderedSet<String> poset =
         new PartiallyOrderedSet<>(STRING_SUBSET_ORDERING);
@@ -195,6 +220,8 @@ class PartiallyOrderedSetTest {
     printValidate(poset);
     poset.add("'ab'");
     printValidate(poset);
+    assertThat(poset.getNonChildren(), hasToString("['ac', 'ab']"));
+    assertThat(poset.getNonParents(), hasToString("['a', 'b']"));
   }
 
   @Test void testPosetBits() {