src/data/mrset.h

   1 /* PSPP - a program for statistical analysis.
   2    Copyright (C) 2010 Free Software Foundation, Inc.
   3
   4    This program is free software: you can redistribute it and/or modify
   5    it under the terms of the GNU General Public License as published by
   6    the Free Software Foundation, either version 3 of the License, or
   7    (at your option) any later version.
   8
   9    This program is distributed in the hope that it will be useful,
  10    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12    GNU General Public License for more details.
  13
  14    You should have received a copy of the GNU General Public License
  15    along with this program.  If not, see <http://www.gnu.org/licenses/>. */
  16
  17 #ifndef DATA_MRSET_H
  18 #define DATA_MRSET_H 1
  19
  20 /* Multiple response set data structure.
  21
  22    A multiple response set (mrset) is a set of variables that represent
  23    multiple responses to a single survey question in one of the two following
  24    ways:
  25
  26      - A multiple dichotomy set represents a survey question with a set of
  27        checkboxes.  Each variable in the set is treated in a Boolean fashion:
  28        one value (the "counted value") means that the box was checked, and any
  29        other value means that it was not.
  30
  31      - A multiple category set represents a survey question where the
  32        respondent is instructed to "list up to N choices".  Each variable
  33        represents one of the responses.
  34
  35    The set of functions provided here are skeletal.  Undoubtedly they will grow
  36    as PSPP begins to make use of multiple response sets, as opposed to merely
  37    maintaining them as part of the dictionary.
  38  */
  39
  40 #include <stdbool.h>
  41 #include <stddef.h>
  42
  43 #include "data/value.h"
  44
  45 struct dictionary;
  46
  47 /* Type of a multiple response set. */
  48 enum mrset_type
  49   {
  50     MRSET_MD,                   /* Multiple dichotomy group. */
  51     MRSET_MC                    /* Multiple category group. */
  52   };
  53
  54 /* Source of category labels for a multiple dichotomy group. */
  55 enum mrset_md_cat_source
  56   {
  57     MRSET_VARLABELS,            /* Variable labels. */
  58     MRSET_COUNTEDVALUES         /* Value labels for the counted value. */
  59   };
  60
  61 /* A multiple response set. */
  62 struct mrset
  63   {
  64     char *name;                 /* UTF-8 encoded name beginning with "$". */
  65     char *label;                /* Human-readable UTF-8 label for group. */
  66     enum mrset_type type;       /* Group type. */
  67     struct variable **vars;     /* Constituent variables. */
  68     size_t n_vars;              /* Number of constituent variables. */
  69
  70     /* MRSET_MD only. */
  71     enum mrset_md_cat_source cat_source; /* Source of category labels. */
  72     bool label_from_var_label;  /* 'label' taken from variable label? */
  73     union value counted;        /* Counted value. */
  74     int width;                  /* Width of 'counted'. */
  75   };
  76
  77 struct mrset *mrset_clone (const struct mrset *);
  78 void mrset_destroy (struct mrset *);
  79
  80 bool mrset_is_valid_name (const char *name, const char *dict_encoding,
  81                           bool issue_error);
  82
  83 bool mrset_ok (const struct mrset *, const struct dictionary *);
  84
  85 #endif /* data/mrset.h */