Refactor CompactSegmentTree and add dedicated tests (williamfiset#1274)

Apply SKILL.md conventions: fix package/header order, add detailed
file-level docs explaining bottom-up array layout, replace FQN with
import, make UNIQUE static final, add Javadoc on all public methods,
add educational inline comments, clean up main(). Add 11 new tests
covering sum queries, point updates, negative values, edge cases.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: williamfiset

src/main/java/com/williamfiset/algorithms/datastructures/segmenttree/CompactSegmentTree.java

@@ -1,85 +1,123 @@
+package com.williamfiset.algorithms.datastructures.segmenttree;
+
+import java.util.Arrays;
+
 /**
- * A compact array based segment tree implementation. This segment tree supports point updates and
- * range queries.
+ * Compact Array-Based Segment Tree
+ *
+ * A space-efficient segment tree stored in a flat array of size 2*n (no
+ * recursion, no pointers). Supports point updates and range queries using
+ * any associative combine function (sum, min, max, product, GCD, etc.).
+ *
+ * The tree is stored bottom-up: leaves occupy indices [n, 2n) and internal
+ * nodes occupy [1, n). Index 0 is unused. Each internal node i is the
+ * combination of its children at 2i and 2i+1.
+ *
+ * Use cases:
+ *   - Range sum / min / max queries with point updates
+ *   - Competitive programming (very short, cache-friendly implementation)
+ *
+ * Time:  O(n) construction, O(log(n)) per query and update
+ * Space: O(n)
  *
  * @author Al.Cash & William Fiset, william.alexandre.fiset@gmail.com
  */
-package com.williamfiset.algorithms.datastructures.segmenttree;
-
 public class CompactSegmentTree {
 
   private int N;
 
-  // Let UNIQUE be a value which does NOT
-  // and will not appear in the segment tree
-  private long UNIQUE = 8123572096793136074L;
-
-  // Segment tree values
-  private long[] tree;
+  // Flat array storing the segment tree. Leaves are at indices [N, 2N),
+  // internal nodes at [1, N). Index 0 is unused. Uninitialized slots
+  // are null, which acts as the identity element for the combine function.
+  private Long[] tree;
 
+  /**
+   * Creates an empty segment tree of the given size, with all slots
+   * initialized to null.
+   *
+   * @param size the number of elements (leaves) in the segment tree
+   */
   public CompactSegmentTree(int size) {
-    tree = new long[2 * (N = size)];
-    java.util.Arrays.fill(tree, UNIQUE);
+    tree = new Long[2 * (N = size)];
   }
 
+  /**
+   * Creates a segment tree from an array of values.
+   *
+   * @param values the initial leaf values
+   */
   public CompactSegmentTree(long[] values) {
     this(values.length);
-    // TODO(william): Implement smarter construction.
     for (int i = 0; i < N; i++) modify(i, values[i]);
   }
 
-  // This is the segment tree function we are using for queries.
-  // The function must be an associative function, meaning
-  // the following property must hold: f(f(a,b),c) = f(a,f(b,c)).
-  // Common associative functions used with segment trees
-  // include: min, max, sum, product, GCD, and etc...
-  private long function(long a, long b) {
-    if (a == UNIQUE) return b;
-    else if (b == UNIQUE) return a;
-
-    return a + b; // sum over a range
-    // return (a > b) ? a : b; // maximum value over a range
-    // return (a < b) ? a : b; // minimum value over a range
-    // return a * b; // product over a range (watch out for overflow!)
+  /**
+   * The associative combine function used for queries. This function must
+   * satisfy f(f(a,b), c) = f(a, f(b,c)) for correct segment tree behavior.
+   * Null acts as the identity element: f(null, x) = f(x, null) = x.
+   *
+   * Change this to customize the query type:
+   *   return a + b;                 // sum over a range
+   *   return (a > b) ? a : b;      // maximum over a range
+   *   return (a < b) ? a : b;      // minimum over a range
+   *   return a * b;                // product over a range (watch for overflow!)
+   */
+  private Long function(Long a, Long b) {
+    if (a == null) return b;
+    if (b == null) return a;
+    return a + b;
   }
 
-  // Adjust point i by a value, O(log(n))
+  /**
+   * Updates the value at index i by combining it with the given value
+   * using the combine function, then propagates changes up to the root.
+   *
+   * @param i     the leaf index to update (0-based)
+   * @param value the value to combine at position i
+   *
+   * Time: O(log(n))
+   */
   public void modify(int i, long value) {
+    // Update the leaf node
     tree[i + N] = function(tree[i + N], value);
+    // Propagate up: recompute each ancestor from its two children
     for (i += N; i > 1; i >>= 1) {
       tree[i >> 1] = function(tree[i], tree[i ^ 1]);
     }
   }
 
-  // Query interval [l, r), O(log(n))
+  /**
+   * Queries the aggregate value over the half-open interval [l, r).
+   *
+   * Works by starting at the leaves and moving up. At each level, if the
+   * left boundary is a right child, include it and move right. If the right
+   * boundary is a right child, move left and include it.
+   *
+   * @param l left endpoint (inclusive, 0-based)
+   * @param r right endpoint (exclusive, 0-based)
+   * @return the combined result over [l, r)
+   * @throws IllegalStateException if the query range is empty
+   *
+   * Time: O(log(n))
+   */
   public long query(int l, int r) {
-    long res = UNIQUE;
+    Long res = null;
     for (l += N, r += N; l < r; l >>= 1, r >>= 1) {
+      // If l is a right child, include it and move to next subtree
       if ((l & 1) != 0) res = function(res, tree[l++]);
+      // If r is a right child, include its left sibling
       if ((r & 1) != 0) res = function(res, tree[--r]);
     }
-    if (res == UNIQUE) {
-      throw new IllegalStateException("UNIQUE should not be the return value.");
+    if (res == null) {
+      throw new IllegalStateException("Empty query range.");
     }
     return res;
   }
 
   public static void main(String[] args) {
-    // exmaple1();
-    example2();
-  }
-
-  private static void example1() {
-    long[] values = new long[] {3, 0, 8, 9, 8, 2, 5, 3, 7, 1};
-    CompactSegmentTree st = new CompactSegmentTree(values);
-    System.out.println(java.util.Arrays.toString(st.tree));
-  }
-
-  private static void example2() {
     long[] values = new long[] {1, 1, 1, 1, 1, 1};
     CompactSegmentTree st = new CompactSegmentTree(values);
-    System.out.println(java.util.Arrays.toString(st.tree));
-
+    System.out.println(Arrays.toString(st.tree));
     System.out.println(st.query(0, 6)); // 6
     System.out.println(st.query(1, 5)); // 4
     System.out.println(st.query(0, 2)); // 2

src/test/java/com/williamfiset/algorithms/datastructures/segmenttree/BUILD

@@ -108,5 +108,16 @@ java_test(
     deps = TEST_DEPS,
 )
 
+# bazel test //src/test/java/com/williamfiset/algorithms/datastructures/segmenttree:CompactSegmentTreeTest
+java_test(
+    name = "CompactSegmentTreeTest",
+    srcs = ["CompactSegmentTreeTest.java"],
+    main_class = "org.junit.platform.console.ConsoleLauncher",
+    use_testrunner = False,
+    args = ["--select-class=com.williamfiset.algorithms.datastructures.segmenttree.CompactSegmentTreeTest"],
+    runtime_deps = JUNIT5_RUNTIME_DEPS,
+    deps = TEST_DEPS,
+)
+
 # Run all tests
 # bazel test //src/test/java/com/williamfiset/algorithms/datastructures/segmenttree:all

src/test/java/com/williamfiset/algorithms/datastructures/segmenttree/CompactSegmentTreeTest.java

@@ -0,0 +1,124 @@
+package com.williamfiset.algorithms.datastructures.segmenttree;
+
+import static com.google.common.truth.Truth.assertThat;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+import org.junit.jupiter.api.Test;
+
+public class CompactSegmentTreeTest {
+
+  @Test
+  public void testSumQueryBasic() {
+    long[] values = {1, 2, 3, 4, 5};
+    CompactSegmentTree st = new CompactSegmentTree(values);
+    assertThat(st.query(0, 5)).isEqualTo(15);
+    assertThat(st.query(0, 3)).isEqualTo(6);
+    assertThat(st.query(2, 5)).isEqualTo(12);
+  }
+
+  @Test
+  public void testSingleElement() {
+    long[] values = {42};
+    CompactSegmentTree st = new CompactSegmentTree(values);
+    assertThat(st.query(0, 1)).isEqualTo(42);
+  }
+
+  @Test
+  public void testTwoElements() {
+    long[] values = {3, 7};
+    CompactSegmentTree st = new CompactSegmentTree(values);
+    assertThat(st.query(0, 2)).isEqualTo(10);
+    assertThat(st.query(0, 1)).isEqualTo(3);
+    assertThat(st.query(1, 2)).isEqualTo(7);
+  }
+
+  @Test
+  public void testPointUpdate() {
+    long[] values = {1, 1, 1, 1, 1, 1};
+    CompactSegmentTree st = new CompactSegmentTree(values);
+    assertThat(st.query(0, 6)).isEqualTo(6);
+
+    // modify combines with existing value (sum), so adding 5 to index 2
+    // changes value from 1 to 6
+    st.modify(2, 5);
+    assertThat(st.query(0, 6)).isEqualTo(11);
+    assertThat(st.query(2, 3)).isEqualTo(6);
+  }
+
+  @Test
+  public void testQuerySingleElementInRange() {
+    long[] values = {10, 20, 30, 40, 50};
+    CompactSegmentTree st = new CompactSegmentTree(values);
+    for (int i = 0; i < values.length; i++) {
+      assertThat(st.query(i, i + 1)).isEqualTo(values[i]);
+    }
+  }
+
+  @Test
+  public void testAllZeros() {
+    long[] values = {0, 0, 0, 0};
+    CompactSegmentTree st = new CompactSegmentTree(values);
+    assertThat(st.query(0, 4)).isEqualTo(0);
+    assertThat(st.query(1, 3)).isEqualTo(0);
+  }
+
+  @Test
+  public void testNegativeValues() {
+    long[] values = {-5, 3, -2, 7, -1};
+    CompactSegmentTree st = new CompactSegmentTree(values);
+    assertThat(st.query(0, 5)).isEqualTo(2);
+    assertThat(st.query(0, 2)).isEqualTo(-2);
+    assertThat(st.query(3, 5)).isEqualTo(6);
+  }
+
+  @Test
+  public void testMultipleUpdates() {
+    long[] values = {1, 2, 3};
+    CompactSegmentTree st = new CompactSegmentTree(values);
+    assertThat(st.query(0, 3)).isEqualTo(6);
+
+    st.modify(0, 10);  // 1 + 10 = 11
+    st.modify(1, 20);  // 2 + 20 = 22
+    st.modify(2, 30);  // 3 + 30 = 33
+    assertThat(st.query(0, 3)).isEqualTo(66);
+  }
+
+  @Test
+  public void testSizeConstructor() {
+    // Empty tree created with size constructor, then populated with modify
+    CompactSegmentTree st = new CompactSegmentTree(4);
+    st.modify(0, 5);
+    st.modify(1, 10);
+    st.modify(2, 15);
+    st.modify(3, 20);
+    assertThat(st.query(0, 4)).isEqualTo(50);
+    assertThat(st.query(1, 3)).isEqualTo(25);
+  }
+
+  // Query with equal l and r is an empty range — should throw since
+  // the result would be the UNIQUE sentinel value.
+  @Test
+  public void testEmptyRangeQueryThrows() {
+    long[] values = {1, 2, 3};
+    CompactSegmentTree st = new CompactSegmentTree(values);
+    assertThrows(IllegalStateException.class, () -> st.query(1, 1));
+  }
+
+  @Test
+  public void testLargerArray() {
+    int n = 100;
+    long[] values = new long[n];
+    long total = 0;
+    for (int i = 0; i < n; i++) {
+      values[i] = i + 1;
+      total += values[i];
+    }
+    CompactSegmentTree st = new CompactSegmentTree(values);
+    assertThat(st.query(0, n)).isEqualTo(total);
+
+    // Query first half: sum of 1..50 = 1275
+    assertThat(st.query(0, 50)).isEqualTo(1275);
+    // Query second half: sum of 51..100 = 3775
+    assertThat(st.query(50, 100)).isEqualTo(3775);
+  }
+}