1 /* PSPP - computes sample statistics.
2 Copyright (C) 1997-9, 2000 Free Software Foundation, Inc.
3 Written by Ben Pfaff <blp@gnu.org>.
5 This program is free software; you can redistribute it and/or
6 modify it under the terms of the GNU General Public License as
7 published by the Free Software Foundation; either version 2 of the
8 License, or (at your option) any later version.
10 This program is distributed in the hope that it will be useful, but
11 WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 General Public License for more details.
15 You should have received a copy of the GNU General Public License
16 along with this program; if not, write to the Free Software
17 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
22 #include <libpspp/assertion.h>
23 #include <libpspp/message.h>
25 #include <libpspp/alloc.h>
26 #include <libpspp/compiler.h>
27 #include "dictionary.h"
28 #include <libpspp/hash.h>
29 #include "identifier.h"
30 #include <libpspp/misc.h>
31 #include <libpspp/str.h>
32 #include "value-labels.h"
37 #define _(msgid) gettext (msgid)
39 /* Returns true if VAR_TYPE is a valid variable type. */
41 var_type_is_valid (enum var_type var_type)
43 return var_type == NUMERIC || var_type == ALPHA;
46 /* Returns an adjective describing the given variable TYPE,
47 suitable for use in phrases like "numeric variable". */
49 var_type_adj (enum var_type type)
51 return type == NUMERIC ? _("numeric") : _("string");
54 /* Returns a noun describing a value of the given variable TYPE,
55 suitable for use in phrases like "a number". */
57 var_type_noun (enum var_type type)
59 return type == NUMERIC ? _("number") : _("string");
62 /* Returns true if M is a valid variable measurement level,
65 measure_is_valid (enum measure m)
67 return m == MEASURE_NOMINAL || m == MEASURE_ORDINAL || m == MEASURE_SCALE;
70 /* Returns true if A is a valid alignment,
73 alignment_is_valid (enum alignment a)
75 return a == ALIGN_LEFT || a == ALIGN_RIGHT || a == ALIGN_CENTRE;
78 /* Assign auxiliary data AUX to variable V, which must not
79 already have auxiliary data. Before V's auxiliary data is
80 cleared, AUX_DTOR(V) will be called. */
82 var_attach_aux (struct variable *v,
83 void *aux, void (*aux_dtor) (struct variable *))
85 assert (v->aux == NULL);
88 v->aux_dtor = aux_dtor;
92 /* Remove auxiliary data, if any, from V, and returns it, without
93 calling any associated destructor. */
95 var_detach_aux (struct variable *v)
103 /* Clears auxiliary data, if any, from V, and calls any
104 associated destructor. */
106 var_clear_aux (struct variable *v)
111 if (v->aux_dtor != NULL)
117 /* This function is appropriate for use an auxiliary data
118 destructor (passed as AUX_DTOR to var_attach_aux()) for the
119 case where the auxiliary data should be passed to free(). */
121 var_dtor_free (struct variable *v)
126 /* Compares A and B, which both have the given WIDTH, and returns
127 a strcmp()-type result. */
129 compare_values (const union value *a, const union value *b, int width)
132 return a->f < b->f ? -1 : a->f > b->f;
134 return memcmp (a->s, b->s, MIN(MAX_SHORT_STRING, width));
137 /* Create a hash of v */
139 hash_value(const union value *v, int width)
144 id_hash = hsh_hash_double (v->f);
146 id_hash = hsh_hash_bytes (v->s, MIN(MAX_SHORT_STRING, width));
151 /* Return variable V's name. */
153 var_get_name (const struct variable *v)
158 /* Sets V's name to NAME. */
160 var_set_name (struct variable *v, const char *name)
162 assert (name[0] != '\0');
163 assert (lex_id_to_token (ss_cstr (name)) == T_ID);
165 str_copy_trunc (v->name, sizeof v->name, name);
168 /* Returns true if NAME is an acceptable name for a variable,
169 false otherwise. If ISSUE_ERROR is true, issues an
170 explanatory error message on failure. */
172 var_is_valid_name (const char *name, bool issue_error)
177 assert (name != NULL);
179 /* Note that strlen returns number of BYTES, not the number of
181 length = strlen (name);
183 plausible = var_is_plausible_name(name, issue_error);
189 if (!lex_is_id1 (name[0]))
192 msg (SE, _("Character `%c' (in %s), may not appear "
193 "as the first character in a variable name."),
199 for (i = 0; i < length; i++)
201 if (!lex_is_idn (name[i]))
204 msg (SE, _("Character `%c' (in %s) may not appear in "
215 Returns true if NAME is an plausible name for a variable,
216 false otherwise. If ISSUE_ERROR is true, issues an
217 explanatory error message on failure.
218 This function makes no use of LC_CTYPE.
221 var_is_plausible_name (const char *name, bool issue_error)
225 assert (name != NULL);
227 /* Note that strlen returns number of BYTES, not the number of
229 length = strlen (name);
233 msg (SE, _("Variable name cannot be empty string."));
236 else if (length > LONG_NAME_LEN)
239 msg (SE, _("Variable name %s exceeds %d-character limit."),
240 name, (int) LONG_NAME_LEN);
244 if (lex_id_to_token (ss_cstr (name)) != T_ID)
247 msg (SE, _("`%s' may not be used as a variable name because it "
248 "is a reserved word."), name);
255 /* A hsh_compare_func that orders variables A and B by their
258 compare_var_names (const void *a_, const void *b_, const void *aux UNUSED)
260 const struct variable *a = a_;
261 const struct variable *b = b_;
263 return strcasecmp (var_get_name (a), var_get_name (b));
266 /* A hsh_hash_func that hashes variable V based on its name. */
268 hash_var_name (const void *v_, const void *aux UNUSED)
270 const struct variable *v = v_;
272 return hsh_hash_case_string (var_get_name (v));
275 /* A hsh_compare_func that orders pointers to variables A and B
278 compare_var_ptr_names (const void *a_, const void *b_, const void *aux UNUSED)
280 struct variable *const *a = a_;
281 struct variable *const *b = b_;
283 return strcasecmp (var_get_name (*a), var_get_name (*b));
286 /* A hsh_hash_func that hashes pointer to variable V based on its
289 hash_var_ptr_name (const void *v_, const void *aux UNUSED)
291 struct variable *const *v = v_;
293 return hsh_hash_case_string (var_get_name (*v));
296 /* Returns the type of a variable with the given WIDTH. */
298 width_to_type (int width)
300 return width == 0 ? NUMERIC : ALPHA;
303 /* Returns the type of variable V. */
305 var_get_type (const struct variable *v)
307 return width_to_type (v->width);
310 /* Returns the width of variable V. */
312 var_get_width (const struct variable *v)
317 /* Sets the width of V to WIDTH. */
319 var_set_width (struct variable *v, int new_width)
321 enum var_type new_type = width_to_type (new_width);
323 if (mv_is_resizable (&v->miss, new_width))
324 mv_resize (&v->miss, new_width);
326 mv_init (&v->miss, new_width);
328 if (v->val_labs != NULL)
330 if (val_labs_can_set_width (v->val_labs, new_width))
331 val_labs_set_width (v->val_labs, new_width);
334 val_labs_destroy (v->val_labs);
339 if (var_get_type (v) != new_type)
341 v->print = (new_type == NUMERIC
342 ? fmt_for_output (FMT_F, 8, 2)
343 : fmt_for_output (FMT_A, new_width, 0));
346 else if (new_type == ALPHA)
348 v->print.w = v->print.type == FMT_AHEX ? new_width * 2 : new_width;
349 v->write.w = v->write.type == FMT_AHEX ? new_width * 2 : new_width;
352 v->width = new_width;
355 /* Returns true if variable V is numeric, false otherwise. */
357 var_is_numeric (const struct variable *v)
359 return var_get_type (v) == NUMERIC;
362 /* Returns true if variable V is a string variable, false
365 var_is_alpha (const struct variable *v)
367 return var_get_type (v) == ALPHA;
370 /* Returns true if variable V is a short string variable, false
373 var_is_short_string (const struct variable *v)
375 return v->width > 0 && v->width <= MAX_SHORT_STRING;
378 /* Returns true if variable V is a long string variable, false
381 var_is_long_string (const struct variable *v)
383 return v->width > MAX_SHORT_STRING;
386 /* Returns true if variable V is a very long string variable,
389 var_is_very_long_string (const struct variable *v)
391 return v->width > MAX_LONG_STRING;
394 /* Returns variable V's missing values. */
395 const struct missing_values *
396 var_get_missing_values (const struct variable *v)
401 /* Sets variable V's missing values to MISS, which must be of the
404 var_set_missing_values (struct variable *v, const struct missing_values *miss)
408 assert (v->width == mv_get_width (miss));
409 mv_copy (&v->miss, miss);
412 mv_init (&v->miss, v->width);
415 /* Sets variable V to have no user-missing values. */
417 var_clear_missing_values (struct variable *v)
419 var_set_missing_values (v, NULL);
422 /* Returns true if V has any user-missing values,
425 var_has_missing_values (const struct variable *v)
427 return !mv_is_empty (&v->miss);
430 /* Returns true if VALUE is system missing or user-missing value
431 for V, false otherwise. */
433 var_is_value_missing (const struct variable *v, const union value *value)
435 return mv_is_value_missing (&v->miss, value);
438 /* Returns true if D is system missing or a missing value in V,
440 V must be a numeric variable. */
442 var_is_num_missing (const struct variable *v, double d)
444 return mv_is_num_missing (&v->miss, d);
447 /* Returns true if S[] is a missing value for V, false otherwise.
448 S[] must contain exactly as many characters as V's width.
449 V must be a string variable. */
451 var_is_str_missing (const struct variable *v, const char s[])
453 return mv_is_str_missing (&v->miss, s);
456 /* Returns true if VALUE is a missing value for V, false
459 var_is_value_user_missing (const struct variable *v, const union value *value)
461 return mv_is_value_user_missing (&v->miss, value);
464 /* Returns true if D is a user-missing value for V, false
465 otherwise. V must be a numeric variable. */
467 var_is_num_user_missing (const struct variable *v, double d)
469 return mv_is_num_user_missing (&v->miss, d);
472 /* Returns true if S[] is a missing value for V, false otherwise.
473 V must be a string variable.
474 S[] must contain exactly as many characters as V's width. */
476 var_is_str_user_missing (const struct variable *v, const char s[])
478 return mv_is_str_user_missing (&v->miss, s);
481 /* Returns true if V is a numeric variable and VALUE is the
482 system missing value. */
484 var_is_value_system_missing (const struct variable *v,
485 const union value *value)
487 return mv_is_value_system_missing (&v->miss, value);
490 /* Print and write formats. */
492 /* Returns V's print format specification. */
493 const struct fmt_spec *
494 var_get_print_format (const struct variable *v)
499 /* Sets V's print format specification to PRINT, which must be a
500 valid format specification for outputting a variable of V's
503 var_set_print_format (struct variable *v, const struct fmt_spec *print)
505 assert (fmt_check_width_compat (print, v->width));
509 /* Returns V's write format specification. */
510 const struct fmt_spec *
511 var_get_write_format (const struct variable *v)
516 /* Sets V's write format specification to WRITE, which must be a
517 valid format specification for outputting a variable of V's
520 var_set_write_format (struct variable *v, const struct fmt_spec *write)
522 assert (fmt_check_width_compat (write, v->width));
526 /* Sets V's print and write format specifications to FORMAT,
527 which must be a valid format specification for outputting a
528 variable of V's width. */
530 var_set_both_formats (struct variable *v, const struct fmt_spec *format)
532 var_set_print_format (v, format);
533 var_set_write_format (v, format);
536 /* Returns V's variable label, or a null pointer if it has none. */
538 var_get_label (const struct variable *v)
543 /* Sets V's variable label to LABEL, stripping off leading and
544 trailing white space and truncating to 255 characters.
545 If LABEL is a null pointer or if LABEL is an empty string
546 (after stripping white space), then V's variable label (if
549 var_set_label (struct variable *v, const char *label)
556 struct substring s = ss_cstr (label);
557 ss_trim (&s, ss_cstr (CC_SPACES));
558 ss_truncate (&s, 255);
559 if (!ss_is_empty (s))
560 v->label = ss_xstrdup (s);
564 /* Removes any variable label from V. */
566 var_clear_label (struct variable *v)
568 var_set_label (v, NULL);
571 /* Returns true if V has a variable V,
574 var_has_label (const struct variable *v)
576 return v->label != NULL;
579 /* Returns V's measurement level. */
581 var_get_measure (const struct variable *v)
586 /* Sets V's measurement level to MEASURE. */
588 var_set_measure (struct variable *v, enum measure measure)
590 assert (measure_is_valid (measure));
591 v->measure = measure;
594 /* Returns V's display width, which applies only to GUIs. */
596 var_get_display_width (const struct variable *v)
598 return v->display_width;
601 /* Sets V's display width to DISPLAY_WIDTH. */
603 var_set_display_width (struct variable *v, int display_width)
605 v->display_width = display_width;
608 /* Returns V's display alignment, which applies only to GUIs. */
610 var_get_alignment (const struct variable *v)
615 /* Sets V's display alignment to ALIGNMENT. */
617 var_set_alignment (struct variable *v, enum alignment alignment)
619 assert (alignment_is_valid (alignment));
620 v->alignment = alignment;
623 /* Returns the number of "union value"s need to store a value of
626 var_get_value_cnt (const struct variable *v)
628 return v->width == 0 ? 1 : DIV_RND_UP (v->width, MAX_SHORT_STRING);
631 /* Return whether variable V's values should be preserved from
634 var_get_leave (const struct variable *v)
639 /* Returns V's short name, if it has one, or a null pointer
642 Short names are used only for system and portable file input
643 and output. They are upper-case only, not necessarily unique,
644 and limited to SHORT_NAME_LEN characters (plus a null
645 terminator). Any variable may have no short name, indicated
646 by returning a null pointer. */
648 var_get_short_name (const struct variable *v)
650 return v->short_name[0] != '\0' ? v->short_name : NULL;
653 /* Sets V's short_name to SHORT_NAME, truncating it to
654 SHORT_NAME_LEN characters and converting it to uppercase in
655 the process. Specifying a null pointer for SHORT_NAME clears
656 the variable's short name. */
658 var_set_short_name (struct variable *v, const char *short_name)
661 assert (short_name == NULL || var_is_plausible_name (short_name, false));
663 if (short_name != NULL)
665 str_copy_trunc (v->short_name, sizeof v->short_name, short_name);
666 str_uppercase (v->short_name);
669 v->short_name[0] = '\0';
672 /* Clears V's short name. */
674 var_clear_short_name (struct variable *v)
678 v->short_name[0] = '\0';
681 /* Sets V's short name to BASE, followed by a suffix of the form
682 _A, _B, _C, ..., _AA, _AB, etc. according to the value of
683 SUFFIX_NUMBER. Truncates BASE as necessary to fit. */
685 var_set_short_name_suffix (struct variable *v, const char *base,
688 char suffix[SHORT_NAME_LEN + 1];
689 char short_name[SHORT_NAME_LEN + 1];
694 assert (suffix_number >= 0);
697 var_set_short_name (v, base);
699 /* Compose suffix. */
700 start = end = suffix + sizeof suffix - 1;
704 *--start = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"[suffix_number % 26];
705 if (start <= suffix + 1)
706 msg (SE, _("Variable suffix too large."));
709 while (suffix_number > 0);
712 /* Append suffix to V's short name. */
713 str_copy_trunc (short_name, sizeof short_name, base);
715 if (len + strlen (short_name) > SHORT_NAME_LEN)
716 ofs = SHORT_NAME_LEN - len;
718 ofs = strlen (short_name);
719 strcpy (short_name + ofs, start);
722 var_set_short_name (v, short_name);
726 /* Returns the dictionary class corresponding to a variable named
729 dict_class_from_id (const char *name)
731 assert (name != NULL);
744 /* Returns the name of dictionary class DICT_CLASS. */
746 dict_class_to_name (enum dict_class dict_class)
751 return _("ordinary");
761 /* Return the number of bytes used when writing case_data for a variable
764 width_to_bytes(int width)
769 return MAX_SHORT_STRING ;
770 else if (width <= MAX_LONG_STRING)
771 return ROUND_UP (width, MAX_SHORT_STRING);
774 int chunks = width / EFFECTIVE_LONG_STRING_LENGTH ;
775 int remainder = width % EFFECTIVE_LONG_STRING_LENGTH ;
776 int bytes = remainder + (chunks * (MAX_LONG_STRING + 1) );
777 return ROUND_UP (bytes, MAX_SHORT_STRING);