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 (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 (struct fmt_spec, enum fmt_use);
  95 bool fmt_check_input (struct fmt_spec);
  96 bool fmt_check_output (struct fmt_spec);
  97 bool fmt_check_type_compat (struct fmt_spec, enum val_type);
  98 bool fmt_check_width_compat (struct fmt_spec, int var_width);
  99
 100 char *fmt_check__ (struct fmt_spec, enum fmt_use);
 101 char *fmt_check_input__ (struct fmt_spec);
 102 char *fmt_check_output__ (struct fmt_spec);
 103 char *fmt_check_type_compat__ (struct fmt_spec, const char *varname,
 104                                enum val_type);
 105 char *fmt_check_width_compat__ (struct fmt_spec, const char *varname,
 106                                 int var_width);
 107
 108 /* Working with formats. */
 109 int fmt_var_width (struct fmt_spec);
 110 char *fmt_to_string (struct fmt_spec, char s[FMT_STRING_LEN_MAX + 1]);
 111 bool fmt_equal (struct fmt_spec, struct fmt_spec);
 112 bool fmt_resize (struct fmt_spec *, int new_width);
 113
 114 void fmt_fix (struct fmt_spec *, enum fmt_use);
 115 void fmt_fix_input (struct fmt_spec *);
 116 void fmt_fix_output (struct fmt_spec *);
 117
 118 void fmt_change_width (struct fmt_spec *, int width, enum fmt_use);
 119 void fmt_change_decimals (struct fmt_spec *, int decimals, enum fmt_use);
 120
 121 /* Format types. */
 122 bool is_fmt_type (enum fmt_type);
 123
 124 const char *fmt_name (enum fmt_type) PURE_FUNCTION;
 125 bool fmt_from_name (const char *name, enum fmt_type *);
 126
 127 bool fmt_takes_decimals (enum fmt_type) PURE_FUNCTION;
 128
 129 int fmt_min_width (enum fmt_type, enum fmt_use) PURE_FUNCTION;
 130 int fmt_max_width (enum fmt_type, enum fmt_use) PURE_FUNCTION;
 131 int fmt_max_decimals (enum fmt_type, int width, enum fmt_use) PURE_FUNCTION;
 132 int fmt_min_input_width (enum fmt_type) PURE_FUNCTION;
 133 int fmt_max_input_width (enum fmt_type) PURE_FUNCTION;
 134 int fmt_max_input_decimals (enum fmt_type, int width) PURE_FUNCTION;
 135 int fmt_min_output_width (enum fmt_type) PURE_FUNCTION;
 136 int fmt_max_output_width (enum fmt_type) PURE_FUNCTION;
 137 int fmt_max_output_decimals (enum fmt_type, int width) PURE_FUNCTION;
 138 int fmt_step_width (enum fmt_type) PURE_FUNCTION;
 139
 140 bool fmt_is_string (enum fmt_type) PURE_FUNCTION;
 141 bool fmt_is_numeric (enum fmt_type) PURE_FUNCTION;
 142 enum fmt_category fmt_get_category (enum fmt_type) PURE_FUNCTION;
 143
 144 enum fmt_type fmt_input_to_output (enum fmt_type) PURE_FUNCTION;
 145 bool fmt_usable_for_input (enum fmt_type) PURE_FUNCTION;
 146
 147 int fmt_to_io (enum fmt_type) PURE_FUNCTION;
 148 bool fmt_from_io (int io, enum fmt_type *);
 149 bool fmt_from_u32 (uint32_t, int var_width, bool loose, struct fmt_spec *);
 150
 151 const char *fmt_date_template (enum fmt_type, int width) PURE_FUNCTION;
 152 const char *fmt_gui_name (enum fmt_type);
 153 \f
 154 /* A prefix or suffix for a numeric output format. */
 155 struct fmt_affix
 156   {
 157     char *s;                    /* String contents of affix, in UTF-8. */
 158     int width;                  /* Display width in columns (see wcwidth()). */
 159   };
 160
 161 /* A numeric output style.  This can express the basic numeric formats (in the
 162    FMT_CAT_BASIC category) and custom currency formats (FMT_CCx). */
 163 struct fmt_number_style
 164   {
 165     struct fmt_affix neg_prefix; /* Negative prefix. */
 166     struct fmt_affix prefix;     /* Prefix. */
 167     struct fmt_affix suffix;     /* Suffix. */
 168     struct fmt_affix neg_suffix; /* Negative suffix. */
 169     char decimal;                /* Decimal point: '.' or ','. */
 170     char grouping;               /* Grouping character: ',', '.', or 0. */
 171     bool include_leading_zero;   /* Format as ".5" or "0.5"? */
 172
 173     /* A fmt_affix may require more bytes than its display width; for example,
 174        U+00A5 (¥) is 2 bytes in UTF-8 but occupies only one display column.
 175        This member is the sum of the number of bytes required by all of the
 176        fmt_affix members in this struct, minus their display widths.  Thus, it
 177        can be used to size memory allocations: for example, the formatted
 178        result of CCA20.5 requires no more than (20 + extra_bytes) bytes in
 179        UTF-8. */
 180     int extra_bytes;
 181   };
 182
 183 struct fmt_number_style *fmt_number_style_from_string (const char *);
 184 struct fmt_number_style *fmt_number_style_clone (
 185   const struct fmt_number_style *);
 186 void fmt_number_style_destroy (struct fmt_number_style *);
 187
 188 char *fmt_number_style_to_string (const struct fmt_number_style *);
 189
 190 int fmt_affix_width (const struct fmt_number_style *);
 191 int fmt_neg_affix_width (const struct fmt_number_style *);
 192 \f
 193 /* Number of custom currency styles. */
 194 #define FMT_N_CCS 5             /* FMT_CCA through FMT_CCE. */
 195
 196 struct fmt_settings
 197   {
 198     int epoch;                               /* 0 for default epoch. */
 199     char decimal;                            /* '.' or ','. */
 200
 201     /* Format F, E, COMMA, and DOT with leading zero (e.g. "0.5" instead of
 202        ".5")? */
 203     bool include_leading_zero;
 204
 205     struct fmt_number_style *ccs[FMT_N_CCS]; /* CCA through CCE. */
 206   };
 207 #define FMT_SETTINGS_INIT { .decimal = '.' }
 208
 209 void fmt_settings_init (struct fmt_settings *);
 210 void fmt_settings_uninit (struct fmt_settings *);
 211 struct fmt_settings fmt_settings_copy (const struct fmt_settings *);
 212
 213 const struct fmt_number_style *fmt_settings_get_style (
 214   const struct fmt_settings *, enum fmt_type);
 215 int fmt_settings_get_epoch (const struct fmt_settings *);
 216
 217 void fmt_settings_set_cc (struct fmt_settings *, enum fmt_type,
 218                           struct fmt_number_style *);
 219 \f
 220 extern const struct fmt_spec F_8_0 ;
 221 extern const struct fmt_spec F_8_2 ;
 222 extern const struct fmt_spec F_4_3 ;
 223 extern const struct fmt_spec F_5_1 ;
 224
 225 #endif /* data/format.h */