X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=src%2Fdata%2Fcase-ordering.c;h=7b3948c441e0658914a3737ae33071f8b0c2a910;hb=685407ad62911e5edb1ec093a01ec9e46563af44;hp=910a9ea66ad7facb55a2c4a5740d636845e52b11;hpb=f5c108becd49d78f4898cab11352291f5689d24e;p=pspp-builds.git

diff --git a/src/data/case-ordering.c b/src/data/case-ordering.c
index 910a9ea6..7b3948c4 100644
--- a/src/data/case-ordering.c
+++ b/src/data/case-ordering.c
@@ -1,20 +1,18 @@
-/* PSPP - computes sample statistics.
+/* PSPP - a program for statistical analysis.
    Copyright (C) 2007 Free Software Foundation, Inc.
 
-   This program is free software; you can redistribute it and/or
-   modify it under the terms of the GNU General Public License as
-   published by the Free Software Foundation; either version 2 of the
-   License, or (at your option) any later version.
+   This program is free software: you can redistribute it and/or modify
+   it under the terms of the GNU General Public License as published by
+   the Free Software Foundation, either version 3 of the License, or
+   (at your option) any later version.
 
-   This program is distributed in the hope that it will be useful, but
-   WITHOUT ANY WARRANTY; without even the implied warranty of
-   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-   General Public License for more details.
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
 
    You should have received a copy of the GNU General Public License
-   along with this program; if not, write to the Free Software
-   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
-   02110-1301, USA. */
+   along with this program.  If not, see <http://www.gnu.org/licenses/>. */
 
 #include <config.h>
 
@@ -46,6 +44,10 @@ 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)
 {
@@ -56,6 +58,7 @@ 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)
 {
@@ -66,6 +69,7 @@ case_ordering_clone (const struct case_ordering *orig)
   return co;
 }
 
+/* Destroys case ordering CO. */
 void
 case_ordering_destroy (struct case_ordering *co)
 {
@@ -76,12 +80,17 @@ case_ordering_destroy (struct case_ordering *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)
 {
   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)
@@ -116,6 +125,9 @@ 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)
@@ -134,12 +146,18 @@ 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)
 {
   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)
 {
@@ -147,6 +165,7 @@ case_ordering_get_var (const struct case_ordering *co, size_t idx)
   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)
 {
@@ -154,6 +173,10 @@ case_ordering_get_direction (const struct case_ordering *co, size_t idx)
   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)