PostgreSQL Source Code  git master
hstore.h
Go to the documentation of this file.
1 /*
2  * contrib/hstore/hstore.h
3  */
4 #ifndef __HSTORE_H__
5 #define __HSTORE_H__
6 
7 #include "fmgr.h"
8 #include "utils/array.h"
9 
10 
11 /*
12  * HEntry: there is one of these for each key _and_ value in an hstore
13  *
14  * the position offset points to the _end_ so that we can get the length
15  * by subtraction from the previous entry. the ISFIRST flag lets us tell
16  * whether there is a previous entry.
17  */
18 typedef struct
19 {
21 } HEntry;
22 
23 #define HENTRY_ISFIRST 0x80000000
24 #define HENTRY_ISNULL 0x40000000
25 #define HENTRY_POSMASK 0x3FFFFFFF
26 
27 /* note possible multiple evaluations, also access to prior array element */
28 #define HSE_ISFIRST(he_) (((he_).entry & HENTRY_ISFIRST) != 0)
29 #define HSE_ISNULL(he_) (((he_).entry & HENTRY_ISNULL) != 0)
30 #define HSE_ENDPOS(he_) ((he_).entry & HENTRY_POSMASK)
31 #define HSE_OFF(he_) (HSE_ISFIRST(he_) ? 0 : HSE_ENDPOS((&(he_))[-1]))
32 #define HSE_LEN(he_) (HSE_ISFIRST(he_) \
33  ? HSE_ENDPOS(he_) \
34  : HSE_ENDPOS(he_) - HSE_ENDPOS((&(he_))[-1]))
35 
36 /*
37  * determined by the size of "endpos" (ie HENTRY_POSMASK), though this is a
38  * bit academic since currently varlenas (and hence both the input and the
39  * whole hstore) have the same limit
40  */
41 #define HSTORE_MAX_KEY_LEN 0x3FFFFFFF
42 #define HSTORE_MAX_VALUE_LEN 0x3FFFFFFF
43 
44 typedef struct
45 {
46  int32 vl_len_; /* varlena header (do not touch directly!) */
47  uint32 size_; /* flags and number of items in hstore */
48  /* array of HEntry follows */
49 } HStore;
50 
51 /*
52  * It's not possible to get more than 2^28 items into an hstore, so we reserve
53  * the top few bits of the size field. See hstore_compat.c for one reason
54  * why. Some bits are left for future use here. MaxAllocSize makes the
55  * practical count limit slightly more than 2^28 / 3, or INT_MAX / 24, the
56  * limit for an hstore full of 4-byte keys and null values. Therefore, we
57  * don't explicitly check the format-imposed limit.
58  */
59 #define HS_FLAG_NEWVERSION 0x80000000
60 
61 #define HS_COUNT(hsp_) ((hsp_)->size_ & 0x0FFFFFFF)
62 #define HS_SETCOUNT(hsp_,c_) ((hsp_)->size_ = (c_) | HS_FLAG_NEWVERSION)
63 
64 
65 /*
66  * "x" comes from an existing HS_COUNT() (as discussed, <= INT_MAX/24) or a
67  * Pairs array length (due to MaxAllocSize, <= INT_MAX/40). "lenstr" is no
68  * more than INT_MAX, that extreme case arising in hstore_from_arrays().
69  * Therefore, this calculation is limited to about INT_MAX / 5 + INT_MAX.
70  */
71 #define HSHRDSIZE (sizeof(HStore))
72 #define CALCDATASIZE(x, lenstr) ( (x) * 2 * sizeof(HEntry) + HSHRDSIZE + (lenstr) )
73 
74 /* note multiple evaluations of x */
75 #define ARRPTR(x) ( (HEntry*) ( (HStore*)(x) + 1 ) )
76 #define STRPTR(x) ( (char*)(ARRPTR(x) + HS_COUNT((HStore*)(x)) * 2) )
77 
78 /* note multiple/non evaluations */
79 #define HSTORE_KEY(arr_,str_,i_) ((str_) + HSE_OFF((arr_)[2*(i_)]))
80 #define HSTORE_VAL(arr_,str_,i_) ((str_) + HSE_OFF((arr_)[2*(i_)+1]))
81 #define HSTORE_KEYLEN(arr_,i_) (HSE_LEN((arr_)[2*(i_)]))
82 #define HSTORE_VALLEN(arr_,i_) (HSE_LEN((arr_)[2*(i_)+1]))
83 #define HSTORE_VALISNULL(arr_,i_) (HSE_ISNULL((arr_)[2*(i_)+1]))
84 
85 /*
86  * currently, these following macros are the _only_ places that rely
87  * on internal knowledge of HEntry. Everything else should be using
88  * the above macros. Exception: the in-place upgrade in hstore_compat.c
89  * messes with entries directly.
90  */
91 
92 /*
93  * copy one key/value pair (which must be contiguous starting at
94  * sptr_) into an under-construction hstore; dent_ is an HEntry*,
95  * dbuf_ is the destination's string buffer, dptr_ is the current
96  * position in the destination. lots of modification and multiple
97  * evaluation here.
98  */
99 #define HS_COPYITEM(dent_,dbuf_,dptr_,sptr_,klen_,vlen_,vnull_) \
100  do { \
101  memcpy((dptr_), (sptr_), (klen_)+(vlen_)); \
102  (dptr_) += (klen_)+(vlen_); \
103  (dent_)++->entry = ((dptr_) - (dbuf_) - (vlen_)) & HENTRY_POSMASK; \
104  (dent_)++->entry = ((((dptr_) - (dbuf_)) & HENTRY_POSMASK) \
105  | ((vnull_) ? HENTRY_ISNULL : 0)); \
106  } while(0)
107 
108 /*
109  * add one key/item pair, from a Pairs structure, into an
110  * under-construction hstore
111  */
112 #define HS_ADDITEM(dent_,dbuf_,dptr_,pair_) \
113  do { \
114  memcpy((dptr_), (pair_).key, (pair_).keylen); \
115  (dptr_) += (pair_).keylen; \
116  (dent_)++->entry = ((dptr_) - (dbuf_)) & HENTRY_POSMASK; \
117  if ((pair_).isnull) \
118  (dent_)++->entry = ((((dptr_) - (dbuf_)) & HENTRY_POSMASK) \
119  | HENTRY_ISNULL); \
120  else \
121  { \
122  memcpy((dptr_), (pair_).val, (pair_).vallen); \
123  (dptr_) += (pair_).vallen; \
124  (dent_)++->entry = ((dptr_) - (dbuf_)) & HENTRY_POSMASK; \
125  } \
126  } while (0)
127 
128 /* finalize a newly-constructed hstore */
129 #define HS_FINALIZE(hsp_,count_,buf_,ptr_) \
130  do { \
131  int _buflen = (ptr_) - (buf_); \
132  if ((count_)) \
133  ARRPTR(hsp_)[0].entry |= HENTRY_ISFIRST; \
134  if ((count_) != HS_COUNT((hsp_))) \
135  { \
136  HS_SETCOUNT((hsp_),(count_)); \
137  memmove(STRPTR(hsp_), (buf_), _buflen); \
138  } \
139  SET_VARSIZE((hsp_), CALCDATASIZE((count_), _buflen)); \
140  } while (0)
141 
142 /* ensure the varlena size of an existing hstore is correct */
143 #define HS_FIXSIZE(hsp_,count_) \
144  do { \
145  int bl = (count_) ? HSE_ENDPOS(ARRPTR(hsp_)[2*(count_)-1]) : 0; \
146  SET_VARSIZE((hsp_), CALCDATASIZE((count_),bl)); \
147  } while (0)
148 
149 /* DatumGetHStoreP includes support for reading old-format hstore values */
150 extern PGDLLEXPORT HStore *hstoreUpgrade(Datum orig);
151 
152 #define DatumGetHStoreP(d) hstoreUpgrade(d)
153 
154 #define PG_GETARG_HSTORE_P(x) DatumGetHStoreP(PG_GETARG_DATUM(x))
155 
156 
157 /*
158  * Pairs is a "decompressed" representation of one key/value pair.
159  * The two strings are not necessarily null-terminated.
160  */
161 typedef struct
162 {
163  char *key;
164  char *val;
165  size_t keylen;
166  size_t vallen;
167  bool isnull; /* value is null? */
168  bool needfree; /* need to pfree the value? */
169 } Pairs;
170 
171 extern PGDLLEXPORT int hstoreUniquePairs(Pairs *a, int32 l, int32 *buflen);
172 extern PGDLLEXPORT HStore *hstorePairs(Pairs *pairs, int32 pcount, int32 buflen);
173 
174 extern PGDLLEXPORT size_t hstoreCheckKeyLen(size_t len);
175 extern PGDLLEXPORT size_t hstoreCheckValLen(size_t len);
176 
177 extern PGDLLEXPORT int hstoreFindKey(HStore *hs, int *lowbound, char *key, int keylen);
178 extern PGDLLEXPORT Pairs *hstoreArrayToPairs(ArrayType *a, int *npairs);
179 
180 #define HStoreContainsStrategyNumber 7
181 #define HStoreExistsStrategyNumber 9
182 #define HStoreExistsAnyStrategyNumber 10
183 #define HStoreExistsAllStrategyNumber 11
184 #define HStoreOldContainsStrategyNumber 13 /* backwards compatibility */
185 
186 /*
187  * defining HSTORE_POLLUTE_NAMESPACE=0 will prevent use of old function names;
188  * for now, we default to on for the benefit of people restoring old dumps
189  */
190 #ifndef HSTORE_POLLUTE_NAMESPACE
191 #define HSTORE_POLLUTE_NAMESPACE 1
192 #endif
193 
194 #if HSTORE_POLLUTE_NAMESPACE
195 #define HSTORE_POLLUTE(newname_,oldname_) \
196  PG_FUNCTION_INFO_V1(oldname_); \
197  extern PGDLLEXPORT Datum newname_(PG_FUNCTION_ARGS); \
198  Datum oldname_(PG_FUNCTION_ARGS) { return newname_(fcinfo); } \
199  extern int no_such_variable
200 #else
201 #define HSTORE_POLLUTE(newname_,oldname_) \
202  extern int no_such_variable
203 #endif
204 
205 #endif /* __HSTORE_H__ */
unsigned int uint32
Definition: c.h:518
signed int int32
Definition: c.h:508
#define PGDLLEXPORT
Definition: c.h:1334
PGDLLEXPORT size_t hstoreCheckKeyLen(size_t len)
Definition: hstore_io.c:404
PGDLLEXPORT HStore * hstorePairs(Pairs *pairs, int32 pcount, int32 buflen)
Definition: hstore_io.c:445
PGDLLEXPORT int hstoreUniquePairs(Pairs *a, int32 l, int32 *buflen)
Definition: hstore_io.c:356
PGDLLEXPORT size_t hstoreCheckValLen(size_t len)
Definition: hstore_io.c:424
PGDLLEXPORT Pairs * hstoreArrayToPairs(ArrayType *a, int *npairs)
Definition: hstore_op.c:73
PGDLLEXPORT int hstoreFindKey(HStore *hs, int *lowbound, char *key, int keylen)
Definition: hstore_op.c:36
PGDLLEXPORT HStore * hstoreUpgrade(Datum orig)
int a
Definition: isn.c:68
const void size_t len
uintptr_t Datum
Definition: postgres.h:64
Definition: hstore.h:19
uint32 entry
Definition: hstore.h:20
Definition: hstore.h:45
int32 vl_len_
Definition: hstore.h:46
uint32 size_
Definition: hstore.h:47
Definition: hstore.h:162
char * val
Definition: hstore.h:164
bool isnull
Definition: hstore.h:167
size_t keylen
Definition: hstore.h:165
char * key
Definition: hstore.h:163
bool needfree
Definition: hstore.h:168
size_t vallen
Definition: hstore.h:166