1 /* PSPP - a program for statistical analysis. 2 Copyright (C) 1997-9, 2000, 2009, 2010, 2011, 2012, 2013, 3 2014, 2020 Free Software Foundation, Inc. 4 5 This program is free software: you can redistribute it and/or modify 6 it under the terms of the GNU General Public License as published by 7 the Free Software Foundation, either version 3 of the License, or 8 (at your option) any later version. 9 10 This program is distributed in the hope that it will be useful, 11 but WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 GNU General Public License for more details. 14 15 You should have received a copy of the GNU General Public License 16 along with this program. If not, see <http://www.gnu.org/licenses/>. */ 17 18 #ifndef DATA_VARIABLE_H 19 #define DATA_VARIABLE_H 1 20 21 #include <stddef.h> 22 #include <stdbool.h> 23 #include "data/dict-class.h" 24 #include "data/missing-values.h" 25 #include "data/val-type.h" 26 #include "data/settings.h" 27 28 /* Bitfields to identify traits of a variable */ 29 30 #define VAR_TRAIT_NAME 0x0001 31 #define VAR_TRAIT_WIDTH 0x0002 32 #define VAR_TRAIT_ROLE 0x0004 33 #define VAR_TRAIT_LABEL 0x0008 34 #define VAR_TRAIT_VALUE_LABELS 0x0010 35 #define VAR_TRAIT_MISSING_VALUES 0x0020 36 #define VAR_TRAIT_ALIGNMENT 0x0040 37 #define VAR_TRAIT_MEASURE 0x0080 38 #define VAR_TRAIT_DISPLAY_WIDTH 0x0100 39 #define VAR_TRAIT_LEAVE 0x0200 40 #define VAR_TRAIT_POSITION 0x0400 41 #define VAR_TRAIT_ATTRIBUTES 0x0800 42 #define VAR_TRAIT_PRINT_FORMAT 0x1000 43 #define VAR_TRAIT_WRITE_FORMAT 0x2000 44 45 46 union value; 47 48 /* Variables. 49 These functions should rarely be called directly: use 50 dict_create_var, dict_clone_var, or dict_delete_var 51 instead. */ 52 struct variable *var_create (const char *name, int width); 53 struct variable *var_clone (const struct variable *); 54 struct variable * var_ref (struct variable *) WARN_UNUSED_RESULT; 55 void var_unref (struct variable *); 56 57 /* Variable names. */ 58 const char *var_get_name (const struct variable *); 59 void var_set_name (struct variable *, const char *); 60 enum dict_class var_get_dict_class (const struct variable *); 61 62 int compare_vars_by_name (const void *, const void *, const void *); 63 unsigned hash_var_by_name (const void *, const void *); 64 65 int compare_var_ptrs_by_name (const void *, const void *, const void *); 66 unsigned hash_var_ptr_by_name (const void *, const void *); 67 68 int compare_var_ptrs_by_dict_index (const void *, const void *, const void *); 69 70 struct fmt_spec; 71 72 /* Types and widths of values associated with a variable. */ 73 enum val_type var_get_type (const struct variable *); 74 int var_get_width (const struct variable *); 75 void var_set_width (struct variable *, int width); 76 void var_set_width_and_formats (struct variable *v, int new_width, 77 const struct fmt_spec *print, const struct fmt_spec *write); 78 79 bool var_is_numeric (const struct variable *); 80 bool var_is_alpha (const struct variable *); 81 82 /* Variables' missing values. */ 83 const struct missing_values *var_get_missing_values (const struct variable *); 84 void var_set_missing_values (struct variable *, const struct missing_values *); 85 void var_clear_missing_values (struct variable *); 86 bool var_has_missing_values (const struct variable *); 87 88 bool var_is_value_missing (const struct variable *, const union value *, 89 enum mv_class); 90 bool var_is_num_missing (const struct variable *, double, enum mv_class); 91 bool var_is_str_missing (const struct variable *, const uint8_t[], enum mv_class); 92 93 /* Value labels. */ 94 const char *var_lookup_value_label (const struct variable *, 95 const union value *); 96 struct string; 97 void var_append_value_name (const struct variable *, const union value *, 98 struct string *); 99 void var_append_value_name__ (const struct variable *, const union value *, 100 enum settings_value_show, struct string *); 101 102 bool var_has_value_labels (const struct variable *); 103 const struct val_labs *var_get_value_labels (const struct variable *); 104 void var_set_value_labels (struct variable *, const struct val_labs *); 105 106 bool var_add_value_label (struct variable *, 107 const union value *, const char *); 108 void var_replace_value_label (struct variable *, 109 const union value *, const char *); 110 void var_clear_value_labels (struct variable *); 111 112 /* Print and write formats. */ 113 const struct fmt_spec *var_get_print_format (const struct variable *); 114 void var_set_print_format (struct variable *, const struct fmt_spec *); 115 const struct fmt_spec *var_get_write_format (const struct variable *); 116 void var_set_write_format (struct variable *, const struct fmt_spec *); 117 void var_set_both_formats (struct variable *, const struct fmt_spec *); 118 119 struct fmt_spec var_default_formats (int width); 120 121 /* Variable labels. */ 122 const char *var_to_string (const struct variable *); 123 const char *var_get_label (const struct variable *); 124 void var_set_label (struct variable *, const char *label); 125 void var_clear_label (struct variable *); 126 bool var_has_label (const struct variable *); 127 128 /* How data is measured. */ 129 enum measure 130 { 131 MEASURE_NOMINAL = 0, 132 MEASURE_ORDINAL = 1, 133 MEASURE_SCALE = 2, 134 n_MEASURES 135 }; 136 137 bool measure_is_valid (enum measure); 138 const char *measure_to_string (enum measure); 139 const char *measure_to_syntax (enum measure); 140 141 enum measure var_get_measure (const struct variable *); 142 void var_set_measure (struct variable *, enum measure); 143 144 enum measure var_default_measure (enum val_type); 145 146 /* Intended usage of a variable, for populating dialogs. */ 147 enum var_role 148 { 149 ROLE_INPUT, 150 ROLE_TARGET, 151 ROLE_BOTH, 152 ROLE_NONE, 153 ROLE_PARTITION, 154 ROLE_SPLIT 155 }; 156 157 bool var_role_is_valid (enum var_role); 158 const char *var_role_to_string (enum var_role); 159 const char *var_role_to_syntax (enum var_role); 160 161 enum var_role var_get_role (const struct variable *); 162 void var_set_role (struct variable *, enum var_role); 163 164 /* GUI display width. */ 165 int var_get_display_width (const struct variable *); 166 void var_set_display_width (struct variable *, int display_width); 167 168 int var_default_display_width (int width); 169 170 /* Alignment of data for display. */ 171 enum alignment 172 { 173 ALIGN_LEFT = 0, 174 ALIGN_RIGHT = 1, 175 ALIGN_CENTRE = 2 176 }; 177 178 bool alignment_is_valid (enum alignment); 179 const char *alignment_to_string (enum alignment); 180 const char *alignment_to_syntax (enum alignment); 181 182 enum alignment var_get_alignment (const struct variable *); 183 void var_set_alignment (struct variable *, enum alignment); 184 185 enum alignment var_default_alignment (enum val_type); 186 187 /* Whether variables' values should be preserved from case to 188 case. */ 189 bool var_get_leave (const struct variable *); 190 void var_set_leave (struct variable *, bool leave); 191 bool var_must_leave (const struct variable *); 192 193 /* Short names. */ 194 size_t var_get_short_name_cnt (const struct variable *); 195 const char *var_get_short_name (const struct variable *, size_t idx); 196 void var_set_short_name (struct variable *, size_t, const char *); 197 void var_clear_short_names (struct variable *); 198 199 /* Relationship with dictionary. */ 200 size_t var_get_dict_index (const struct variable *); 201 size_t var_get_case_index (const struct variable *); 202 203 /* Custom attributes. */ 204 struct attrset *var_get_attributes (const struct variable *); 205 void var_set_attributes (struct variable *, const struct attrset *); 206 bool var_has_attributes (const struct variable *); 207 208 /* Encoding. */ 209 const char *var_get_encoding (const struct variable *); 210 211 /* Function types. */ 212 typedef bool var_predicate_func (const struct variable *); 213 214 double var_force_valid_weight (const struct variable *wv, double w, 215 bool *warn_on_invalid); 216 217 #endif /* data/variable.h */ 218