PCOMPUTE works
[pspp] / src / data / format.h
1 /* PSPP - a program for statistical analysis.
2    Copyright (C) 1997-9, 2000, 2006, 2010, 2011, 2012 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_FORMAT_H
18 #define DATA_FORMAT_H 1
19
20 /* Display format types. */
21
22 #include <stdbool.h>
23 #include <stdint.h>
24 #include "data/val-type.h"
25 #include "libpspp/str.h"
26
27 struct fmt_settings;
28 struct msg_location;
29
30 /* How a format is going to be used. */
31 enum fmt_use
32   {
33     FMT_FOR_INPUT,           /* For parsing data input, e.g. data_in(). */
34     FMT_FOR_OUTPUT           /* For formatting data output, e.g. data_out(). */
35   };
36
37 /* Format type categories.
38
39    Each format is in exactly one category.  We give categories
40    bitwise disjoint values only to enable bitwise comparisons
41    against a mask of FMT_CAT_* values, not to allow multiple
42    categories per format. */
43 enum fmt_category
44   {
45     /* Numeric formats. */
46     FMT_CAT_BASIC          = 0x001,     /* Basic numeric formats. */
47     FMT_CAT_CUSTOM         = 0x002,     /* Custom currency formats. */
48     FMT_CAT_LEGACY         = 0x004,     /* Legacy numeric formats. */
49     FMT_CAT_BINARY         = 0x008,     /* Binary formats. */
50     FMT_CAT_HEXADECIMAL    = 0x010,     /* Hexadecimal formats. */
51     FMT_CAT_DATE           = 0x020,     /* Date formats. */
52     FMT_CAT_TIME           = 0x040,     /* Time formats. */
53     FMT_CAT_DATE_COMPONENT = 0x080,     /* Date component formats. */
54
55     /* String formats. */
56     FMT_CAT_STRING         = 0x100      /* String formats. */
57   };
58
59 /* Format type. */
60 enum ATTRIBUTE ((packed)) fmt_type
61   {
62 #define FMT(NAME, METHOD, IMIN, OMIN, IO, CATEGORY) FMT_##NAME,
63 #include "format.def"
64     FMT_NUMBER_OF_FORMATS,
65   };
66
67 /* Length of longest format specifier name,
68    not including terminating null. */
69 #define FMT_TYPE_LEN_MAX 8
70
71 /* Length of longest string representation of fmt_spec,
72    not including terminating null. */
73 #define FMT_STRING_LEN_MAX 32
74
75 /* Display format. */
76 struct fmt_spec
77   {
78     enum fmt_type type;         /* One of FMT_*. */
79     uint8_t d;                  /* Number of decimal places. */
80     uint16_t w;                 /* Width. */
81   };
82
83 /* Maximum width of any numeric format. */
84 #define FMT_MAX_NUMERIC_WIDTH 40
85
86 /* Constructing formats. */
87 struct fmt_spec fmt_for_input (enum fmt_type, int w, int d) PURE_FUNCTION;
88 struct fmt_spec fmt_for_output (enum fmt_type, int w, int d) PURE_FUNCTION;
89 struct fmt_spec fmt_for_output_from_input (const struct fmt_spec *,
90                                            const struct fmt_settings *);
91 struct fmt_spec fmt_default_for_width (int width);
92
93 /* Verifying formats. */
94 bool fmt_check (const struct fmt_spec *, enum fmt_use);
95 bool fmt_check_input (const struct fmt_spec *);
96 bool fmt_check_output (const struct fmt_spec *);
97 bool fmt_check_type_compat (const struct fmt_spec *, enum val_type);
98 bool fmt_check_width_compat (const struct fmt_spec *, int var_width);
99
100 char *fmt_check__ (const struct fmt_spec *, enum fmt_use);
101 char *fmt_check_type_compat__ (const struct fmt_spec *, enum val_type);
102 char *fmt_check_width_compat__ (const struct fmt_spec *, int var_width);
103
104 /* Working with formats. */
105 int fmt_var_width (const struct fmt_spec *);
106 char *fmt_to_string (const struct fmt_spec *, char s[FMT_STRING_LEN_MAX + 1]);
107 bool fmt_equal (const struct fmt_spec *, const struct fmt_spec *);
108 bool fmt_resize (struct fmt_spec *, int new_width);
109
110 void fmt_fix (struct fmt_spec *, enum fmt_use);
111 void fmt_fix_input (struct fmt_spec *);
112 void fmt_fix_output (struct fmt_spec *);
113
114 void fmt_change_width (struct fmt_spec *, int width, enum fmt_use);
115 void fmt_change_decimals (struct fmt_spec *, int decimals, enum fmt_use);
116
117 /* Format types. */
118 bool is_fmt_type (enum fmt_type);
119
120 const char *fmt_name (enum fmt_type) PURE_FUNCTION;
121 bool fmt_from_name (const char *name, enum fmt_type *);
122
123 bool fmt_takes_decimals (enum fmt_type) PURE_FUNCTION;
124
125 int fmt_min_width (enum fmt_type, enum fmt_use) PURE_FUNCTION;
126 int fmt_max_width (enum fmt_type, enum fmt_use) PURE_FUNCTION;
127 int fmt_max_decimals (enum fmt_type, int width, enum fmt_use) PURE_FUNCTION;
128 int fmt_min_input_width (enum fmt_type) PURE_FUNCTION;
129 int fmt_max_input_width (enum fmt_type) PURE_FUNCTION;
130 int fmt_max_input_decimals (enum fmt_type, int width) PURE_FUNCTION;
131 int fmt_min_output_width (enum fmt_type) PURE_FUNCTION;
132 int fmt_max_output_width (enum fmt_type) PURE_FUNCTION;
133 int fmt_max_output_decimals (enum fmt_type, int width) PURE_FUNCTION;
134 int fmt_step_width (enum fmt_type) PURE_FUNCTION;
135
136 bool fmt_is_string (enum fmt_type) PURE_FUNCTION;
137 bool fmt_is_numeric (enum fmt_type) PURE_FUNCTION;
138 enum fmt_category fmt_get_category (enum fmt_type) PURE_FUNCTION;
139
140 enum fmt_type fmt_input_to_output (enum fmt_type) PURE_FUNCTION;
141 bool fmt_usable_for_input (enum fmt_type) PURE_FUNCTION;
142
143 int fmt_to_io (enum fmt_type) PURE_FUNCTION;
144 bool fmt_from_io (int io, enum fmt_type *);
145 bool fmt_from_u32 (uint32_t, int var_width, bool loose, struct fmt_spec *);
146
147 const char *fmt_date_template (enum fmt_type, int width) PURE_FUNCTION;
148 const char *fmt_gui_name (enum fmt_type);
149 \f
150 /* A prefix or suffix for a numeric output format. */
151 struct fmt_affix
152   {
153     char *s;                    /* String contents of affix, in UTF-8. */
154     int width;                  /* Display width in columns (see wcwidth()). */
155   };
156
157 /* A numeric output style.  This can express the basic numeric formats (in the
158    FMT_CAT_BASIC category) and custom currency formats (FMT_CCx). */
159 struct fmt_number_style
160   {
161     struct fmt_affix neg_prefix; /* Negative prefix. */
162     struct fmt_affix prefix;     /* Prefix. */
163     struct fmt_affix suffix;     /* Suffix. */
164     struct fmt_affix neg_suffix; /* Negative suffix. */
165     char decimal;                /* Decimal point: '.' or ','. */
166     char grouping;               /* Grouping character: ',', '.', or 0. */
167
168     /* A fmt_affix may require more bytes than its display width; for example,
169        U+00A5 (¥) is 2 bytes in UTF-8 but occupies only one display column.
170        This member is the sum of the number of bytes required by all of the
171        fmt_affix members in this struct, minus their display widths.  Thus, it
172        can be used to size memory allocations: for example, the formatted
173        result of CCA20.5 requires no more than (20 + extra_bytes) bytes in
174        UTF-8. */
175     int extra_bytes;
176   };
177
178 struct fmt_number_style *fmt_number_style_from_string (const char *);
179 struct fmt_number_style *fmt_number_style_clone (
180   const struct fmt_number_style *);
181 void fmt_number_style_destroy (struct fmt_number_style *);
182
183 char *fmt_number_style_to_string (const struct fmt_number_style *);
184
185 int fmt_affix_width (const struct fmt_number_style *);
186 int fmt_neg_affix_width (const struct fmt_number_style *);
187 \f
188 /* Number of custom currency styles. */
189 #define FMT_N_CCS 5             /* FMT_CCA through FMT_CCE. */
190
191 struct fmt_settings
192   {
193     int epoch;                               /* 0 for default epoch. */
194     char decimal;                            /* '.' or ','. */
195     struct fmt_number_style *ccs[FMT_N_CCS]; /* CCA through CCE. */
196   };
197 #define FMT_SETTINGS_INIT { .decimal = '.' }
198
199 void fmt_settings_init (struct fmt_settings *);
200 void fmt_settings_uninit (struct fmt_settings *);
201 struct fmt_settings fmt_settings_copy (const struct fmt_settings *);
202
203 const struct fmt_number_style *fmt_settings_get_style (
204   const struct fmt_settings *, enum fmt_type);
205 int fmt_settings_get_epoch (const struct fmt_settings *);
206
207 void fmt_settings_set_cc (struct fmt_settings *, enum fmt_type,
208                           struct fmt_number_style *);
209 \f
210 extern const struct fmt_spec F_8_0 ;
211 extern const struct fmt_spec F_8_2 ;
212 extern const struct fmt_spec F_4_3 ;
213 extern const struct fmt_spec F_5_1 ;
214
215 #endif /* data/format.h */