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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 33 - (hide 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 ben.allan 33 /**<
2 aw0a 1 * 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 ben.allan 33 /**<
31 aw0a 1 * 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 ben.allan 33 /**< requires
42 aw0a 1 # #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 ben.allan 33 /**< Note:
52 aw0a 1 * 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 ben.allan 33 name_unfound, /**< inst of name not made yet */
71     incorrect_name, /**< name can never be found */
72 aw0a 1 temporary_variable_reused,
73 ben.allan 33 undefined_value, /**< inst exists without being assigned */
74     dimension_conflict, /**< arithmetic error in dimensionality */
75 aw0a 1 incorrect_such_that,
76 ben.allan 33 empty_choice, /**< CHOICE() on an empty set */
77 aw0a 1 empty_intersection,
78 ben.allan 33 illegal_set_use /**< set used in list context */
79 aw0a 1 };
80    
81     enum value_kind {
82     real_value,
83     integer_value,
84     symbol_value,
85     boolean_value,
86 ben.allan 33 list_value, /**< keep set and list together */
87     set_value, /**< set is unique and sorted, or ought to be */
88 aw0a 1 error_value
89     };
90    
91     struct real_value_t{
92     double value;
93     CONST dim_type *dimp;
94     };
95    
96     union value_union{
97 ben.allan 33 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 aw0a 1 };
105    
106 ben.allan 33 /**< v.constant is true if the data from which the value is derived is
107 aw0a 1 * 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 ben.allan 33 unsigned int constant; /**< since the union aligns on the double, this free */
116 aw0a 1 union value_union u;
117     };
118 ben.allan 33 /**< Be sure that within value_t the union is aligned on an 8 byte boundary
119 aw0a 1 * 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 ben.allan 33 /**<
128 aw0a 1 * 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 ben.allan 33 /**<
138 aw0a 1 * 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 ben.allan 33 /**<
147 aw0a 1 * ReportValueManager(f);
148     * FILE *f;
149     * Reports on the value manager to f.
150     */
151    
152 ben.allan 33 /**< In the macro IVAL, x must be a struct value_t variable,
153 aw0a 1 * NOT a pointer to same.
154     * If you want to init a pointer contents, y, use IVALPTR.
155     */
156     #ifdef NDEBUG
157 ben.allan 33 /**< do nothings */
158 aw0a 1 #define IVAL(x)
159     #define IVALPTR(y)
160     #else
161 ben.allan 33 /**< init to 0 */
162 aw0a 1 #define IVAL(x) ValInit(&(x))
163     #define IVALPTR(y) ValInit(y)
164     #endif
165     extern void ValInit(struct value_t *);
166 ben.allan 33 /**<
167 aw0a 1 * ValInit(v)
168     * Inits the contents of v to 0.
169     * Do not call this function -- use the IVAL macros
170     */
171    
172 ben.allan 33 /**<
173 aw0a 1 * 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 ben.allan 33 /**<
184 aw0a 1 * 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 ben.allan 33 /**<
191 aw0a 1 * 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 ben.allan 33 /**<
198 aw0a 1 * 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 ben.allan 33 /**<
205 aw0a 1 * 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 ben.allan 33 /**<
212 aw0a 1 * 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 ben.allan 33 /**<
219 aw0a 1 * 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 ben.allan 33 /**<
226 aw0a 1 * 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 ben.allan 33 /**<
234 aw0a 1 * 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 ben.allan 33 /**<
241 aw0a 1 * 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 ben.allan 33 /**<
248 aw0a 1 * 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 ben.allan 33 /**<
258 aw0a 1 * 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 ben.allan 33 /**<
267 aw0a 1 * 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 ben.allan 33 /**<
276 aw0a 1 * 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 ben.allan 33 /**<
285 aw0a 1 * 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 ben.allan 33 /**<
295 aw0a 1 * 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 ben.allan 33 /**<
307 aw0a 1 * 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 ben.allan 33 /**<
320 aw0a 1 * 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 ben.allan 33 /**<
329 aw0a 1 * 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 ben.allan 33 /**<
338 aw0a 1 * 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 ben.allan 33 /**<
346 aw0a 1 * 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 ben.allan 33 /**<
354 aw0a 1 * Return 1 if value is marked constant, 0 if not.
355     */
356    
357     #define BothConstantValue(va,vb) ((va).constant && (vb).constant)
358 ben.allan 33 /**<
359 aw0a 1 * Return 1 if both args marked constant, 0 if not.
360     */
361    
362     #define SetConstantValue(v) ((v).constant = 1)
363 ben.allan 33 /**<
364 aw0a 1 * Mark value as constant.
365     */
366    
367     #define SetVariableValue(v) ((v).constant = 0)
368 ben.allan 33 /**<
369 aw0a 1 * Mark value as constant.
370     */
371    
372     extern void DestroyValue(struct value_t *);
373 ben.allan 33 /**<
374 aw0a 1 * 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 ben.allan 33 /**<
382 aw0a 1 * 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 ben.allan 33 /**<
387 aw0a 1 * 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 ben.allan 33 /**<
398 aw0a 1 * 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 ben.allan 33 /**<
408 aw0a 1 * 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 ben.allan 33 /**<
421 aw0a 1 * 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 ben.allan 33 /**<
434 aw0a 1 * 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 ben.allan 33 /**<
445 aw0a 1 * 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 ben.allan 33 /**<
454 aw0a 1 * 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 ben.allan 33 /**<
463 aw0a 1 * 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 ben.allan 33 /**<
473 aw0a 1 * 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 ben.allan 33 /**<
484 aw0a 1 * 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 ben.allan 33 /**<
493 aw0a 1 * 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 ben.allan 33 /**<
502 aw0a 1 * 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 ben.allan 33 /**<
512 aw0a 1 * 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 ben.allan 33 /**<
520 aw0a 1 * 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 ben.allan 33 /**<
528 aw0a 1 * 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 ben.allan 33 /**<
537 aw0a 1 * 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 ben.allan 33 /**<
547 aw0a 1 * 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 ben.allan 33 /**<
558 aw0a 1 * 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 ben.allan 33 /**<
569 aw0a 1 * 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 ben.allan 33 /**<
580 aw0a 1 * 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 ben.allan 33 /**<
591 aw0a 1 * 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 ben.allan 33 /**<
602 aw0a 1 * 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 ben.allan 33 /**<
612 aw0a 1 * 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 ben.allan 33 /**<
620 aw0a 1 * 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 ben.allan 33 #endif /**< __VALUE_TYPE_H_SEEN__ */

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