1 /* PSPP - a program for statistical analysis.
2 Copyright (C) 1997-9, 2000, 2006, 2007, 2009, 2010 Free Software Foundation, Inc.
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.
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.
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/>. */
19 #include "data/dictionary.h"
24 #include "data/attributes.h"
25 #include "data/case.h"
26 #include "data/category.h"
27 #include "data/identifier.h"
28 #include "data/settings.h"
29 #include "data/value-labels.h"
30 #include "data/vardict.h"
31 #include "data/variable.h"
32 #include "data/vector.h"
33 #include "libpspp/array.h"
34 #include "libpspp/assertion.h"
35 #include "libpspp/compiler.h"
36 #include "libpspp/hash-functions.h"
37 #include "libpspp/hmap.h"
38 #include "libpspp/message.h"
39 #include "libpspp/misc.h"
40 #include "libpspp/pool.h"
41 #include "libpspp/str.h"
43 #include "gl/intprops.h"
44 #include "gl/minmax.h"
45 #include "gl/xalloc.h"
48 #define _(msgid) gettext (msgid)
53 struct vardict_info *var; /* Variables. */
54 size_t var_cnt, var_cap; /* Number of variables, capacity. */
55 struct caseproto *proto; /* Prototype for dictionary cases
57 struct hmap name_map; /* Variable index by name. */
58 int next_value_idx; /* Index of next `union value' to allocate. */
59 const struct variable **split; /* SPLIT FILE vars. */
60 size_t split_cnt; /* SPLIT FILE count. */
61 struct variable *weight; /* WEIGHT variable. */
62 struct variable *filter; /* FILTER variable. */
63 casenumber case_limit; /* Current case limit (N command). */
64 char *label; /* File label. */
65 struct string documents; /* Documents, as a string. */
66 struct vector **vector; /* Vectors of variables. */
67 size_t vector_cnt; /* Number of vectors. */
68 struct attrset attributes; /* Custom attributes. */
70 char *encoding; /* Character encoding of string data */
72 const struct dict_callbacks *callbacks; /* Callbacks on dictionary
74 void *cb_data ; /* Data passed to callbacks */
76 void (*changed) (struct dictionary *, void *); /* Generic change callback */
82 dict_set_encoding (struct dictionary *d, const char *enc)
87 d->encoding = xstrdup (enc);
92 dict_get_encoding (const struct dictionary *d)
99 dict_set_change_callback (struct dictionary *d,
100 void (*changed) (struct dictionary *, void*),
103 d->changed = changed;
104 d->changed_data = data;
107 /* Discards dictionary D's caseproto. (It will be regenerated
108 lazily, on demand.) */
110 invalidate_proto (struct dictionary *d)
112 caseproto_unref (d->proto);
116 /* Print a representation of dictionary D to stdout, for
117 debugging purposes. */
119 dict_dump (const struct dictionary *d)
122 for (i = 0 ; i < d->var_cnt ; ++i )
124 const struct variable *v = d->var[i].var;
125 printf ("Name: %s;\tdict_idx: %zu; case_idx: %zu\n",
127 var_get_dict_index (v),
128 var_get_case_index (v));
133 /* Associate CALLBACKS with DICT. Callbacks will be invoked whenever
134 the dictionary or any of the variables it contains are modified.
135 Each callback will get passed CALLBACK_DATA.
136 Any callback may be NULL, in which case it'll be ignored.
139 dict_set_callbacks (struct dictionary *dict,
140 const struct dict_callbacks *callbacks,
143 dict->callbacks = callbacks;
144 dict->cb_data = callback_data;
147 /* Shallow copy the callbacks from SRC to DEST */
149 dict_copy_callbacks (struct dictionary *dest,
150 const struct dictionary *src)
152 dest->callbacks = src->callbacks;
153 dest->cb_data = src->cb_data;
156 /* Creates and returns a new dictionary. */
160 struct dictionary *d = xzalloc (sizeof *d);
162 hmap_init (&d->name_map);
163 attrset_init (&d->attributes);
167 /* Creates and returns a (deep) copy of an existing
170 The new dictionary's case indexes are copied from the old
171 dictionary. If the new dictionary won't be used to access
172 cases produced with the old dictionary, then the new
173 dictionary's case indexes should be compacted with
174 dict_compact_values to save space. */
176 dict_clone (const struct dictionary *s)
178 struct dictionary *d;
183 for (i = 0; i < s->var_cnt; i++)
185 struct variable *sv = s->var[i].var;
186 struct variable *dv = dict_clone_var_assert (d, sv);
189 for (i = 0; i < var_get_short_name_cnt (sv); i++)
190 var_set_short_name (dv, i, var_get_short_name (sv, i));
192 var_get_vardict (dv)->case_index = var_get_vardict (sv)->case_index;
195 d->next_value_idx = s->next_value_idx;
197 d->split_cnt = s->split_cnt;
198 if (d->split_cnt > 0)
200 d->split = xnmalloc (d->split_cnt, sizeof *d->split);
201 for (i = 0; i < d->split_cnt; i++)
202 d->split[i] = dict_lookup_var_assert (d, var_get_name (s->split[i]));
205 if (s->weight != NULL)
206 dict_set_weight (d, dict_lookup_var_assert (d, var_get_name (s->weight)));
208 if (s->filter != NULL)
209 dict_set_filter (d, dict_lookup_var_assert (d, var_get_name (s->filter)));
211 d->case_limit = s->case_limit;
212 dict_set_label (d, dict_get_label (s));
213 dict_set_documents (d, dict_get_documents (s));
215 d->vector_cnt = s->vector_cnt;
216 d->vector = xnmalloc (d->vector_cnt, sizeof *d->vector);
217 for (i = 0; i < s->vector_cnt; i++)
218 d->vector[i] = vector_clone (s->vector[i], s, d);
221 d->encoding = xstrdup (s->encoding);
223 dict_set_attributes (d, dict_get_attributes (s));
228 /* Clears the contents from a dictionary without destroying the
229 dictionary itself. */
231 dict_clear (struct dictionary *d)
233 /* FIXME? Should we really clear case_limit, label, documents?
234 Others are necessarily cleared by deleting all the variables.*/
235 while (d->var_cnt > 0 )
237 dict_delete_var (d, d->var[d->var_cnt - 1].var);
242 d->var_cnt = d->var_cap = 0;
243 invalidate_proto (d);
244 hmap_clear (&d->name_map);
245 d->next_value_idx = 0;
246 dict_set_split_vars (d, NULL, 0);
247 dict_set_weight (d, NULL);
248 dict_set_filter (d, NULL);
252 ds_destroy (&d->documents);
253 dict_clear_vectors (d);
254 attrset_clear (&d->attributes);
257 /* Destroys the aux data for every variable in D, by calling
258 var_clear_aux() for each variable. */
260 dict_clear_aux (struct dictionary *d)
264 for (i = 0; i < d->var_cnt; i++)
265 var_clear_aux (d->var[i].var);
268 /* Clears a dictionary and destroys it. */
270 dict_destroy (struct dictionary *d)
274 /* In general, we don't want callbacks occuring, if the dictionary
275 is being destroyed */
276 d->callbacks = NULL ;
279 hmap_destroy (&d->name_map);
280 attrset_destroy (&d->attributes);
285 /* Returns the number of variables in D. */
287 dict_get_var_cnt (const struct dictionary *d)
292 /* Returns the variable in D with dictionary index IDX, which
293 must be between 0 and the count returned by
294 dict_get_var_cnt(), exclusive. */
296 dict_get_var (const struct dictionary *d, size_t idx)
298 assert (idx < d->var_cnt);
300 return d->var[idx].var;
303 /* Sets *VARS to an array of pointers to variables in D and *CNT
304 to the number of variables in *D. All variables are returned
305 except for those, if any, in the classes indicated by EXCLUDE.
306 (There is no point in putting DC_SYSTEM in EXCLUDE as
307 dictionaries never include system variables.) */
309 dict_get_vars (const struct dictionary *d, const struct variable ***vars,
310 size_t *cnt, enum dict_class exclude)
312 dict_get_vars_mutable (d, (struct variable ***) vars, cnt, exclude);
315 /* Sets *VARS to an array of pointers to variables in D and *CNT
316 to the number of variables in *D. All variables are returned
317 except for those, if any, in the classes indicated by EXCLUDE.
318 (There is no point in putting DC_SYSTEM in EXCLUDE as
319 dictionaries never include system variables.) */
321 dict_get_vars_mutable (const struct dictionary *d, struct variable ***vars,
322 size_t *cnt, enum dict_class exclude)
327 assert (exclude == (exclude & DC_ALL));
330 for (i = 0; i < d->var_cnt; i++)
332 enum dict_class class = var_get_dict_class (d->var[i].var);
333 if (!(class & exclude))
337 *vars = xnmalloc (count, sizeof **vars);
339 for (i = 0; i < d->var_cnt; i++)
341 enum dict_class class = var_get_dict_class (d->var[i].var);
342 if (!(class & exclude))
343 (*vars)[(*cnt)++] = d->var[i].var;
345 assert (*cnt == count);
348 static struct variable *
349 add_var (struct dictionary *d, struct variable *v)
351 struct vardict_info *vardict;
353 /* Update dictionary. */
354 if (d->var_cnt >= d->var_cap)
358 d->var = x2nrealloc (d->var, &d->var_cap, sizeof *d->var);
359 hmap_clear (&d->name_map);
360 for (i = 0; i < d->var_cnt; i++)
362 var_set_vardict (d->var[i].var, &d->var[i]);
363 hmap_insert_fast (&d->name_map, &d->var[i].name_node,
364 d->var[i].name_node.hash);
368 vardict = &d->var[d->var_cnt++];
371 hmap_insert (&d->name_map, &vardict->name_node,
372 hash_case_string (var_get_name (v), 0));
373 vardict->case_index = d->next_value_idx;
374 var_set_vardict (v, vardict);
376 if ( d->changed ) d->changed (d, d->changed_data);
377 if ( d->callbacks && d->callbacks->var_added )
378 d->callbacks->var_added (d, var_get_dict_index (v), d->cb_data);
381 invalidate_proto (d);
386 /* Creates and returns a new variable in D with the given NAME
387 and WIDTH. Returns a null pointer if the given NAME would
388 duplicate that of an existing variable in the dictionary. */
390 dict_create_var (struct dictionary *d, const char *name, int width)
392 return (dict_lookup_var (d, name) == NULL
393 ? dict_create_var_assert (d, name, width)
397 /* Creates and returns a new variable in D with the given NAME
398 and WIDTH. Assert-fails if the given NAME would duplicate
399 that of an existing variable in the dictionary. */
401 dict_create_var_assert (struct dictionary *d, const char *name, int width)
403 assert (dict_lookup_var (d, name) == NULL);
404 return add_var (d, var_create (name, width));
407 /* Creates and returns a new variable in D, as a copy of existing variable
408 OLD_VAR, which need not be in D or in any dictionary. Returns a null
409 pointer if OLD_VAR's name would duplicate that of an existing variable in
412 dict_clone_var (struct dictionary *d, const struct variable *old_var)
414 return dict_clone_var_as (d, old_var, var_get_name (old_var));
417 /* Creates and returns a new variable in D, as a copy of existing variable
418 OLD_VAR, which need not be in D or in any dictionary. Assert-fails if
419 OLD_VAR's name would duplicate that of an existing variable in the
422 dict_clone_var_assert (struct dictionary *d, const struct variable *old_var)
424 return dict_clone_var_as_assert (d, old_var, var_get_name (old_var));
427 /* Creates and returns a new variable in D with name NAME, as a copy of
428 existing variable OLD_VAR, which need not be in D or in any dictionary.
429 Returns a null pointer if the given NAME would duplicate that of an existing
430 variable in the dictionary. */
432 dict_clone_var_as (struct dictionary *d, const struct variable *old_var,
435 return (dict_lookup_var (d, name) == NULL
436 ? dict_clone_var_as_assert (d, old_var, name)
440 /* Creates and returns a new variable in D with name NAME, as a copy of
441 existing variable OLD_VAR, which need not be in D or in any dictionary.
442 Assert-fails if the given NAME would duplicate that of an existing variable
443 in the dictionary. */
445 dict_clone_var_as_assert (struct dictionary *d, const struct variable *old_var,
448 struct variable *new_var = var_clone (old_var);
449 assert (dict_lookup_var (d, name) == NULL);
450 var_set_name (new_var, name);
451 return add_var (d, new_var);
454 /* Returns the variable named NAME in D, or a null pointer if no
455 variable has that name. */
457 dict_lookup_var (const struct dictionary *d, const char *name)
459 struct vardict_info *vardict;
461 HMAP_FOR_EACH_WITH_HASH (vardict, struct vardict_info, name_node,
462 hash_case_string (name, 0), &d->name_map)
464 struct variable *var = vardict->var;
465 if (!strcasecmp (var_get_name (var), name))
472 /* Returns the variable named NAME in D. Assert-fails if no
473 variable has that name. */
475 dict_lookup_var_assert (const struct dictionary *d, const char *name)
477 struct variable *v = dict_lookup_var (d, name);
482 /* Returns true if variable V is in dictionary D,
485 dict_contains_var (const struct dictionary *d, const struct variable *v)
487 return (var_has_vardict (v)
488 && vardict_get_dictionary (var_get_vardict (v)) == d);
491 /* Compares two double pointers to variables, which should point
492 to elements of a struct dictionary's `var' member array. */
494 compare_var_ptrs (const void *a_, const void *b_, const void *aux UNUSED)
496 struct variable *const *a = a_;
497 struct variable *const *b = b_;
499 return *a < *b ? -1 : *a > *b;
503 unindex_var (struct dictionary *d, struct vardict_info *vardict)
505 hmap_delete (&d->name_map, &vardict->name_node);
508 /* This function assumes that vardict->name_node.hash is valid, that is, that
509 its name has not changed since it was hashed (rename_var() updates this
510 hash along with the name itself). */
512 reindex_var (struct dictionary *d, struct vardict_info *vardict)
514 struct variable *var = vardict->var;
516 var_set_vardict (var, vardict);
517 hmap_insert_fast (&d->name_map, &vardict->name_node,
518 vardict->name_node.hash);
520 if ( d->changed ) d->changed (d, d->changed_data);
521 if ( d->callbacks && d->callbacks->var_changed )
522 d->callbacks->var_changed (d, var_get_dict_index (var), d->cb_data);
525 /* Sets the case_index in V's vardict to CASE_INDEX. */
527 set_var_case_index (struct variable *v, int case_index)
529 var_get_vardict (v)->case_index = case_index;
532 /* Removes the dictionary variables with indexes from FROM to TO (exclusive)
535 unindex_vars (struct dictionary *d, size_t from, size_t to)
539 for (i = from; i < to; i++)
540 unindex_var (d, &d->var[i]);
543 /* Re-sets the dict_index in the dictionary variables with
544 indexes from FROM to TO (exclusive). */
546 reindex_vars (struct dictionary *d, size_t from, size_t to)
550 for (i = from; i < to; i++)
551 reindex_var (d, &d->var[i]);
554 /* Deletes variable V from dictionary D and frees V.
556 This is a very bad idea if there might be any pointers to V
557 from outside D. In general, no variable in the active file's
558 dictionary should be deleted when any transformations are
559 active on the dictionary's dataset, because those
560 transformations might reference the deleted variable. The
561 safest time to delete a variable is just after a procedure has
562 been executed, as done by DELETE VARIABLES.
564 Pointers to V within D are not a problem, because
565 dict_delete_var() knows to remove V from split variables,
566 weights, filters, etc. */
568 dict_delete_var (struct dictionary *d, struct variable *v)
570 int dict_index = var_get_dict_index (v);
571 const int case_index = var_get_case_index (v);
572 const int width = var_get_width (v);
574 assert (dict_contains_var (d, v));
576 /* Delete aux data. */
579 dict_unset_split_var (d, v);
582 dict_set_weight (d, NULL);
585 dict_set_filter (d, NULL);
587 dict_clear_vectors (d);
589 /* Remove V from var array. */
590 unindex_vars (d, dict_index, d->var_cnt);
591 remove_element (d->var, d->var_cnt, sizeof *d->var, dict_index);
594 /* Update dict_index for each affected variable. */
595 reindex_vars (d, dict_index, d->var_cnt);
598 var_clear_vardict (v);
601 if ( d->changed ) d->changed (d, d->changed_data);
603 invalidate_proto (d);
604 if (d->callbacks && d->callbacks->var_deleted )
605 d->callbacks->var_deleted (d, dict_index, case_index, width, d->cb_data);
608 /* Deletes the COUNT variables listed in VARS from D. This is
609 unsafe; see the comment on dict_delete_var() for details. */
611 dict_delete_vars (struct dictionary *d,
612 struct variable *const *vars, size_t count)
614 /* FIXME: this can be done in O(count) time, but this algorithm
616 assert (count == 0 || vars != NULL);
619 dict_delete_var (d, *vars++);
622 /* Deletes the COUNT variables in D starting at index IDX. This
623 is unsafe; see the comment on dict_delete_var() for
626 dict_delete_consecutive_vars (struct dictionary *d, size_t idx, size_t count)
628 /* FIXME: this can be done in O(count) time, but this algorithm
630 assert (idx + count <= d->var_cnt);
633 dict_delete_var (d, d->var[idx].var);
636 /* Deletes scratch variables from dictionary D. */
638 dict_delete_scratch_vars (struct dictionary *d)
642 /* FIXME: this can be done in O(count) time, but this algorithm
644 for (i = 0; i < d->var_cnt; )
645 if (var_get_dict_class (d->var[i].var) == DC_SCRATCH)
646 dict_delete_var (d, d->var[i].var);
651 /* Moves V to 0-based position IDX in D. Other variables in D,
652 if any, retain their relative positions. Runs in time linear
653 in the distance moved. */
655 dict_reorder_var (struct dictionary *d, struct variable *v, size_t new_index)
657 size_t old_index = var_get_dict_index (v);
659 assert (new_index < d->var_cnt);
661 unindex_vars (d, MIN (old_index, new_index), MAX (old_index, new_index) + 1);
662 move_element (d->var, d->var_cnt, sizeof *d->var, old_index, new_index);
663 reindex_vars (d, MIN (old_index, new_index), MAX (old_index, new_index) + 1);
666 /* Reorders the variables in D, placing the COUNT variables
667 listed in ORDER in that order at the beginning of D. The
668 other variables in D, if any, retain their relative
671 dict_reorder_vars (struct dictionary *d,
672 struct variable *const *order, size_t count)
674 struct vardict_info *new_var;
677 assert (count == 0 || order != NULL);
678 assert (count <= d->var_cnt);
680 new_var = xnmalloc (d->var_cap, sizeof *new_var);
682 /* Add variables in ORDER to new_var. */
683 for (i = 0; i < count; i++)
685 struct vardict_info *old_var;
687 assert (dict_contains_var (d, order[i]));
689 old_var = var_get_vardict (order[i]);
690 new_var[i] = *old_var;
691 old_var->dict = NULL;
694 /* Add remaining variables to new_var. */
695 for (i = 0; i < d->var_cnt; i++)
696 if (d->var[i].dict != NULL)
697 new_var[count++] = d->var[i];
698 assert (count == d->var_cnt);
700 /* Replace old vardicts by new ones. */
704 hmap_clear (&d->name_map);
705 reindex_vars (d, 0, d->var_cnt);
708 /* Changes the name of variable V that is currently in a dictionary to
711 rename_var (struct variable *v, const char *new_name)
713 struct vardict_info *vardict = var_get_vardict (v);
714 var_clear_vardict (v);
715 var_set_name (v, new_name);
716 vardict->name_node.hash = hash_case_string (new_name, 0);
717 var_set_vardict (v, vardict);
720 /* Changes the name of V in D to name NEW_NAME. Assert-fails if
721 a variable named NEW_NAME is already in D, except that
722 NEW_NAME may be the same as V's existing name. */
724 dict_rename_var (struct dictionary *d, struct variable *v,
725 const char *new_name)
727 assert (!strcasecmp (var_get_name (v), new_name)
728 || dict_lookup_var (d, new_name) == NULL);
730 unindex_var (d, var_get_vardict (v));
731 rename_var (v, new_name);
732 reindex_var (d, var_get_vardict (v));
734 if (settings_get_algorithm () == ENHANCED)
735 var_clear_short_names (v);
737 if ( d->changed ) d->changed (d, d->changed_data);
738 if ( d->callbacks && d->callbacks->var_changed )
739 d->callbacks->var_changed (d, var_get_dict_index (v), d->cb_data);
742 /* Renames COUNT variables specified in VARS to the names given
743 in NEW_NAMES within dictionary D. If the renaming would
744 result in a duplicate variable name, returns false and stores a
745 name that would be duplicated into *ERR_NAME (if ERR_NAME is
746 non-null). Otherwise, the renaming is successful, and true
749 dict_rename_vars (struct dictionary *d,
750 struct variable **vars, char **new_names, size_t count,
757 assert (count == 0 || vars != NULL);
758 assert (count == 0 || new_names != NULL);
760 /* Save the names of the variables to be renamed. */
761 pool = pool_create ();
762 old_names = pool_nalloc (pool, count, sizeof *old_names);
763 for (i = 0; i < count; i++)
764 old_names[i] = pool_strdup (pool, var_get_name (vars[i]));
766 /* Remove the variables to be renamed from the name hash,
768 for (i = 0; i < count; i++)
770 unindex_var (d, var_get_vardict (vars[i]));
771 rename_var (vars[i], new_names[i]);
774 /* Add the renamed variables back into the name hash,
775 checking for conflicts. */
776 for (i = 0; i < count; i++)
778 if (dict_lookup_var (d, var_get_name (vars[i])) != NULL)
780 /* There is a name conflict.
781 Back out all the name changes that have already
782 taken place, and indicate failure. */
784 if (err_name != NULL)
785 *err_name = new_names[i];
787 for (i = 0; i < fail_idx; i++)
788 unindex_var (d, var_get_vardict (vars[i]));
790 for (i = 0; i < count; i++)
792 rename_var (vars[i], old_names[i]);
793 reindex_var (d, var_get_vardict (vars[i]));
799 reindex_var (d, var_get_vardict (vars[i]));
802 /* Clear short names. */
803 if (settings_get_algorithm () == ENHANCED)
804 for (i = 0; i < count; i++)
805 var_clear_short_names (vars[i]);
811 /* Returns true if a variable named NAME may be inserted in DICT;
812 that is, if there is not already a variable with that name in
813 DICT and if NAME is not a reserved word. (The caller's checks
814 have already verified that NAME is otherwise acceptable as a
817 var_name_is_insertable (const struct dictionary *dict, const char *name)
819 return (dict_lookup_var (dict, name) == NULL
820 && lex_id_to_token (ss_cstr (name)) == T_ID);
824 make_hinted_name (const struct dictionary *dict, const char *hint,
825 char name[VAR_NAME_LEN + 1])
827 bool dropped = false;
830 for (cp = name; *hint && cp < name + VAR_NAME_LEN; hint++)
833 ? lex_is_id1 (*hint) && *hint != '$'
834 : lex_is_idn (*hint))
841 if (cp < name + VAR_NAME_LEN)
851 size_t len = strlen (name);
854 if (var_name_is_insertable (dict, name))
857 for (i = 0; i < ULONG_MAX; i++)
859 char suffix[INT_BUFSIZE_BOUND (i) + 1];
863 if (!str_format_26adic (i + 1, &suffix[1], sizeof suffix - 1))
866 ofs = MIN (VAR_NAME_LEN - strlen (suffix), len);
867 strcpy (&name[ofs], suffix);
869 if (var_name_is_insertable (dict, name))
878 make_numeric_name (const struct dictionary *dict, unsigned long int *num_start,
879 char name[VAR_NAME_LEN + 1])
881 unsigned long int number;
883 for (number = num_start != NULL ? MAX (*num_start, 1) : 1;
887 sprintf (name, "VAR%03lu", number);
888 if (dict_lookup_var (dict, name) == NULL)
890 if (num_start != NULL)
891 *num_start = number + 1;
896 if (num_start != NULL)
897 *num_start = ULONG_MAX;
902 /* Attempts to devise a variable name unique within DICT.
903 Returns true if successful, in which case the new variable
904 name is stored into NAME. Returns false if all names that can
905 be generated have already been taken. (Returning false is
906 quite unlikely: at least ULONG_MAX unique names can be
909 HINT, if it is non-null, is used as a suggestion that will be
910 modified for suitability as a variable name and for
913 If HINT is null or entirely unsuitable, a name in the form
914 "VAR%03d" will be generated, where the smallest unused integer
915 value is used. If NUM_START is non-null, then its value is
916 used as the minimum numeric value to check, and it is updated
917 to the next value to be checked.
920 dict_make_unique_var_name (const struct dictionary *dict, const char *hint,
921 unsigned long int *num_start,
922 char name[VAR_NAME_LEN + 1])
924 return ((hint != NULL && make_hinted_name (dict, hint, name))
925 || make_numeric_name (dict, num_start, name));
928 /* Returns the weighting variable in dictionary D, or a null
929 pointer if the dictionary is unweighted. */
931 dict_get_weight (const struct dictionary *d)
933 assert (d->weight == NULL || dict_contains_var (d, d->weight));
938 /* Returns the value of D's weighting variable in case C, except
939 that a negative weight is returned as 0. Returns 1 if the
940 dictionary is unweighted. Will warn about missing, negative,
941 or zero values if *WARN_ON_INVALID is true. The function will
942 set *WARN_ON_INVALID to false if an invalid weight is
945 dict_get_case_weight (const struct dictionary *d, const struct ccase *c,
946 bool *warn_on_invalid)
950 if (d->weight == NULL)
954 double w = case_num (c, d->weight);
955 if (w < 0.0 || var_is_num_missing (d->weight, w, MV_ANY))
957 if ( w == 0.0 && warn_on_invalid != NULL && *warn_on_invalid ) {
958 *warn_on_invalid = false;
959 msg (SW, _("At least one case in the data file had a weight value "
960 "that was user-missing, system-missing, zero, or "
961 "negative. These case(s) were ignored."));
967 /* Sets the weighting variable of D to V, or turning off
968 weighting if V is a null pointer. */
970 dict_set_weight (struct dictionary *d, struct variable *v)
972 assert (v == NULL || dict_contains_var (d, v));
973 assert (v == NULL || var_is_numeric (v));
977 if (d->changed) d->changed (d, d->changed_data);
978 if ( d->callbacks && d->callbacks->weight_changed )
979 d->callbacks->weight_changed (d,
980 v ? var_get_dict_index (v) : -1,
984 /* Returns the filter variable in dictionary D (see cmd_filter())
985 or a null pointer if the dictionary is unfiltered. */
987 dict_get_filter (const struct dictionary *d)
989 assert (d->filter == NULL || dict_contains_var (d, d->filter));
994 /* Sets V as the filter variable for dictionary D. Passing a
995 null pointer for V turn off filtering. */
997 dict_set_filter (struct dictionary *d, struct variable *v)
999 assert (v == NULL || dict_contains_var (d, v));
1000 assert (v == NULL || var_is_numeric (v));
1004 if (d->changed) d->changed (d, d->changed_data);
1005 if ( d->callbacks && d->callbacks->filter_changed )
1006 d->callbacks->filter_changed (d,
1007 v ? var_get_dict_index (v) : -1,
1011 /* Returns the case limit for dictionary D, or zero if the number
1012 of cases is unlimited. */
1014 dict_get_case_limit (const struct dictionary *d)
1016 return d->case_limit;
1019 /* Sets CASE_LIMIT as the case limit for dictionary D. Use
1020 0 for CASE_LIMIT to indicate no limit. */
1022 dict_set_case_limit (struct dictionary *d, casenumber case_limit)
1024 d->case_limit = case_limit;
1027 /* Returns the prototype used for cases created by dictionary D. */
1028 const struct caseproto *
1029 dict_get_proto (const struct dictionary *d_)
1031 struct dictionary *d = CONST_CAST (struct dictionary *, d_);
1032 if (d->proto == NULL)
1036 d->proto = caseproto_create ();
1037 d->proto = caseproto_reserve (d->proto, d->var_cnt);
1038 for (i = 0; i < d->var_cnt; i++)
1039 d->proto = caseproto_set_width (d->proto,
1040 var_get_case_index (d->var[i].var),
1041 var_get_width (d->var[i].var));
1046 /* Returns the case index of the next value to be added to D.
1047 This value is the number of `union value's that need to be
1048 allocated to store a case for dictionary D. */
1050 dict_get_next_value_idx (const struct dictionary *d)
1052 return d->next_value_idx;
1055 /* Returns the number of bytes needed to store a case for
1058 dict_get_case_size (const struct dictionary *d)
1060 return sizeof (union value) * dict_get_next_value_idx (d);
1063 /* Reassigns values in dictionary D so that fragmentation is
1066 dict_compact_values (struct dictionary *d)
1070 d->next_value_idx = 0;
1071 for (i = 0; i < d->var_cnt; i++)
1073 struct variable *v = d->var[i].var;
1074 set_var_case_index (v, d->next_value_idx++);
1076 invalidate_proto (d);
1079 /* Returns the number of values occupied by the variables in
1080 dictionary D. All variables are considered if EXCLUDE_CLASSES
1081 is 0, or it may contain one or more of (1u << DC_ORDINARY),
1082 (1u << DC_SYSTEM), or (1u << DC_SCRATCH) to exclude the
1083 corresponding type of variable.
1085 The return value may be less than the number of values in one
1086 of dictionary D's cases (as returned by
1087 dict_get_next_value_idx) even if E is 0, because there may be
1088 gaps in D's cases due to deleted variables. */
1090 dict_count_values (const struct dictionary *d, unsigned int exclude_classes)
1095 assert ((exclude_classes & ~((1u << DC_ORDINARY)
1097 | (1u << DC_SCRATCH))) == 0);
1100 for (i = 0; i < d->var_cnt; i++)
1102 enum dict_class class = var_get_dict_class (d->var[i].var);
1103 if (!(exclude_classes & (1u << class)))
1109 /* Returns the case prototype that would result after deleting
1110 all variables from D that are not in one of the
1111 EXCLUDE_CLASSES and compacting the dictionary with
1114 The caller must unref the returned caseproto when it is no
1117 dict_get_compacted_proto (const struct dictionary *d,
1118 unsigned int exclude_classes)
1120 struct caseproto *proto;
1123 assert ((exclude_classes & ~((1u << DC_ORDINARY)
1125 | (1u << DC_SCRATCH))) == 0);
1127 proto = caseproto_create ();
1128 for (i = 0; i < d->var_cnt; i++)
1130 struct variable *v = d->var[i].var;
1131 if (!(exclude_classes & (1u << var_get_dict_class (v))))
1132 proto = caseproto_add_width (proto, var_get_width (v));
1137 /* Returns the SPLIT FILE vars (see cmd_split_file()). Call
1138 dict_get_split_cnt() to determine how many SPLIT FILE vars
1139 there are. Returns a null pointer if and only if there are no
1141 const struct variable *const *
1142 dict_get_split_vars (const struct dictionary *d)
1147 /* Returns the number of SPLIT FILE vars. */
1149 dict_get_split_cnt (const struct dictionary *d)
1151 return d->split_cnt;
1154 /* Removes variable V, which must be in D, from D's set of split
1157 dict_unset_split_var (struct dictionary *d, struct variable *v)
1161 assert (dict_contains_var (d, v));
1163 orig_count = d->split_cnt;
1164 d->split_cnt = remove_equal (d->split, d->split_cnt, sizeof *d->split,
1165 &v, compare_var_ptrs, NULL);
1166 if (orig_count != d->split_cnt)
1168 if (d->changed) d->changed (d, d->changed_data);
1169 /* We changed the set of split variables so invoke the
1171 if (d->callbacks && d->callbacks->split_changed)
1172 d->callbacks->split_changed (d, d->cb_data);
1176 /* Sets CNT split vars SPLIT in dictionary D. */
1178 dict_set_split_vars (struct dictionary *d,
1179 struct variable *const *split, size_t cnt)
1181 assert (cnt == 0 || split != NULL);
1186 d->split = xnrealloc (d->split, cnt, sizeof *d->split) ;
1187 memcpy (d->split, split, cnt * sizeof *d->split);
1195 if (d->changed) d->changed (d, d->changed_data);
1196 if ( d->callbacks && d->callbacks->split_changed )
1197 d->callbacks->split_changed (d, d->cb_data);
1200 /* Returns the file label for D, or a null pointer if D is
1201 unlabeled (see cmd_file_label()). */
1203 dict_get_label (const struct dictionary *d)
1208 /* Sets D's file label to LABEL, truncating it to a maximum of 60
1211 dict_set_label (struct dictionary *d, const char *label)
1214 d->label = label != NULL ? xstrndup (label, 60) : NULL;
1217 /* Returns the documents for D, or a null pointer if D has no
1218 documents. If the return value is nonnull, then the string
1219 will be an exact multiple of DOC_LINE_LENGTH bytes in length,
1220 with each segment corresponding to one line. */
1222 dict_get_documents (const struct dictionary *d)
1224 return ds_is_empty (&d->documents) ? NULL : ds_cstr (&d->documents);
1227 /* Sets the documents for D to DOCUMENTS, or removes D's
1228 documents if DOCUMENT is a null pointer. If DOCUMENTS is
1229 nonnull, then it should be an exact multiple of
1230 DOC_LINE_LENGTH bytes in length, with each segment
1231 corresponding to one line. */
1233 dict_set_documents (struct dictionary *d, const char *documents)
1237 ds_assign_cstr (&d->documents, documents != NULL ? documents : "");
1239 /* In case the caller didn't get it quite right, pad out the
1240 final line with spaces. */
1241 remainder = ds_length (&d->documents) % DOC_LINE_LENGTH;
1243 ds_put_char_multiple (&d->documents, ' ', DOC_LINE_LENGTH - remainder);
1246 /* Drops the documents from dictionary D. */
1248 dict_clear_documents (struct dictionary *d)
1250 ds_clear (&d->documents);
1253 /* Appends LINE to the documents in D. LINE will be truncated or
1254 padded on the right with spaces to make it exactly
1255 DOC_LINE_LENGTH bytes long. */
1257 dict_add_document_line (struct dictionary *d, const char *line)
1259 if (strlen (line) > DOC_LINE_LENGTH)
1261 /* Note to translators: "bytes" is correct, not characters */
1262 msg (SW, _("Truncating document line to %d bytes."), DOC_LINE_LENGTH);
1264 buf_copy_str_rpad (ds_put_uninit (&d->documents, DOC_LINE_LENGTH),
1265 DOC_LINE_LENGTH, line, ' ');
1268 /* Returns the number of document lines in dictionary D. */
1270 dict_get_document_line_cnt (const struct dictionary *d)
1272 return ds_length (&d->documents) / DOC_LINE_LENGTH;
1275 /* Copies document line number IDX from dictionary D into
1276 LINE, trimming off any trailing white space. */
1278 dict_get_document_line (const struct dictionary *d,
1279 size_t idx, struct string *line)
1281 assert (idx < dict_get_document_line_cnt (d));
1282 ds_assign_substring (line, ds_substr (&d->documents, idx * DOC_LINE_LENGTH,
1284 ds_rtrim (line, ss_cstr (CC_SPACES));
1287 /* Creates in D a vector named NAME that contains the CNT
1288 variables in VAR. Returns true if successful, or false if a
1289 vector named NAME already exists in D. */
1291 dict_create_vector (struct dictionary *d,
1293 struct variable **var, size_t cnt)
1298 for (i = 0; i < cnt; i++)
1299 assert (dict_contains_var (d, var[i]));
1301 if (dict_lookup_vector (d, name) == NULL)
1303 d->vector = xnrealloc (d->vector, d->vector_cnt + 1, sizeof *d->vector);
1304 d->vector[d->vector_cnt++] = vector_create (name, var, cnt);
1311 /* Creates in D a vector named NAME that contains the CNT
1312 variables in VAR. A vector named NAME must not already exist
1315 dict_create_vector_assert (struct dictionary *d,
1317 struct variable **var, size_t cnt)
1319 assert (dict_lookup_vector (d, name) == NULL);
1320 dict_create_vector (d, name, var, cnt);
1323 /* Returns the vector in D with index IDX, which must be less
1324 than dict_get_vector_cnt (D). */
1325 const struct vector *
1326 dict_get_vector (const struct dictionary *d, size_t idx)
1328 assert (idx < d->vector_cnt);
1330 return d->vector[idx];
1333 /* Returns the number of vectors in D. */
1335 dict_get_vector_cnt (const struct dictionary *d)
1337 return d->vector_cnt;
1340 /* Looks up and returns the vector within D with the given
1342 const struct vector *
1343 dict_lookup_vector (const struct dictionary *d, const char *name)
1346 for (i = 0; i < d->vector_cnt; i++)
1347 if (!strcasecmp (vector_get_name (d->vector[i]), name))
1348 return d->vector[i];
1352 /* Deletes all vectors from D. */
1354 dict_clear_vectors (struct dictionary *d)
1358 for (i = 0; i < d->vector_cnt; i++)
1359 vector_destroy (d->vector[i]);
1366 /* Returns D's attribute set. The caller may examine or modify
1367 the attribute set, but must not destroy it. Destroying D or
1368 calling dict_set_attributes for D will also destroy D's
1371 dict_get_attributes (const struct dictionary *d)
1373 return CONST_CAST (struct attrset *, &d->attributes);
1376 /* Replaces D's attributes set by a copy of ATTRS. */
1378 dict_set_attributes (struct dictionary *d, const struct attrset *attrs)
1380 attrset_destroy (&d->attributes);
1381 attrset_clone (&d->attributes, attrs);
1384 /* Returns true if D has at least one attribute in its attribute
1385 set, false if D's attribute set is empty. */
1387 dict_has_attributes (const struct dictionary *d)
1389 return attrset_count (&d->attributes) > 0;
1392 /* Called from variable.c to notify the dictionary that some property of
1393 the variable has changed */
1395 dict_var_changed (const struct variable *v)
1397 if ( var_has_vardict (v))
1399 const struct vardict_info *vardict = var_get_vardict (v);
1400 struct dictionary *d = vardict->dict;
1405 if (d->changed ) d->changed (d, d->changed_data);
1406 if ( d->callbacks && d->callbacks->var_changed )
1407 d->callbacks->var_changed (d, var_get_dict_index (v), d->cb_data);
1412 /* Called from variable.c to notify the dictionary that the variable's width
1415 dict_var_resized (const struct variable *v, int old_width)
1417 if ( var_has_vardict (v))
1419 const struct vardict_info *vardict = var_get_vardict (v);
1420 struct dictionary *d;
1424 if (d->changed) d->changed (d, d->changed_data);
1426 invalidate_proto (d);
1427 if ( d->callbacks && d->callbacks->var_resized )
1428 d->callbacks->var_resized (d, var_get_dict_index (v), old_width,
1433 /* Called from variable.c to notify the dictionary that the variable's display width
1436 dict_var_display_width_changed (const struct variable *v)
1438 if ( var_has_vardict (v))
1440 const struct vardict_info *vardict = var_get_vardict (v);
1441 struct dictionary *d;
1445 if (d->changed) d->changed (d, d->changed_data);
1446 if ( d->callbacks && d->callbacks->var_display_width_changed )
1447 d->callbacks->var_display_width_changed (d, var_get_dict_index (v), d->cb_data);
1451 /* Dictionary used to contain "internal variables". */
1452 static struct dictionary *internal_dict;
1454 /* Create a variable of the specified WIDTH to be used for internal
1455 calculations only. The variable is assigned case index CASE_IDX. */
1457 dict_create_internal_var (int case_idx, int width)
1459 if (internal_dict == NULL)
1460 internal_dict = dict_create ();
1464 static int counter = INT_MAX / 2;
1465 struct variable *var;
1468 if (++counter == INT_MAX)
1469 counter = INT_MAX / 2;
1471 sprintf (name, "$internal%d", counter);
1472 var = dict_create_var (internal_dict, name, width);
1475 set_var_case_index (var, case_idx);
1481 /* Destroys VAR, which must have been created with
1482 dict_create_internal_var(). */
1484 dict_destroy_internal_var (struct variable *var)
1488 dict_delete_var (internal_dict, var);
1490 /* Destroy internal_dict if it has no variables left, just so that
1491 valgrind --leak-check --show-reachable won't show internal_dict. */
1492 if (dict_get_var_cnt (internal_dict) == 0)
1494 dict_destroy (internal_dict);
1495 internal_dict = NULL;
1501 vardict_get_dict_index (const struct vardict_info *vardict)
1503 return vardict - vardict->dict->var;