ac8664c4ce72723a58b39920e5332dfe8bbe0efb
[pspp-builds.git] / src / data / category.c
1 /* PSPP - binary encodings for categorical variables.
2    Copyright (C) 2005 Free Software Foundation, Inc.
3
4    This program is free software; you can redistribute it and/or
5    modify it under the terms of the GNU General Public License as
6    published by the Free Software Foundation; either version 2 of the
7    License, or (at your option) any later version.
8
9    This program is distributed in the hope that it will be useful, but
10    WITHOUT ANY WARRANTY; without even the implied warranty of
11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12    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, write to the Free Software
16    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
17    02110-1301, USA. */
18
19 /*
20   Functions and data structures to store values of a categorical
21   variable, and to recode those values into binary vectors.
22
23   For some statistical models, it is necessary to change each value
24   of a categorical variable to a vector with binary entries. These
25   vectors are then stored as sub-rows within a matrix during
26   model-fitting. For example, we need functions and data strucutres to map a
27   value, say 'a', of a variable named 'cat_var', to a vector, say (0
28   1 0 0 0), and vice versa.  We also need to be able to map the
29   vector back to the value 'a', and if the vector is a sub-row of a
30   matrix, we need to know which sub-row corresponds to the variable
31   'cat_var'.
32 */
33 #include <config.h>
34
35 #include <assert.h>
36 #include <stdlib.h>
37 #include <string.h>
38
39 #include <libpspp/alloc.h>
40 #include <libpspp/message.h>
41 #include "category.h"
42 #include "value.h"
43 #include "variable.h"
44
45 #define CAT_VALUE_NOT_FOUND -2
46
47 #define N_INITIAL_CATEGORIES 1
48
49 /*
50   This structure contains the observed values of a
51   categorical variable.
52  */
53 struct cat_vals
54 {
55   union value *vals;
56   size_t n_categories;
57   size_t n_allocated_categories;        /* This is used only during
58                                            initialization to keep
59                                            track of the number of
60                                            values stored.
61                                          */
62 };
63
64 void
65 cat_stored_values_create (const struct variable *v)
66 {
67   if (!var_has_obs_vals (v))
68     {
69       struct cat_vals *obs_vals = xmalloc (sizeof *obs_vals);
70
71       obs_vals->n_categories = 0;
72       obs_vals->n_allocated_categories = N_INITIAL_CATEGORIES;
73       obs_vals->vals = xnmalloc (N_INITIAL_CATEGORIES, sizeof *obs_vals->vals);
74       var_set_obs_vals (v, obs_vals);
75     }
76 }
77
78 void
79 cat_stored_values_destroy (struct cat_vals *obs_vals)
80 {
81   if (obs_vals != NULL)
82     {
83       if (obs_vals->n_allocated_categories > 0)
84         free (obs_vals->vals);
85       free (obs_vals);
86     }
87 }
88
89 /*
90   Which subscript corresponds to val?
91  */
92 size_t
93 cat_value_find (const struct variable *v, const union value *val)
94 {
95   struct cat_vals *obs_vals = var_get_obs_vals (v);
96   size_t i;
97   const union value *candidate;
98
99   for (i = 0; i < obs_vals->n_categories; i++)
100     {
101       candidate = obs_vals->vals + i;
102       assert (candidate != NULL);
103       if (!compare_values (candidate, val, var_get_width (v)))
104         {
105           return i;
106         }
107     }
108   return CAT_VALUE_NOT_FOUND;
109 }
110
111 /*
112    Add the new value unless it is already present.
113  */
114 void
115 cat_value_update (const struct variable *v, const union value *val)
116 {
117   if (var_is_alpha (v))
118     {
119       struct cat_vals *cv = var_get_obs_vals (v);
120       if (cat_value_find (v, val) == CAT_VALUE_NOT_FOUND)
121         {
122           if (cv->n_categories >= cv->n_allocated_categories)
123             {
124               cv->n_allocated_categories *= 2;
125               cv->vals = xnrealloc (cv->vals,
126                                     cv->n_allocated_categories,
127                                     sizeof *cv->vals);
128             }
129           cv->vals[cv->n_categories] = *val;
130           cv->n_categories++;
131         }
132     }
133 }
134
135 const union value *
136 cat_subscript_to_value (const size_t s, const struct variable *v)
137 {
138   struct cat_vals *obs_vals = var_get_obs_vals (v);
139   return s < obs_vals->n_categories ? obs_vals->vals + s : NULL;
140 }
141
142 /*
143   Return the number of categories of a categorical variable.
144  */
145 size_t 
146 cat_get_n_categories (const struct variable *v)
147 {
148   return var_get_obs_vals (v)->n_categories;
149 }
150