1 /* PSPP - a program for statistical analysis. 2 Copyright (C) 2004, 2007, 2009, 2010, 2011, 2012, 2013 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_DICTIONARY_H 18 #define DATA_DICTIONARY_H 1 19 20 #include <stdbool.h> 21 #include <stddef.h> 22 #include "data/case.h" 23 #include "data/dict-class.h" 24 25 struct string; 26 struct ccase; 27 28 /* Creating dictionaries. */ 29 struct dictionary *dict_create (const char *encoding); 30 struct dictionary *dict_clone (const struct dictionary *) WARN_UNUSED_RESULT; 31 struct dictionary *dict_ref (struct dictionary *s) WARN_UNUSED_RESULT; 32 33 34 /* Clearing and destroying dictionaries. */ 35 void dict_clear (struct dictionary *); 36 void dict_unref (struct dictionary *); 37 38 /* Common ways to access variables. */ 39 struct variable *dict_lookup_var (const struct dictionary *, const char *); 40 struct variable *dict_lookup_var_assert (const struct dictionary *, 41 const char *); 42 struct variable *dict_get_var (const struct dictionary *, size_t position); 43 size_t dict_get_var_cnt (const struct dictionary *); 44 45 /* Other access to variables. */ 46 bool dict_contains_var (const struct dictionary *, const struct variable *); 47 void dict_get_vars (const struct dictionary *, 48 const struct variable ***vars, size_t *cnt, 49 enum dict_class exclude); 50 void dict_get_vars_mutable (const struct dictionary *, 51 struct variable ***vars, size_t *cnt, 52 enum dict_class exclude); 53 54 /* Creating variables. */ 55 struct variable *dict_create_var (struct dictionary *, const char *, 56 int width); 57 struct variable *dict_create_var_assert (struct dictionary *, const char *, 58 int width); 59 struct variable *dict_clone_var (struct dictionary *, const struct variable *); 60 struct variable *dict_clone_var_assert (struct dictionary *, 61 const struct variable *); 62 struct variable *dict_clone_var_as (struct dictionary *, 63 const struct variable *, const char *); 64 struct variable *dict_clone_var_as_assert (struct dictionary *, 65 const struct variable *, 66 const char *); 67 68 struct variable *dict_clone_var_in_place_assert (struct dictionary *, 69 const struct variable *); 70 71 /* Deleting variables. */ 72 void dict_delete_var (struct dictionary *, struct variable *); 73 void dict_delete_vars (struct dictionary *, 74 struct variable *const *, size_t count); 75 void dict_delete_consecutive_vars (struct dictionary *, 76 size_t idx, size_t count); 77 void dict_delete_scratch_vars (struct dictionary *); 78 79 /* Changing the order of variables. */ 80 void dict_reorder_var (struct dictionary *, struct variable *, 81 size_t new_index); 82 void dict_reorder_vars (struct dictionary *, 83 struct variable *const *, size_t count); 84 85 /* Variable names. */ 86 bool dict_try_rename_var (struct dictionary *, 87 struct variable *, const char *); 88 void dict_rename_var (struct dictionary *, struct variable *, const char *); 89 bool dict_rename_vars (struct dictionary *, 90 struct variable **, char **new_names, 91 size_t count, char **err_name); 92 char *dict_make_unique_var_name (const struct dictionary *, const char *hint, 93 unsigned long int *num_start); 94 95 bool dict_get_names_must_be_ids (const struct dictionary *); 96 void dict_set_names_must_be_ids (struct dictionary *, bool); 97 98 /* Weight variable. */ 99 double dict_get_case_weight (const struct dictionary *, 100 const struct ccase *, bool *); 101 struct variable *dict_get_weight (const struct dictionary *); 102 void dict_set_weight (struct dictionary *, struct variable *); 103 const struct fmt_spec *dict_get_weight_format (const struct dictionary *); 104 105 /* Filter variable. */ 106 struct variable *dict_get_filter (const struct dictionary *); 107 void dict_set_filter (struct dictionary *, struct variable *); 108 109 /* Case limit (N OF CASES). */ 110 casenumber dict_get_case_limit (const struct dictionary *); 111 void dict_set_case_limit (struct dictionary *, casenumber); 112 113 /* Size of cases for this dictionary. */ 114 const struct caseproto *dict_get_proto (const struct dictionary *); 115 int dict_get_next_value_idx (const struct dictionary *); 116 size_t dict_get_case_size (const struct dictionary *); 117 118 /* Making this dictionary's cases smaller (if some variables were 119 deleted). */ 120 size_t dict_count_values (const struct dictionary *, 121 unsigned int exclude_classes); 122 void dict_compact_values (struct dictionary *); 123 struct caseproto *dict_get_compacted_proto (const struct dictionary *, 124 unsigned int exclude_classes); 125 126 /* SPLIT FILE variables. */ 127 const struct variable *const *dict_get_split_vars (const struct dictionary *); 128 size_t dict_get_split_cnt (const struct dictionary *); 129 void dict_set_split_vars (struct dictionary *, 130 struct variable *const *, size_t cnt); 131 132 /* File label. */ 133 const char *dict_get_label (const struct dictionary *); 134 void dict_set_label (struct dictionary *, const char *); 135 136 /* Documents. */ 137 #define DOC_LINE_LENGTH 80 /* Fixed length of document lines. */ 138 139 const struct string_array *dict_get_documents (const struct dictionary *); 140 void dict_set_documents (struct dictionary *, const struct string_array *); 141 void dict_set_documents_string (struct dictionary *, const char *); 142 void dict_clear_documents (struct dictionary *); 143 144 bool dict_add_document_line (struct dictionary *, const char *, 145 bool issue_warning); 146 size_t dict_get_document_line_cnt (const struct dictionary *); 147 const char *dict_get_document_line (const struct dictionary *, size_t); 148 149 /* Vectors. */ 150 bool dict_create_vector (struct dictionary *, const char *name, 151 struct variable **, size_t cnt); 152 void dict_create_vector_assert (struct dictionary *, const char *name, 153 struct variable **, size_t cnt); 154 const struct vector *dict_get_vector (const struct dictionary *, size_t idx); 155 size_t dict_get_vector_cnt (const struct dictionary *); 156 const struct vector *dict_lookup_vector (const struct dictionary *, 157 const char *name); 158 void dict_clear_vectors (struct dictionary *); 159 160 /* Multiple response sets. */ 161 const struct mrset *dict_get_mrset (const struct dictionary *, size_t idx); 162 size_t dict_get_n_mrsets (const struct dictionary *); 163 const struct mrset *dict_lookup_mrset (const struct dictionary *, 164 const char *name); 165 166 bool dict_add_mrset (struct dictionary *, struct mrset *); 167 bool dict_delete_mrset (struct dictionary *, const char *name); 168 void dict_clear_mrsets (struct dictionary *); 169 170 /* Attributes. */ 171 struct attrset *dict_get_attributes (const struct dictionary *); 172 void dict_set_attributes (struct dictionary *, const struct attrset *); 173 bool dict_has_attributes (const struct dictionary *); 174 175 /* Data encoding. */ 176 const char *dict_get_encoding (const struct dictionary *d); 177 178 bool dict_id_is_valid (const struct dictionary *, const char *id, 179 bool issue_error); 180 181 /* Internal variables. */ 182 struct variable *dict_create_internal_var (int case_idx, int width); 183 void dict_destroy_internal_var (struct variable *); 184 185 /* Functions to be called upon dictionary changes. */ 186 struct dict_callbacks 187 { 188 void (*var_added) (struct dictionary *, int, void *); 189 void (*var_deleted) (struct dictionary *, const struct variable *, 190 int dict_index, int case_index, void *); 191 void (*var_changed) (struct dictionary *, int, unsigned int, const struct variable *, void *); 192 void (*weight_changed) (struct dictionary *, int, void *); 193 void (*filter_changed) (struct dictionary *, int, void *); 194 void (*split_changed) (struct dictionary *, void *); 195 }; 196 197 void dict_set_callbacks (struct dictionary *, const struct dict_callbacks *, 198 void *); 199 void dict_copy_callbacks (struct dictionary *, const struct dictionary *); 200 201 void dict_set_change_callback (struct dictionary *d, 202 void (*changed) (struct dictionary *, void*), 203 void *data); 204 205 206 /* Debug use only. */ 207 void dict_dump (const struct dictionary *); 208 209 #endif /* data/dictionary.h */ 210