work on docs

[pspp] / src / math / interaction.h

diff --git a/src/math/interaction.h b/src/math/interaction.h
index 0fb1f2622298c2b9b741ac6554aa45051644c4c6..8229083f860f7cf0a7b86e5f4268b9a1551623cf 100644 (file)
--- a/src/math/interaction.h
+++ b/src/math/interaction.h
@@ -19,33 +19,55 @@
 #define _INTERACTION_H__ 1
 
 #include <stdbool.h>
+#include "libpspp/compiler.h"
 #include "data/missing-values.h"
 
+struct ccase;
 struct interaction;
-struct variable;
 struct string;
+struct variable;
 
 #include <stddef.h>
+
+/* An interaction is a structure containing a "product" of other variables.
+   The variables can be either string or numeric.
+
+   Interaction is commutative.  That means, that from a mathematical point of
+   view, the order of the variables is irrelevant.  However, for display
+   purposes, and for matching with an interaction's value the order is
+   pertinent.  Therefore, when using these functions, make sure the orders of
+   variables and values match when appropriate.
+
+   Some functions for interactions will not work properly for interactions that
+   contain a given variable more than once, so this should be regarded as an
+   invariant.  The functions to modify interactions don't check for this
+   invariant. */
 struct interaction
-{
-  size_t n_vars;
-  const struct variable **vars;
-};
+  {
+    const struct variable **vars;
+    size_t n_vars;
+  };
 
-struct interaction * interaction_create (const struct variable *);
+struct interaction *interaction_create (const struct variable *);
+struct interaction *interaction_clone (const struct interaction *);
 void interaction_destroy (struct interaction *);
 void interaction_add_variable (struct interaction *, const struct variable *);
 void interaction_dump (const struct interaction *);
-void interaction_to_string (const struct interaction *iact, struct string *str);
-bool interaction_is_proper_subset (const struct interaction *x, const struct interaction *y);
-bool interaction_is_subset (const struct interaction *x, const struct interaction *y);
+void interaction_to_string (const struct interaction *, struct string *str);
+bool interaction_is_proper_subset (const struct interaction *,
+                                   const struct interaction *);
+bool interaction_is_subset (const struct interaction *,
+                            const struct interaction *);
 
 
-struct ccase;
-unsigned int interaction_case_hash (const struct interaction *, const struct ccase *);
-bool interaction_case_equal (const struct interaction *, const struct ccase *, const struct ccase *);
-bool interaction_case_is_missing (const struct interaction *, const struct ccase *, enum mv_class);
-int interaction_case_cmp_3way (const struct interaction *, const struct ccase *, const struct ccase *);
-
+unsigned int interaction_case_hash (const struct interaction *,
+                                    const struct ccase *,
+                                   unsigned int base) WARN_UNUSED_RESULT;
+bool interaction_case_equal (const struct interaction *, const struct ccase *,
+                             const struct ccase *);
+bool interaction_case_is_missing (const struct interaction *,
+                                  const struct ccase *, enum mv_class);
+int interaction_case_cmp_3way (const struct interaction *,
+                               const struct ccase *, const struct ccase *);
 
 #endif