Document datum format.

diff --git a/dump.c b/dump.c
index 1cdb749f81fc714f09876a9701391cb48416e2bb..0445597e635aa6673304d1fa734df0cc29371edc 100644 (file)
--- a/dump.c
+++ b/dump.c
@@ -648,7 +648,7 @@ dump_category(FILE *stream, int level, int *indexes, int *n_indexes, int max_ind
   printf ("</category>\n");
 }
 
-static void
+static int
 dump_dim(int indx)
 {
   int n_categories;
@@ -679,15 +679,20 @@ dump_dim(int indx)
   check_permutation(indexes, n_indexes, "categories");
 
   fprintf (stdout, "</dimension>\n");
+  return n_indexes;
 }
 
 int n_dims;
+static int dim_n_cats[64];
+#define MAX_DIMS (sizeof dim_n_cats / sizeof *dim_n_cats)
+
 static void
 dump_dims(void)
 {
   n_dims = get_u32();
+  assert(n_dims < MAX_DIMS);
   for (int i = 0; i < n_dims; i++)
-    dump_dim (i);
+    dim_n_cats[i] = dump_dim (i);
 }
 
 static void
@@ -715,7 +720,19 @@ dump_data(void)
   printf ("<data>\n");
   for (int i = 0; i < x; i++)
     {
-      printf ("    <datum index=\"%d\">\n", get_u32());
+      unsigned int indx = get_u32();
+      printf ("    <datum index=\"%d\" coords=", indx);
+
+      int coords[MAX_DIMS];
+      for (int i = n_dims; i-- > 0; )
+        {
+          coords[i] = indx % dim_n_cats[i];
+          indx /= dim_n_cats[i];
+        }
+      for (int i = 0; i < n_dims; i++)
+        printf("%c%d", i ? ',' : '"', coords[i]);
+
+      printf ("\">\n");
       match_u32_assert(0);
       if (version == 1)
         match_byte(0);

diff --git a/spv-file-format.texi b/spv-file-format.texi
index bb615a2384333bd3fd4166b21a38f04dceffeefd..a5f45e5b4979f7a86307413c2ad4a8c304658a5c 100644 (file)
--- a/spv-file-format.texi
+++ b/spv-file-format.texi
@@ -557,6 +557,7 @@ be naive.
 
 @example
 data := int[layers] int[rows] int[columns] int*[n-dimensions]
+        int[n-data] datum*[n-data]
 @end example
 
 The values of @code{layers}, @code{rows}, and @code{columns} each
@@ -571,3 +572,27 @@ specify the dimensions represented by rows, and the final
 @code{columns} of them specify the dimensions represented by columns.
 When there is more than one dimension of a given kind, the inner
 dimensions are given first.
+
+@example
+datum := int64[index] 00? value        @r{# Version 1.}
+datum := int64[index] value            @r{# Version 3.}
+@end example
+
+A datum consists of an index and a value.  Suppose there are @math{d}
+dimensions and dimension @math{i} for @math{0 \le i < d} has
+@math{n_i} categories.  Consider the datum at coordinates @math{x_i}
+for @math{0 \le i < d}; note that @math{0 \le x_i < n_i}.  Then the
+index is calculated by the following algorithm:
+
+@display
+let index = 0
+for each @math{i} from 0 to @math{d - 1}:
+    index = @math{n_i \times} index + @math{x_i}
+@end display
+
+For example, suppose there are 3 dimensions with 3, 4, and 5
+categories, respectively.  The datum at coordinates (1, 2, 3) has
+index @math{5 \times (4 \times (3 \times 0 + 1) + 2) + 3 = 33}.
+
+The format of a datum varies slightly from version 1 to version 3, in
+that version 1 has an extra optional 00 byte.