1 /****************************************************************************
2 **
3 ** This file is part of GAP, a system for computational discrete algebra.
4 **
5 ** Copyright of GAP belongs to its developers, whose names are too numerous
6 ** to list here. Please refer to the COPYRIGHT file for details.
7 **
8 ** SPDX-License-Identifier: GPL-2.0-or-later
9 **
10 ** This file declares the functions for plain records.
11 */
12
13 #ifndef GAP_PRECORD_H
14 #define GAP_PRECORD_H
15
16 #include "objects.h"
17
18 /****************************************************************************
19 **
20 *F * * * * * * * * * standard functions for plain records * * * * * * * * * *
21 */
22
23
24 /****************************************************************************
25 **
26 *F NEW_PREC( <len> ) . . . . . . . . . . . . . . . . make a new plain record
27 **
28 ** 'NEW_PREC' returns a new plain record with room for <len> components.
29 ** Note that you still have to set the actual length once you have populated
30 ** the record!
31 */
32 Obj NEW_PREC(UInt len);
33
34
35 /****************************************************************************
36 **
37 *F IS_PREC( <rec> ) . . . . . . . . . check if <rec> is in plain record rep
38 */
IS_PREC(Obj rec)39 EXPORT_INLINE Int IS_PREC(Obj rec)
40 {
41 UInt tnum = TNUM_OBJ(rec);
42 return tnum == T_PREC || tnum == T_PREC+IMMUTABLE;
43 }
44
45
46 /****************************************************************************
47 **
48 *F IS_PREC_OR_COMOBJ( <list> ) . . . . . . . . . . . . . check type of <rec>
49 **
50 ** Checks if this is 'PREC'-like.
51 ** This function is used in a GAP_ASSERT checking if calling functions like
52 ** SET_ELM_PREC is acceptable on an Obj.
53 **
54 ** Unlike IS_PREC, this function also accepts component objects (which have
55 ** the same memory layout as precs), as the precs APIs using it for
56 ** assertion checks are in practice invoked on such objects, too.
57 */
IS_PREC_OR_COMOBJ(Obj rec)58 EXPORT_INLINE Int IS_PREC_OR_COMOBJ(Obj rec)
59 {
60 UInt tnum = TNUM_OBJ(rec);
61 return tnum == T_PREC || tnum == T_PREC+IMMUTABLE || tnum == T_COMOBJ;
62 }
63
64
65 /****************************************************************************
66 **
67 *F CAPACITY_PREC(<list>) . . . . . . . . . . . . capacity of a plain record
68 **
69 ** 'CAPACITY_PREC' returns the maximum capacity of a PREC.
70 **
71 */
CAPACITY_PREC(Obj rec)72 EXPORT_INLINE UInt CAPACITY_PREC(Obj rec)
73 {
74 return SIZE_OBJ(rec) / (2 * sizeof(Obj)) - 1;
75 }
76
77
78 /****************************************************************************
79 **
80 *F LEN_PREC( <rec> ) . . . . . . . . . number of components of plain record
81 **
82 ** 'LEN_PREC' returns the number of components of the plain record <rec>.
83 */
LEN_PREC(Obj rec)84 EXPORT_INLINE UInt LEN_PREC(Obj rec)
85 {
86 GAP_ASSERT(IS_PREC_OR_COMOBJ(rec));
87 return ((const UInt *)(CONST_ADDR_OBJ(rec)))[1];
88 }
89
90
91 /****************************************************************************
92 **
93 *F SET_LEN_PREC( <rec> ) . . . . . set number of components of plain record
94 **
95 ** 'SET_LEN_PREC' sets the number of components of the plain record <rec>.
96 */
SET_LEN_PREC(Obj rec,UInt nr)97 EXPORT_INLINE void SET_LEN_PREC(Obj rec, UInt nr)
98 {
99 GAP_ASSERT(IS_PREC_OR_COMOBJ(rec));
100 GAP_ASSERT(nr <= CAPACITY_PREC(rec));
101 ((UInt *)(ADDR_OBJ(rec)))[1] = nr;
102 }
103
104
105 /****************************************************************************
106 **
107 *F SET_RNAM_PREC( <rec>, <i>, <rnam> ) . set name of <i>-th record component
108 **
109 ** 'SET_RNAM_PREC' sets the name of the <i>-th record component of the
110 ** record <rec> to the record name <rnam>.
111 */
SET_RNAM_PREC(Obj rec,UInt i,Int rnam)112 EXPORT_INLINE void SET_RNAM_PREC(Obj rec, UInt i, Int rnam)
113 {
114 GAP_ASSERT(IS_PREC_OR_COMOBJ(rec));
115 GAP_ASSERT(i <= CAPACITY_PREC(rec));
116 *(Int *)(ADDR_OBJ(rec) + 2 * (i)) = rnam;
117 }
118
119
120 /****************************************************************************
121 **
122 *F GET_RNAM_PREC( <rec>, <i> ) . . . . . . . name of <i>-th record component
123 **
124 ** 'GET_RNAM_PREC' returns the record name of the <i>-th record component of
125 ** the record <rec>.
126 */
GET_RNAM_PREC(Obj rec,UInt i)127 EXPORT_INLINE Int GET_RNAM_PREC(Obj rec, UInt i)
128 {
129 GAP_ASSERT(IS_PREC_OR_COMOBJ(rec));
130 GAP_ASSERT(i <= LEN_PREC(rec));
131 return *(const Int *)(CONST_ADDR_OBJ(rec) + 2 * (i));
132 }
133
134
135 /****************************************************************************
136 **
137 *F SET_ELM_PREC( <rec>, <i>, <val> ) . set value of <i>-th record component
138 **
139 ** 'SET_ELM_PREC' sets the value of the <i>-th record component of the
140 ** record <rec> to the value <val>.
141 */
SET_ELM_PREC(Obj rec,UInt i,Obj val)142 EXPORT_INLINE void SET_ELM_PREC(Obj rec, UInt i, Obj val)
143 {
144 GAP_ASSERT(IS_PREC_OR_COMOBJ(rec));
145 GAP_ASSERT(i <= CAPACITY_PREC(rec));
146 *(ADDR_OBJ(rec)+2*(i)+1) = val;
147 }
148
149
150 /****************************************************************************
151 **
152 *F GET_ELM_PREC( <rec>, <i> ) . . . . . . value of <i>-th record component
153 **
154 ** 'GET_ELM_PREC' returns the value of the <i>-th record component of the
155 ** record <rec>.
156 */
GET_ELM_PREC(Obj rec,UInt i)157 EXPORT_INLINE Obj GET_ELM_PREC(Obj rec, UInt i)
158 {
159 GAP_ASSERT(IS_PREC_OR_COMOBJ(rec));
160 GAP_ASSERT(i <= LEN_PREC(rec));
161 return *(CONST_ADDR_OBJ(rec)+2*(i)+1);
162 }
163
164
165 /****************************************************************************
166 **
167 *F * * * * * * * * * standard functions for plain records * * * * * * * * * *
168 */
169
170 /****************************************************************************
171 **
172 *F PositionPRec( <rec>, <rnam>, <cleanup> )
173 *F . . . . . . . . . . . . . . . . . find a component name by binary search
174 **
175 ** Searches <rnam> in <rec>, returns the position where it is found, or 0
176 ** if it is not present.
177 ** If <cleanup> is nonzero, a dirty record is automatically cleaned up.
178 ** If <cleanup> is 0, this does not happen.
179 **
180 **
181 *F FindPRec( <rec>, <rnam>, <pos>, <cleanup> )
182 *F . . . . . . . . . . . . . . . . . find a component name by binary search
183 ** A deprecated variant of PositionPRec, which sets <pos> to the position
184 ** where the value is contained (or NULL if it is not present) and returns 1
185 ** if the record contained rnam, and 0 otherwise.
186 **/
187
188 UInt PositionPRec(Obj rec, UInt rnam, int cleanup);
189
FindPRec(Obj rec,UInt rnam,UInt * pos,int cleanup)190 EXPORT_INLINE UInt FindPRec(Obj rec, UInt rnam, UInt * pos, int cleanup)
191 {
192 *pos = PositionPRec(rec, rnam, cleanup);
193 return (*pos != 0);
194 }
195
196
197 /****************************************************************************
198 **
199 *F ElmPRec(<rec>,<rnam>) . . . . . . . select an element from a plain record
200 **
201 ** 'ElmPRec' returns the element, i.e., the value of the component, with the
202 ** record name <rnam> in the plain record <rec>. An error is signalled if
203 ** <rec> has no component with record name <rnam>.
204 */
205 Obj ElmPRec(Obj rec, UInt rnam);
206
207
208 /****************************************************************************
209 **
210 *F IsbPRec(<rec>,<rnam>) . . . . . test for an element from a plain record
211 **
212 ** 'IsbPRec' returns 1 if the record <rec> has a component with the record
213 ** name <rnam>, and 0 otherwise.
214 */
215 Int IsbPRec(Obj rec, UInt rnam);
216
217
218 /****************************************************************************
219 **
220 *F AssPRec(<rec>,<rnam>,<val>) . . . . . . . . . . assign to a plain record
221 **
222 ** 'AssPRec' assigns the value <val> to the record component with the record
223 ** name <rnam> in the plain record <rec>.
224 */
225 void AssPRec(Obj rec, UInt rnam, Obj val);
226
227
228 /****************************************************************************
229 **
230 *F UnbPRec(<rec>,<rnam>) . . . unbind a record component from a plain record
231 **
232 ** 'UnbPRec' removes the record component with the record name <rnam> from
233 ** the record <rec>.
234 */
235 void UnbPRec(Obj rec, UInt rnam);
236
237
238 /****************************************************************************
239 **
240 *F SortPRecRNam(<rec>, <inplace>) . . . . . . . sort the Rnams of the record
241 **
242 ** This is needed after the components of a record have been assigned
243 ** in not necessarily sorted order in the kernel. It is automatically
244 ** called on the first read access if necessary. See the top of "precord.c"
245 ** for a comment on lazy sorting.
246 ** If inplace is 1 then a slightly slower algorithm is used of
247 ** which we know that it does not produce garbage collections.
248 ** If inplace is 0 a garbage collection may be triggered.
249 **
250 */
251 void SortPRecRNam(Obj rec, int inplace);
252
253
254 #ifdef USE_THREADSAFE_COPYING
255 typedef struct TraversalState TraversalState;
256 void TraversePRecord(TraversalState * traversal, Obj obj);
257 void CopyPRecord(TraversalState * traversal, Obj copy, Obj original);
258 #endif
259
260
261 void MarkPRecSubBags(Obj bag);
262
263
264 /****************************************************************************
265 **
266 *F * * * * * * * * * * * * * initialize module * * * * * * * * * * * * * * *
267 */
268
269 /****************************************************************************
270 **
271 *F InitInfoPRecord() . . . . . . . . . . . . . . . . table of init functions
272 */
273 StructInitInfo * InitInfoPRecord ( void );
274
275
276 #endif // GAP_PRECORD_H
277