The MultiDimension tools was extended with a few helper methods. The API was unified a bit.

h2/src/docsrc/html/changelog.html

@@ -18,7 +18,9 @@ Change Log
 <h1>Change Log</h1>
 
 <h2>Next Version (unreleased)</h2>
-<ul><li>ODBC: additional connection settings can now be added to the database name. 
+<ul><li>The MultiDimension tools was extended with a few helper methods.
+    The API was unified a bit.
+</li><li>ODBC: additional connection settings can now be added to the database name. 
     Example: ~/test;cipher=xtea. Therefore, encrypted databases are supported.
 </li><li>Local temporary tables can now be created without having to commit a transaction
     using CREATE LOCAL TEMPORARY TABLE TEMP(ID INT PRIMARY KEY) TRANSACTIONAL. 

h2/src/main/org/h2/tools/MultiDimension.java

@@ -37,65 +37,107 @@ public class MultiDimension implements Comparator<long[]> {
         return INSTANCE;
     }
 
+    /**
+     * Normalize a value so that it is between the minimum and maximum value for
+     * the given number of dimensions.
+     *
+     * @param dimensions the number of dimensions
+     * @param value the value (must be in the range min..max)
+     * @param min the minimum value
+     * @param max the maximum value (must be larger than min)
+     * @return the normalized value in the range 0..getMaxValue(dimensions)
+     */
+    public int normalize(int dimensions, double value, double min, double max) {
+        if (value < min || value > max) {
+            throw new IllegalArgumentException(min + "<" + value + "<" + max);
+        }
+        double x = (value - min) / (max - min);
+        return (int) (x * getMaxValue(dimensions));
+    }
+
+    /**
+     * Get the maximum value for the given dimension count. For two dimensions,
+     * each value must contain at most 32 bit, for 3: 21 bit, 4: 16 bit, 5: 12
+     * bit, 6: 10 bit, 7: 9 bit, 8: 8 bit.
+     *
+     * @param dimensions the number of dimensions
+     * @return the maximum value
+     */
+    public int getMaxValue(int dimensions) {
+        if (dimensions < 2 || dimensions > 32) {
+            throw new IllegalArgumentException("" + dimensions);
+        }
+        int bitsPerValue = getBitsPerValue(dimensions);
+        return (int) ((1L << bitsPerValue) - 1);
+    }
+
+    private int getBitsPerValue(int dimensions) {
+        return Math.min(31, 64 / dimensions);
+    }
+
     /**
      * Convert the multi-dimensional value into a one-dimensional (scalar) value.
      * This is done by interleaving the bits of the values.
-     * Each values must be bigger or equal to 0. The maximum value
-     * depends on the number of dimensions. For two keys, it is 32 bit,
-     * for 3: 21 bit, 4: 16 bit, 5: 12 bit, 6: 10 bit, 7: 9 bit, 8: 8 bit.
+     * Each values must be between 0 (including) and the maximum value
+     * for the given number of dimensions (getMaxValue, excluding).
+     * To normalize values to this range, use the normalize function.
      *
      * @param values the multi-dimensional value
      * @return the scalar value
      */
-    public long interleave(int[] values) {
+    public long interleave(int... values) {
         int dimensions = values.length;
-        int bitsPerValue = 64 / dimensions;
-        // for 2 keys: 0x800000; 3: 0x
         long max = getMaxValue(dimensions);
+        int bitsPerValue = getBitsPerValue(dimensions);
         long x = 0;
         for (int i = 0; i < dimensions; i++) {
             long k = values[i];
-            if (k < 0 || k >= max) {
-                throw new IllegalArgumentException("value out of range; value=" + values[i] + " min=0 max=" + max);
+            if (k < 0 || k > max) {
+                throw new IllegalArgumentException(0 + "<" + k + "<" + max);
             }
             for (int b = 0; b < bitsPerValue; b++) {
                 x |= (k & (1L << b)) << (i + (dimensions - 1) * b);
             }
         }
-        if (dimensions == 2) {
-            long xx = getMorton2(values[0], values[1]);
-            if (xx != x) {
-                throw new IllegalArgumentException("test");
-            }
-        }
         return x;
     }
 
     /**
-     * Get the maximum value for the given dimension count
-     * @param dimensions the number of dimensions
+     * Convert the two-dimensional value into a one-dimensional (scalar) value.
+     * This is done by interleaving the bits of the values.
+     * Each values must be between 0 (including) and the maximum value
+     * for the given number of dimensions (getMaxValue, excluding).
+     * To normalize values to this range, use the normalize function.
      *
-     * @return the maximum value
+     * @param x the value of the first dimension, normalized
+     * @param y the value of the second dimension, normalized
+     * @return the scalar value
      */
-    public static long getMaxValue(int dimensions) {
-        if (dimensions < 2 || dimensions > 64) {
-            throw new IllegalArgumentException("dimensions: " + dimensions);
+    public long interleave(int x, int y) {
+        if (x < 0) {
+            throw new IllegalArgumentException(0 + "<" + x);
+        }
+        if (y < 0) {
+            throw new IllegalArgumentException(0 + "<" + y);
         }
-        int bitsPerValue = 64 / dimensions;
-        // for 2 keys: 0x800000; 3: 0x
-        return 1L << bitsPerValue;
+        long z = 0;
+        for (int i = 0; i < 32; i++) {
+            z |= (x & (1L << i)) << i;
+            z |= (y & (1L << i)) << (i + 1);
+        }
+        return z;
     }
 
     /**
      * Gets one of the original multi-dimensional values from a scalar value.
      *
-     * @param scalar the scalar value
      * @param dimensions the number of dimensions
+     * @param scalar the scalar value
      * @param dim the dimension of the returned value (starting from 0)
      * @return the value
      */
-    public int deinterleave(long scalar, int dimensions, int dim) {
-        int bitsPerValue = 64 / dimensions;
+    public int deinterleave(int dimensions, long scalar, int dim) {
+        int bitsPerValue = getBitsPerValue(dimensions);
         int value = 0;
         for (int i = 0; i < bitsPerValue; i++) {
             value |= (scalar >> (dim + (dimensions - 1) * i)) & (1L << i);
@@ -103,14 +145,6 @@ public class MultiDimension implements Comparator<long[]> {
         return value;
     }
 
-//    public static int get(long z, int d) {
-//        int n = 0;
-//        for (int i = 0; i < 31; i++) {
-//            n |= (z & (1 << (i + i + d))) >> (i + d);
-//        }
-//        return n;
-//    }
-
     /**
      * Generates an optimized multi-dimensional range query.
      * The query contains parameters. It can only be used with the H2 database.
@@ -172,7 +206,7 @@ public class MultiDimension implements Comparator<long[]> {
     private long[][] getMortonRanges(int[] min, int[] max) {
         int len = min.length;
         if (max.length != len) {
-            throw new IllegalArgumentException("dimensions mismatch");
+            throw new IllegalArgumentException(len + "=" + max.length);
         }
         for (int i = 0; i < len; i++) {
             if (min[i] > max[i]) {
@@ -184,21 +218,12 @@ public class MultiDimension implements Comparator<long[]> {
         int total = getSize(min, max, len);
         ArrayList<long[]> list = New.arrayList();
         addMortonRanges(list, min, max, len, 0);
-        optimize(list, total);
+        combineEntries(list, total);
         long[][] ranges = new long[list.size()][2];
         list.toArray(ranges);
         return ranges;
     }
 
-    private long getMorton2(int x, int y) {
-        long z = 0;
-        for (int i = 0; i < 32; i++) {
-            z |= (x & (1L << i)) << i;
-            z |= (y & (1L << i)) << (i + 1);
-        }
-        return z;
-    }
-
     private int getSize(int[] min, int[] max, int len) {
         int size = 1;
         for (int i = 0; i < len; i++) {
@@ -208,9 +233,15 @@ public class MultiDimension implements Comparator<long[]> {
         return size;
     }
 
-    private void optimize(ArrayList<long[]> list, int total) {
+    /**
+     * Combine entries if the size of the list is too large.
+     *
+     * @param list the size of the list
+     * @param total
+     */
+    private void combineEntries(ArrayList<long[]> list, int total) {
         Collections.sort(list, this);
-        for (int minGap = 10;; minGap += minGap / 2) {
+        for (int minGap = 10; minGap < total; minGap += minGap / 2) {
             for (int i = 0; i < list.size() - 1; i++) {
                 long[] current = list.get(i);
                 long[] next = list.get(i + 1);
@@ -224,7 +255,7 @@ public class MultiDimension implements Comparator<long[]> {
             for (long[] range : list) {
                 searched += range[1] - range[0] + 1;
             }
-            if (searched > 2 * total || list.size() < 3 /* || minGap > total */) {
+            if (searched > 2 * total || list.size() < 100) {
                 break;
              }
         }
@@ -236,18 +267,18 @@ public class MultiDimension implements Comparator<long[]> {
 
     private void addMortonRanges(ArrayList<long[]> list, int[] min, int[] max, int len, int level) {
         if (level > 100) {
-            throw new IllegalArgumentException("Stop");
+            throw new IllegalArgumentException("" + level);
         }
         int largest = 0, largestDiff = 0;
         long size = 1;
         for (int i = 0; i < len; i++) {
             int diff = max[i] - min[i];
             if (diff < 0) {
-                throw new IllegalArgumentException("Stop");
+                throw new IllegalArgumentException(""+ diff);
             }
             size *= diff + 1;
             if (size < 0) {
-                throw new IllegalArgumentException("Stop");
+                throw new IllegalArgumentException("" + size);
             }
             if (diff > largestDiff) {
                 largestDiff = diff;
@@ -256,7 +287,7 @@ public class MultiDimension implements Comparator<long[]> {
         }
         long low = interleave(min), high = interleave(max);
         if (high < low) {
-            throw new IllegalArgumentException("Stop");
+            throw new IllegalArgumentException(high + "<" + low);
         }
         long range = high - low + 1;
         if (range == size) {
@@ -294,7 +325,7 @@ public class MultiDimension implements Comparator<long[]> {
         scale--;
         int m = roundUp(a + 2, 1 << scale) - 1;
         if (m <= a || m >= b) {
-            throw new IllegalArgumentException("stop");
+            throw new IllegalArgumentException(a + "<" + m + "<" + b);
         }
         return m;
     }