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

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