Add lots of comments. Some minor substantive changes too:

[pspp-builds.git] / src / data / case-ordering.c

diff --git a/src/data/case-ordering.c b/src/data/case-ordering.c
index aeb87b763511dda02c09b8a89bde334a47c607cb..e9e7095ead9fc1a5916356e87cd4f018cb023c10 100644 (file)
--- a/src/data/case-ordering.c
+++ b/src/data/case-ordering.c
@@ -37,7 +37,7 @@ struct sort_key
   };
 
 /* A set of criteria for ordering cases. */
-struct case_ordering 
+struct case_ordering
   {
     size_t value_cnt;           /* Number of `union value's per case. */
 
@@ -46,8 +46,12 @@ struct case_ordering
     size_t key_cnt;
   };
 
+/* Creates and returns a new case ordering for comparing cases
+   that represent dictionary DICT.  The case ordering initially
+   contains no variables, so that all cases will compare as
+   equal. */
 struct case_ordering *
-case_ordering_create (const struct dictionary *dict) 
+case_ordering_create (const struct dictionary *dict)
 {
   struct case_ordering *co = xmalloc (sizeof *co);
   co->value_cnt = dict_get_next_value_idx (dict);
@@ -56,8 +60,9 @@ case_ordering_create (const struct dictionary *dict)
   return co;
 }
 
+/* Creates and returns a clone of case ordering ORIG. */
 struct case_ordering *
-case_ordering_clone (const struct case_ordering *orig) 
+case_ordering_clone (const struct case_ordering *orig)
 {
   struct case_ordering *co = xmalloc (sizeof *co);
   co->value_cnt = orig->value_cnt;
@@ -66,35 +71,41 @@ case_ordering_clone (const struct case_ordering *orig)
   return co;
 }
 
+/* Destroys case ordering CO. */
 void
-case_ordering_destroy (struct case_ordering *co) 
+case_ordering_destroy (struct case_ordering *co)
 {
-  if (co != NULL) 
+  if (co != NULL)
     {
       free (co->keys);
       free (co);
     }
 }
 
+/* Returns the number of `union value's in the cases that case
+   ordering CO compares (taken from the dictionary used to
+   construct it). */
 size_t
-case_ordering_get_value_cnt (const struct case_ordering *co) 
+case_ordering_get_value_cnt (const struct case_ordering *co)
 {
   return co->value_cnt;
 }
 
+/* Compares cases A and B given case ordering CO and returns a
+   strcmp()-type result. */
 int
 case_ordering_compare_cases (const struct ccase *a, const struct ccase *b,
-                             const struct case_ordering *co) 
+                             const struct case_ordering *co)
 {
   size_t i;
-  
-  for (i = 0; i < co->key_cnt; i++) 
+
+  for (i = 0; i < co->key_cnt; i++)
     {
       const struct sort_key *key = &co->keys[i];
       int width = var_get_width (key->var);
       int cmp;
-      
-      if (width == 0) 
+
+      if (width == 0)
         {
           double af = case_num (a, key->var);
           double bf = case_num (b, key->var);
@@ -102,7 +113,7 @@ case_ordering_compare_cases (const struct ccase *a, const struct ccase *b,
             continue;
           cmp = af > bf ? 1 : -1;
         }
-      else 
+      else
         {
           const char *as = case_str (a, key->var);
           const char *bs = case_str (b, key->var);
@@ -116,9 +127,12 @@ case_ordering_compare_cases (const struct ccase *a, const struct ccase *b,
   return 0;
 }
 
+/* Adds VAR to case ordering CO as an additional sort key in sort
+   direction DIR.  Returns true if successful, false if VAR was
+   already part of the ordering for CO. */
 bool
 case_ordering_add_var (struct case_ordering *co,
-                       const struct variable *var, enum sort_direction dir) 
+                       const struct variable *var, enum sort_direction dir)
 {
   struct sort_key *key;
   size_t i;
@@ -134,32 +148,43 @@ case_ordering_add_var (struct case_ordering *co,
   return true;
 }
 
+/* Returns the number of variables used for ordering within
+   CO. */
 size_t
-case_ordering_get_var_cnt (const struct case_ordering *co) 
+case_ordering_get_var_cnt (const struct case_ordering *co)
 {
   return co->key_cnt;
 }
 
+/* Returns sort variable IDX within CO.  An IDX of 0 returns the
+   primary sort key (the one added first), an IDX of 1 returns
+   the secondary sort key, and so on.  IDX must be less than the
+   number of sort variables. */
 const struct variable *
-case_ordering_get_var (const struct case_ordering *co, size_t idx) 
+case_ordering_get_var (const struct case_ordering *co, size_t idx)
 {
   assert (idx < co->key_cnt);
   return co->keys[idx].var;
 }
 
+/* Returns the sort direction for sort variable IDX within CO. */
 enum sort_direction
-case_ordering_get_direction (const struct case_ordering *co, size_t idx) 
+case_ordering_get_direction (const struct case_ordering *co, size_t idx)
 {
   assert (idx < co->key_cnt);
   return co->keys[idx].dir;
 }
 
+/* Stores an array listing all of the variables used for sorting
+   within CO into *VARS and the number of variables into
+   *VAR_CNT.  The caller is responsible for freeing *VARS when it
+   is no longer needed. */
 void
 case_ordering_get_vars (const struct case_ordering *co,
-                        const struct variable ***vars, size_t *var_cnt) 
+                        const struct variable ***vars, size_t *var_cnt)
 {
   size_t i;
-  
+
   *var_cnt = co->key_cnt;
   *vars = xnmalloc (*var_cnt, sizeof **vars);
   for (i = 0; i < co->key_cnt; i++)