fix: document and update WritableChunk and CompactKernel

engine/chunk/src/main/java/io/deephaven/chunk/WritableBooleanChunk.java

@@ -172,8 +172,20 @@ public final void sort() {
         sort(0, size);
     }
 
-    // region sort
-    // endregion sort
+    @Override
+    public final void sort(int start, int length) {
+        WritableChunkUtils.sort(data, offset + start, offset + start + length);
+    }
+
+    @Override
+    public final void sortUnsafe() {
+        sortUnsafe(0, size);
+    }
+
+    @Override
+    public final void sortUnsafe(int start, int length) {
+        WritableChunkUtils.sortUnsafe(data, offset + start, offset + start + length);
+    }
 
     @Override
     public void close() {}

engine/chunk/src/main/java/io/deephaven/chunk/WritableByteChunk.java

@@ -209,15 +209,20 @@ public final void sort() {
         sort(0, size);
     }
 
-    // region sort
     @Override
     public final void sort(int start, int length) {
-        Arrays.sort(data, offset + start, offset + start + length);
+        WritableChunkUtils.sort(data, offset + start, offset + start + length);
+    }
 
-        // region SortFixup
-        // endregion SortFixup
+    @Override
+    public final void sortUnsafe() {
+        sortUnsafe(0, size);
+    }
+
+    @Override
+    public final void sortUnsafe(int start, int length) {
+        WritableChunkUtils.sortUnsafe(data, offset + start, offset + start + length);
     }
-    // endregion sort
 
     @Override
     public void close() {}

engine/chunk/src/main/java/io/deephaven/chunk/WritableCharChunk.java

@@ -205,39 +205,20 @@ public final void sort() {
         sort(0, size);
     }
 
-    // region sort
     @Override
     public final void sort(int start, int length) {
-        Arrays.sort(data, offset + start, offset + start + length);
-
-        // region SortFixup
-        if (length <= 1) {
-            return;
-        }
-
-        int foundLeft = Arrays.binarySearch(data, start, start + length, NULL_CHAR);
-        if (foundLeft < 0) {
-            return;
-        }
-
-        int foundRight = foundLeft;
-        while (foundLeft > start && data[foundLeft - 1] == NULL_CHAR) {
-            foundLeft--;
-        }
+        WritableChunkUtils.sort(data, offset + start, offset + start + length);
+    }
 
-        // If the nulls are already the leftmost thing, we are done.
-        if (foundLeft > 0) {
-            while (foundRight < start + length - 1 && data[foundRight + 1] == NULL_CHAR) {
-                foundRight++;
-            }
+    @Override
+    public final void sortUnsafe() {
+        sortUnsafe(0, size);
+    }
 
-            final int nullCount = foundRight - foundLeft + 1;
-            System.arraycopy(data, start, data, start + nullCount, foundLeft - start);
-            Arrays.fill(data, start, start + nullCount, NULL_CHAR);
-        }
-        // endregion SortFixup
+    @Override
+    public final void sortUnsafe(int start, int length) {
+        WritableChunkUtils.sortUnsafe(data, offset + start, offset + start + length);
     }
-    // endregion sort
 
     @Override
     public void close() {}

engine/chunk/src/main/java/io/deephaven/chunk/WritableChunk.java

@@ -92,20 +92,34 @@ default int capacity() {
     int internalCapacity(long password);
 
     /**
-     * Sort this chunk in-place using Java's primitive defined ordering.
-     * <p>
-     * Of note is that nulls or NaNs are not sorted according to Deephaven ordering rules.
+     * Sort this chunk using Deephaven-defined ordering; that is, nulls first (and NaNs last for floating-point types).
+     * The one exception is -0.0 and 0.0 for floating-point types; where the Deephaven-defined ordering treats these as
+     * equal, this sort will treat {@code -0.0 < 0.0}.
      */
     void sort();
 
     /**
-     * Sort this chunk in-place using Java's primitive defined ordering.
-     * <p>
-     * Of note is that nulls or NaNs are not sorted according to Deephaven ordering rules.
+     * Sort this chunk's subset using Deephaven-defined ordering; that is, nulls first (and NaNs last for floating-point
+     * types). The one exception is -0.0 and 0.0 for floating-point types; where the Deephaven-defined ordering treats
+     * these as equal, this sort will treat {@code -0.0 < 0.0}.
      */
-    default void sort(int start, int length) {
-        throw new UnsupportedOperationException();
-    }
+    void sort(int start, int length);
+
+    /**
+     * Sort this chunk using Arrays-defined ordering. This is equivalent to Deephaven-defined ordering (with a
+     * floating-point exception for {@code -0.0 < 0.0}) when ignoring nulls. Callers should only use this when they know
+     * the array does not contain nulls, or when the caller plans to explicitly exclude nulls after sorting, or when the
+     * caller does not actually care about the sorting order (for example, is using sort as a means of grouping data).
+     */
+    void sortUnsafe();
+
+    /**
+     * Sort this chunk's subset using Arrays-defined ordering. This is equivalent to Deephaven-defined ordering (with a
+     * floating-point exception for {@code -0.0 < 0.0}) when ignoring nulls. Callers should only use this when they know
+     * the array does not contain nulls, or when the caller plans to explicitly exclude nulls after sorting, or when the
+     * caller does not actually care about the sorting order (for example, is using sort as a means of grouping data).
+     */
+    void sortUnsafe(int start, int length);
 
     default WritableByteChunk<ATTR> asWritableByteChunk() {
         return (WritableByteChunk<ATTR>) this;