/[ascend]/trunk/base/generic/compiler/value_type.h
ViewVC logotype

Contents of /trunk/base/generic/compiler/value_type.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 33 - (show annotations) (download) (as text)
Sun Dec 26 20:06:01 2004 UTC (15 years, 5 months ago) by ben.allan
File MIME type: text/x-chdr
File size: 20135 byte(s)
First pass at doxygenation -- mechanically putting in ** and where
most likely needed **< using sed. Lots of cleanup needed to
be really useful, including grouping data types and their
member methods into class-like documentation.
1 /**<
2 * Value Type Definitions
3 * by Tom Epperly
4 * Created: 1/16/90
5 * Version: $Revision: 1.17 $
6 * Version control file: $RCSfile: value_type.h,v $
7 * Date last modified: $Date: 1998/02/05 16:38:45 $
8 * Last modified by: $Author: ballan $
9 *
10 * This file is part of the Ascend Language Interpreter.
11 *
12 * Copyright (C) 1990, 1993, 1994 Thomas Guthrie Weidner Epperly
13 * Copyright (C) 1996 Benjamin Andrew Allan
14 *
15 * The Ascend Language Interpreter is free software; you can redistribute
16 * it and/or modify it under the terms of the GNU General Public License as
17 * published by the Free Software Foundation; either version 2 of the
18 * License, or (at your option) any later version.
19 *
20 * The Ascend Language Interpreter is distributed in hope that it will be
21 * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
22 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
23 * General Public License for more details.
24 *
25 * You should have received a copy of the GNU General Public License along
26 * with the program; if not, write to the Free Software Foundation, Inc., 675
27 * Mass Ave, Cambridge, MA 02139 USA. Check the file named COPYING.
28 */
29
30 /**<
31 * When #including value_type.h, make sure these files are #included first:
32 * #include "fractions.h"
33 * #include "compiler.h"
34 * #include "dimen.h"
35 * #include "types.h"
36 */
37
38
39 #ifndef __VALUE_TYPE_H_SEEN__
40 #define __VALUE_TYPE_H_SEEN__
41 /**< requires
42 # #include<stdio.h>
43 # #include"compiler.h"
44 # #include"list.h"
45 # #include"exprs.h"
46 # #include"functype.h"
47 # #include"dimen.h"
48 # #include"setinstval.h"
49 */
50
51 /**< Note:
52 * This file is a mess as we are passing around 24 byte structures rather than
53 * pointers to structures. ewww! Anytime you are returned a struct value_t
54 * from any of the functions in this file, remember to call DestroyValue
55 * when you are done with it since values may carry pointers to memory
56 * which this module owns and we don't want to leak memory.
57 *
58 * 3/96 Ben Allan: Added memory manager for struct value_t (internal).
59 * Use the Init, Destroy, and Report functions as required.
60 * Note to implementors: all the objects in a list_value list must be
61 * really allocated values and not just a piece of stack space.
62 *
63 * Added initialization for automatic variables conditional on
64 * NDEBUG flag. If it is not defined, this module is slower. If it
65 * IS defined, the module returns a UNION with parts uninitialized
66 * which really annoys memory auditors like purify.
67 */
68 enum evaluation_error{
69 type_conflict,
70 name_unfound, /**< inst of name not made yet */
71 incorrect_name, /**< name can never be found */
72 temporary_variable_reused,
73 undefined_value, /**< inst exists without being assigned */
74 dimension_conflict, /**< arithmetic error in dimensionality */
75 incorrect_such_that,
76 empty_choice, /**< CHOICE() on an empty set */
77 empty_intersection,
78 illegal_set_use /**< set used in list context */
79 };
80
81 enum value_kind {
82 real_value,
83 integer_value,
84 symbol_value,
85 boolean_value,
86 list_value, /**< keep set and list together */
87 set_value, /**< set is unique and sorted, or ought to be */
88 error_value
89 };
90
91 struct real_value_t{
92 double value;
93 CONST dim_type *dimp;
94 };
95
96 union value_union{
97 struct real_value_t r; /**< real value */
98 long i; /**< integer value */
99 int b; /**< boolean value */
100 symchar *sym_ptr; /**< symbol value */
101 struct set_t *sptr; /**< set structure */
102 struct gl_list_t *lvalues; /**< list of values */
103 enum evaluation_error t; /**< type of evaluation error */
104 };
105
106 /**< v.constant is true if the data from which the value is derived is
107 * impossible to change. Useful in some applications.
108 * At present it should only be examined for values of type
109 * real, boolean, integer, symbol. always true for sets at present.
110 * It really could have 31 other flags with 0x1 defined for the
111 * constant bitfield.
112 */
113 struct value_t {
114 enum value_kind t;
115 unsigned int constant; /**< since the union aligns on the double, this free */
116 union value_union u;
117 };
118 /**< Be sure that within value_t the union is aligned on an 8 byte boundary
119 * or alignment errors will occur. As of 3/96 it does on all
120 * CMU architectures (sparc, hp, alpha).
121 * Someone really should redo this struct value_t so that it doesn't
122 * waste so much space. It takes 24 bytes instead of the 16 that it
123 * should. BAA.
124 */
125
126 void InitValueManager(void);
127 /**<
128 * InitValueManager();
129 * Sets up value memory management. This must be called once
130 * before any value_t can be built, ideally at startup time.
131 * Do not call it again unless DestroyValueManager is called first
132 * and all outstanding value_t have been destroyed.
133 * If insufficient memory to compile anything at all, does exit(2).
134 */
135
136 void DestroyValueManager(void);
137 /**<
138 * DestroyValueManager();
139 * Destroy value memory management. This must be called to
140 * clean up before shutting down ASCEND.
141 * Do attempt to evaluate anything after you call this unless you
142 * have recalled InitValueManager.
143 */
144
145 void ReportValueManager(FILE*);
146 /**<
147 * ReportValueManager(f);
148 * FILE *f;
149 * Reports on the value manager to f.
150 */
151
152 /**< In the macro IVAL, x must be a struct value_t variable,
153 * NOT a pointer to same.
154 * If you want to init a pointer contents, y, use IVALPTR.
155 */
156 #ifdef NDEBUG
157 /**< do nothings */
158 #define IVAL(x)
159 #define IVALPTR(y)
160 #else
161 /**< init to 0 */
162 #define IVAL(x) ValInit(&(x))
163 #define IVALPTR(y) ValInit(y)
164 #endif
165 extern void ValInit(struct value_t *);
166 /**<
167 * ValInit(v)
168 * Inits the contents of v to 0.
169 * Do not call this function -- use the IVAL macros
170 */
171
172 /**<
173 * IVAL(stackvar) should be called on locally allocated
174 * value_t before any other action using them is taken.
175 * When NDEBUG is not defined, it causes the stack memory to be
176 * initialized to 0. Normally it is a do nothing macro.
177 * Proper initialization helps us separate signal from noise in
178 * gdb and purify.
179 */
180
181
182 #define ValueKind(v) ((v).t)
183 /**<
184 * macro ValueKind(v)
185 * struct value_t v;
186 * Return the value of a value_t.
187 */
188
189 #define IntegerValue(v) ((v).u.i)
190 /**<
191 * macro IntegerValue(v)
192 * struct value_t v;
193 * Return the value of an integer or integer_constant value_t.
194 */
195
196 #define RealValue(v) ((v).u.r.value)
197 /**<
198 * macro RealValue(v)
199 * struct value_t v;
200 * Return the real value of a real or real_constant value_t.
201 */
202
203 #define BooleanValue(v) ((v).u.b)
204 /**<
205 * macro BooleanValue(v)
206 * struct value_t v;
207 * Return the boolean value of a boolean or boolean_constant value_t.
208 */
209
210 #define RealValueDimensions(v) ((v).u.r.dimp)
211 /**<
212 * macro RealValueDimensions(v)
213 * struct value_t v;
214 * Return the dimensions of the real or real_constant value_t.
215 */
216
217 #define SetValue(v) ((v).u.sptr)
218 /**<
219 * macro SetValue(v)
220 * struct value_t v;
221 * Return the set value of a set value_t.
222 */
223
224 #define SymbolValue(v) ((v).u.sym_ptr)
225 /**<
226 * macro SymbolValue(v)
227 * struct value_t v;
228 * Return the symbol value of a symbol or symbol_constant value_t.
229 * This will be a symchar *.
230 */
231
232 #define ErrorValue(v) ((v).u.t)
233 /**<
234 * macro ErrorValue(v)
235 * struct value_t v;
236 * Return the error type.
237 */
238
239 extern struct value_t CopyValue(struct value_t);
240 /**<
241 * struct value_t CopyValue(value)
242 * struct value_t value;
243 * Return a copy of the value.
244 */
245
246 extern struct value_t CreateRealValue(double,CONST dim_type *,unsigned);
247 /**<
248 * struct value_t CreateRealValue(value,dim,constant)
249 * double value;
250 * const dim_type *dim;
251 * Create a real value node from the given value and dimensions.
252 * Value created is created marked as variable if constant is 0
253 * and constant if constant is 1.
254 */
255
256 extern struct value_t CreateIntegerValue(long,unsigned);
257 /**<
258 * struct value_t CreateIntegerValue(value,constant)
259 * long value;
260 * Create an integer value.
261 * Value created is created marked as variable if constant is 0
262 * and constant if constant is 1.
263 */
264
265 extern struct value_t CreateSymbolValue(symchar *,unsigned);
266 /**<
267 * struct value_t CreateSymbolValue(sym_ptr,constant)
268 * symchar *sym_ptr;
269 * Create a symbol value.
270 * Value created is created marked as variable if constant is 0
271 * and constant if constant is 1.
272 */
273
274 extern struct value_t CreateBooleanValue(int,unsigned);
275 /**<
276 * struct value_t CreateBooleanValue(truth,constant)
277 * int truth;
278 * Create a boolean value.
279 * Value created is created marked as variable if constant is 0
280 * and constant if constant is 1.
281 */
282
283 extern struct value_t CreateSetValue(struct set_t *);
284 /**<
285 * struct value_t CreateSetValue(sptr)
286 * struct set_t *sptr;
287 * Create a set value.
288 * Value created is created marked as constant. Mark it as variable
289 * if you need to.
290 * BUG BUG BUG. When we have variable sets, this needs to be cleaned up.
291 */
292
293 extern struct value_t CreateSetFromList(struct value_t);
294 /**<
295 * struct value_t CreateSetFromList(value)
296 * struct value_t value;
297 * Create a set from a list of values. Does not damage the list value given.
298 * Value created is created marked as constant. Mark it as variable
299 * if you need to.
300 * The values given may be int, str, or set of int/str, but must be of
301 * all the same type.
302 * BUG BUG BUG. When we have variable sets, this needs to be cleaned up.
303 */
304
305 extern struct value_t CreateOrderedSetFromList(struct value_t);
306 /**<
307 * struct value_t CreateOrderedSetFromList(value)
308 * struct value_t value;
309 * Create a set from a list of values. The set that will be created will
310 * NOT have unique elements, nor will the elments be sorted. In this way
311 * the set that is created behaves more like a list. Useful for processing
312 * arguments to multivariate functions. Appropriate errors are returned
313 * in the event of an error/inconsistency in the elements.
314 * Value created is created marked as variable. Mark it as constant
315 * if you need to.
316 */
317
318 extern struct value_t CreateErrorValue(enum evaluation_error);
319 /**<
320 * struct value_t CreateErrorValue(t)
321 * enum evaluation_error t;
322 * Create an error value.
323 * Value created is created marked as variable. Mark it as constant
324 * if you need to.
325 */
326
327 extern struct value_t CreateVacantListValue(void);
328 /**<
329 * struct value_t CreateEmptyListValue()
330 * Create a list value with no elements and minimal memory.
331 * Use this when you expect the list to die soon and without expansion.
332 * Value created is created marked as variable. Mark it as constant
333 * if you need to.
334 */
335
336 extern struct value_t CreateEmptyListValue(void);
337 /**<
338 * struct value_t CreateEmptyListValue()
339 * Create a list value with no elements but some memory.
340 * Value created is created marked as variable. Mark it as constant
341 * if you need to.
342 */
343
344 extern void AppendToListValue(struct value_t,struct value_t);
345 /**<
346 * void AppendToListValue(list,value)
347 * struct value_t list,value;
348 * Add "value" to the list value "list". This procedure will destory
349 * "value" if it needs to be.
350 */
351
352 #define IsConstantValue(v) ((v).constant)
353 /**<
354 * Return 1 if value is marked constant, 0 if not.
355 */
356
357 #define BothConstantValue(va,vb) ((va).constant && (vb).constant)
358 /**<
359 * Return 1 if both args marked constant, 0 if not.
360 */
361
362 #define SetConstantValue(v) ((v).constant = 1)
363 /**<
364 * Mark value as constant.
365 */
366
367 #define SetVariableValue(v) ((v).constant = 0)
368 /**<
369 * Mark value as constant.
370 */
371
372 extern void DestroyValue(struct value_t *);
373 /**<
374 * This function will deallocate the sets and lists of a value.
375 * Note this requires a pointer. This function does NOT free the
376 * pointer sent it. It DOES free all the values contained in the list of
377 * a list_value and calls DestroySet on a set_value. This function is
378 * potentially recursive.
379 */
380
381 /**<
382 * OPERATIONS: None of the operations below will ever deallocate memory.
383 */
384
385 extern struct value_t AddValues(struct value_t,struct value_t);
386 /**<
387 * struct value_t AddValues(value1,value2);
388 * struct value_t value1,value2;
389 * return value1 + value2
390 * If both args are constant, result is.
391 * Inputs and return must be real, integer or set.
392 * ifdef CATTEST, inputs may be symbols as well.
393 * Bad input will return error_value.
394 */
395
396 extern struct value_t SubtractValues(struct value_t,struct value_t);
397 /**<
398 * struct value_t SubtractValues(value1,value2)
399 * struct value_t value1,value2;
400 * return value1 - value2
401 * If both args are constant, result is.
402 * Inputs and return must be real, integer, boolean, symbol or list.
403 * Bad input will return error_value.
404 */
405
406 extern struct value_t MultiplyValues(struct value_t,struct value_t);
407 /**<
408 * struct value_t MultiplyValues(value1,value2)
409 * struct value_t value1,value2;
410 * return value1 * value2
411 * If both args are constant, result is.
412 * Inputs must be real or integer. If either is real, the result
413 * is real. Dimensionality of result will be derived from inputs.
414 * Inputs may also be sets if both value1 and 2 are sets.
415 * Result will then be the INTERSECTION of those sets.
416 * Bad input will return error_value.
417 */
418
419 extern struct value_t DivideValues(struct value_t,struct value_t);
420 /**<
421 * struct value_t DivideValues(struct value_t,struct value_t)
422 * struct value_t value1,value2;
423 * return value1 / value2
424 * If both args are constant, result is.
425 * Inputs must be real or integer. If either is real, the result
426 * is real. Dimensionality of result will be derived from inputs.
427 * If both input values are integer, integer division will be performed
428 * without promotion to real first and return value will be integer.
429 * Bad input will return error_value.
430 */
431
432 extern struct value_t PowerValues(struct value_t,struct value_t);
433 /**<
434 * struct value_t PowerValues(struct value_t,struct value_t)
435 * struct value_t value1,value2;
436 * return value1 ^ value2
437 * If both args are constant, result is.
438 * Performs integer and real power functions.
439 * IF value2 is nonintegral real, then value1 must be > 0 and DIMENSIONLESS.
440 * If both arguments are integer, result is.
441 */
442
443 extern struct value_t CardValues(struct value_t);
444 /**<
445 * struct value_t CardValues(value)
446 * struct value_t value;
447 * Return the cardinality of the set in value.
448 * Value is marked constant.
449 * Result is an integer.
450 */
451
452 extern struct value_t ChoiceValues(struct value_t);
453 /**<
454 * struct value_t ChoiceValues(value)
455 * struct value_t value;
456 * return an arbitrary but consistent member of the set in value.
457 * That is it always returns the same member from a given set.
458 * Value is marked constant.
459 */
460
461 #define FIRSTCHOICE 1
462 /**<
463 * If FIRSTCHOICE = 0 ChoiceValues uses a fancy method to pick the
464 * set member, else it will always return the first (in internal
465 * storage) set member. You can guess what our storage is.
466 * The DEFAULT value of this is 1 because it gives deterministic
467 * behavior that is platform independent across platforms with an
468 * identical collating sequence.
469 */
470
471 extern struct value_t SumValues(struct value_t);
472 /**<
473 * struct value_t SumValues(value)
474 * struct value_t value;
475 * Return the summation of the value.
476 * If args are constant, result is.
477 * Sums of reals and integers are promoted to real.
478 * Sums of reals must be dimensionally consistent or an error_value will
479 * be returned.
480 */
481
482 extern struct value_t ProdValues(struct value_t);
483 /**<
484 * struct value_t ProdValues(value)
485 * struct value_t value;
486 * Return the product of the value.
487 * If args are constant, result is.
488 *
489 */
490
491 extern struct value_t UnionValues(struct value_t);
492 /**<
493 * struct value_t UnionValues(value)
494 * struct value_t value;
495 * Return the union of the value.
496 * If args are constant, result is.
497 * Returns the set UNION of the set or list given.
498 */
499
500 extern struct value_t IntersectionValues(struct value_t);
501 /**<
502 * struct value_t IntersectionValues(value)
503 * struct value_t value;
504 * Return the intersection of the value. If value is an empty list,
505 * this returns an error.
506 * If args are constant, result is.
507 * Returns the set INTERSECTION of the set or list given.
508 */
509
510 extern struct value_t OrValues(struct value_t,struct value_t);
511 /**<
512 * struct value_t OrValues(value1,value2)
513 * struct value_t value1,value2;
514 * Return value1 OR value2. Arguments and result are boolean.
515 * If args are constant, result is.
516 */
517
518 extern struct value_t AndValues(struct value_t,struct value_t);
519 /**<
520 * struct value_t AndValues(value1,value2)
521 * struct value_t value1,value2;
522 * Return value1 AND value2. Arguments and result are boolean.
523 * If args are constant, result is.
524 */
525
526 extern struct value_t InValues(struct value_t,struct value_t);
527 /**<
528 * struct value_t InValues(value1,value2)
529 * struct value_t value1,value2;
530 * Return value1 IN value2.
531 * value1 is a integer or symbol. value2 is a set.
532 * Return is a boolean.
533 */
534
535 extern struct value_t EqualValues(struct value_t, struct value_t);
536 /**<
537 * struct value_t EqualValues(value1,value2)
538 * struct value_t value1,value2;
539 * Return value1 == value2. Result is boolean.
540 * Comparison exact, and values must be of same type except that
541 * integer/real comparisons are promoted as necessary.
542 * If args are constant, result is.
543 */
544
545 extern struct value_t NotEqualValues(struct value_t,struct value_t);
546 /**<
547 * struct value_t NotEqualValues(value1,value2)
548 * sturct value_t value1,value2;
549 * Return value1 != value2. Result is boolean.
550 * If args are constant, result is.
551 * Comparison exact, and values must be of same type except that
552 * integer/real comparisons are promoted as necessary.
553 * Has problems dealing with sets. This constitutes a bug to be fixed.
554 */
555
556 extern struct value_t LessValues(struct value_t,struct value_t);
557 /**<
558 * struct value_t LessValues(value1,value2)
559 * struct value_t value1,value2
560 * return value1 < value2. result is boolean.
561 * values must be real, integer,symbol. sets are not handled.
562 * Comparison exact, and values must be of same type except that
563 * integer/real comparisons are promoted as necessary.
564 * If args are constant, result is.
565 */
566
567 extern struct value_t GreaterValues(struct value_t,struct value_t);
568 /**<
569 * struct value_t GreaterValues(value1,value2)
570 * struct value_t value1,value2;
571 * return value1 > value2. result is boolean.
572 * values must be real, integer,symbol. sets are not handled.
573 * Comparison exact, and values must be of same type except that
574 * integer/real comparisons are promoted as necessary.
575 * If args are constant, result is.
576 */
577
578 extern struct value_t LessEqValues(struct value_t,struct value_t);
579 /**<
580 * struct value_t LessEqValues(value1,value2)
581 * struct value_t value1,value2
582 * return value1 <= value2. result is boolean.
583 * values must be real, integer,symbol. sets are not handled.
584 * Comparison exact, and values must be of same type except that
585 * integer/real comparisons are promoted as necessary.
586 * If args are constant, result is.
587 */
588
589 extern struct value_t GreaterEqValues(struct value_t,struct value_t);
590 /**<
591 * struct value_t GreaterEqValues(value1,value2)
592 * struct value_t value1,value2;
593 * return value1 >= value2. result is boolean.
594 * values must be real, integer,symbol. sets are not handled.
595 * Comparison exact, and values must be of same type except that
596 * integer/real comparisons are promoted as necessary.
597 * If args are constant, result is.
598 */
599
600 extern struct value_t ApplyFunction(struct value_t, CONST struct Func *);
601 /**<
602 * struct value_t ApplyFunction(value,f)
603 * struct value_t value;
604 * const struct Func *f;
605 * Apply the function f to value. Note all function evaluations require
606 * appropriately dimensioned (or wild) arguments.
607 * If args are constant, result is.
608 */
609
610 extern struct value_t NegateValue(struct value_t );
611 /**<
612 * struct value_t NegateValue(value)
613 * struct value_t value;
614 * return - value;
615 * If args are constant, result is.
616 */
617
618 extern struct value_t NotValue(struct value_t);
619 /**<
620 * struct value_t NotValue(value)
621 * struct value_t value;
622 * return NOT value; Value and result are boolean.
623 * If args are constant, result is.
624 */
625 #endif /**< __VALUE_TYPE_H_SEEN__ */

john.pye@anu.edu.au
ViewVC Help
Powered by ViewVC 1.1.22