pintos-os.org Git - pspp/blob - src/data/caseproto.h

   1 /* PSPP - a program for statistical analysis.
   2    Copyright (C) 2009, 2011 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_CASEPROTO_H
  18 #define DATA_CASEPROTO_H 1
  19
  20 #include <assert.h>
  21 #include <stdbool.h>
  22 #include <stddef.h>
  23 #include <stdlib.h>
  24
  25 #include "data/value.h"
  26 #include "libpspp/cast.h"
  27 #include "libpspp/compiler.h"
  28
  29 /* Case prototype.
  30
  31    A case prototype specifies the number and type of the values
  32    in a case.  It is essentially an array of integers, where the
  33    array index is an index into a case and each element
  34    represents the width of a value in a case.  Valid widths are:
  35
  36        * 0, indicating a numeric value.
  37
  38        * A positive integer between 1 and 32767, indicating the
  39          size in bytes of a string value.
  40
  41        * -1, indicating that the value at this index in the case
  42          is not used at all.  (This is rarely useful.)
  43
  44    Case prototypes are reference counted.  A newly created case
  45    prototype has a single owner (the code that created it),
  46    represented by an initial reference count of 1.  Other code
  47    that receives the case prototype may keep a virtual copy of it
  48    by calling caseproto_ref, which increments the case
  49    prototype's reference count.  When this is done, the case
  50    prototype becomes shared between its original owner and each
  51    piece of code that incremented the reference count.
  52
  53    Functions that modifying case prototypes automatically unshare
  54    them as necessary.  All of these functions potentially move
  55    the caseproto around in memory even when the case prototype is
  56    not shared.  Thus it is very important that every caller of a
  57    function that modifies a case prototype thereafter uses the returned
  58    caseproto instead of the one passed in as an argument.
  59
  60    Only the case prototype code should refer to caseproto members
  61    directly.  Other code should use the provided helper
  62    functions. */
  63 struct caseproto
  64   {
  65     size_t ref_cnt;             /* Reference count. */
  66
  67     /* Tracking of string widths.  Lazily maintained: when 'strings' is null
  68        and 'n_strings' is nonzero, the former must be regenerated. */
  69     size_t *strings;            /* Array of indexes of string widths. */
  70     size_t n_strings;           /* Number of string widths. */
  71
  72     /* Widths. */
  73     size_t n_widths;            /* Number of widths. */
  74     size_t allocated_widths;    /* Space allocated for 'widths' array. */
  75     short int widths[1];        /* Width of each case value. */
  76   };
  77
  78 struct pool;
  79
  80 /* Creation and destruction. */
  81 struct caseproto *caseproto_create (void) MALLOC_LIKE;
  82 static inline struct caseproto *caseproto_ref (const struct caseproto *) WARN_UNUSED_RESULT;
  83 struct caseproto *caseproto_ref_pool (const struct caseproto *, struct pool *) WARN_UNUSED_RESULT;
  84 static inline void caseproto_unref (struct caseproto *);
  85
  86 /* Inspecting stored widths.  */
  87 static inline int caseproto_get_width (const struct caseproto *, size_t idx);
  88 static inline size_t caseproto_get_n_widths (const struct caseproto *);
  89
  90 /* Adding and removing widths. */
  91 struct caseproto *caseproto_reserve (struct caseproto *, size_t n_widths)
  92   WARN_UNUSED_RESULT;
  93 struct caseproto *caseproto_add_width (struct caseproto *, int width)
  94   WARN_UNUSED_RESULT;
  95 struct caseproto *caseproto_set_width (struct caseproto *,
  96                                        size_t idx, int width)
  97   WARN_UNUSED_RESULT;
  98 struct caseproto *caseproto_insert_width (struct caseproto *,
  99                                           size_t before, int width)
 100   WARN_UNUSED_RESULT;
 101 struct caseproto *caseproto_remove_widths (struct caseproto *,
 102                                            size_t idx, size_t n)
 103   WARN_UNUSED_RESULT;
 104 struct caseproto *caseproto_move_widths (struct caseproto *,
 105                                          size_t old_start, size_t new_start,
 106                                          size_t n)
 107   WARN_UNUSED_RESULT;
 108
 109 /* Working with "union value" arrays. */
 110 bool caseproto_needs_init_values (const struct caseproto *);
 111 void caseproto_init_values (const struct caseproto *, union value[]);
 112 bool caseproto_try_init_values (const struct caseproto *, union value[]);
 113 void caseproto_reinit_values (const struct caseproto *old,
 114                               const struct caseproto *new, union value[]);
 115 void caseproto_destroy_values (const struct caseproto *, union value[]);
 116
 117 void caseproto_copy (const struct caseproto *, size_t idx, size_t count,
 118                      union value *dst, const union value *src);
 119
 120 /* Inspecting the cache of string widths.
 121
 122    (These functions are useful for allocating cases, which requires allocating
 123    a block of memory for each string value in the case.) */
 124 static inline size_t caseproto_get_n_strings (const struct caseproto *);
 125 static inline size_t caseproto_get_string_idx (const struct caseproto *,
 126                                                size_t idx1);
 127
 128 /* For use in assertions. */
 129 bool caseproto_range_is_valid (const struct caseproto *,
 130                                size_t ofs, size_t count);
 131 bool caseproto_is_conformable (const struct caseproto *a,
 132                                const struct caseproto *b);
 133 bool caseproto_range_equal (const struct caseproto *a, size_t a_start,
 134                             const struct caseproto *b, size_t b_start,
 135                             size_t n);
 136 bool caseproto_equal (const struct caseproto *, const struct caseproto *);
 137 \f
 138 /* Creation and destruction. */
 139
 140 void caseproto_free__ (struct caseproto *);
 141
 142 /* Increments case prototype PROTO's reference count and returns
 143    PROTO.  Afterward, PROTO is shared among its reference count
 144    holders. */
 145 static inline struct caseproto *
 146 caseproto_ref (const struct caseproto *proto_)
 147 {
 148   struct caseproto *proto = CONST_CAST (struct caseproto *, proto_);
 149   proto->ref_cnt++;
 150   return proto;
 151 }
 152
 153 /* Decrements case prototype PROTO's reference count.  Frees
 154    PROTO if its reference count drops to 0.
 155
 156    If PROTO is a null pointer, this function has no effect. */
 157 static inline void
 158 caseproto_unref (struct caseproto *proto)
 159 {
 160   if (proto != NULL && --proto->ref_cnt == 0)
 161     caseproto_free__ (proto);
 162 }
 163 \f
 164 /* Inspecting stored widths.  */
 165
 166 /* Returns case prototype PROTO's width with the given IDX.  IDX
 167    must be less than caseproto_get_n_widths(PROTO). */
 168 static inline int
 169 caseproto_get_width (const struct caseproto *proto, size_t idx)
 170 {
 171   assert (idx < proto->n_widths);
 172   return proto->widths[idx];
 173 }
 174
 175 /* Returns the number of widths in case prototype PROTO. */
 176 static inline size_t
 177 caseproto_get_n_widths (const struct caseproto *proto)
 178 {
 179   return proto->n_widths;
 180 }
 181 \f
 182 /* Inspecting the cache of long string widths. */
 183
 184 void caseproto_refresh_string_cache__ (const struct caseproto *);
 185
 186 /* Returns the number of strings in PROTO. */
 187 static inline size_t
 188 caseproto_get_n_strings (const struct caseproto *proto)
 189 {
 190   return proto->n_strings;
 191 }
 192
 193 /* Given string width IDX1, returns a value IDX2 for which
 194    caseproto_get_width(PROTO, IDX2) will return a value greater than 0.  IDX1
 195    must be less than caseproto_get_n_strings(PROTO), and IDX2 will be less than
 196    caseproto_get_n_widths(PROTO). */
 197 static inline size_t
 198 caseproto_get_string_idx (const struct caseproto *proto, size_t idx1)
 199 {
 200   if (proto->strings == NULL)
 201     caseproto_refresh_string_cache__ (proto);
 202
 203   assert (idx1 < proto->n_strings);
 204   return proto->strings[idx1];
 205 }
 206
 207 #endif /* data/caseproto.h */