/[ascend]/trunk/ascend/compiler/units.h
ViewVC logotype

Contents of /trunk/ascend/compiler/units.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3355 - (show annotations) (download) (as text)
Mon Apr 16 05:56:23 2018 UTC (6 months ago) by jpye
File MIME type: text/x-chdr
File size: 8632 byte(s)
unexpected behaviour in FindOrDefineUnits eg with 'N/m)'

1 /* ASCEND modelling environment
2 Copyright (C) 2006, 2011 Carnegie Mellon University
3 Copyright (C) 1990, 1993, 1994 Thomas Guthrie Epperly
4
5 This program is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published by
7 the Free Software Foundation; either version 2, or (at your option)
8 any later version.
9
10 This program is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU General Public License for more details.
14
15 You should have received a copy of the GNU General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>.
17 *//**
18 @file
19 Ascend Units Type definitions.
20 *//*
21 by Tom Epperly 8/18/89
22 Last in CVS: $Revision: 1.10 $ $Date: 1998/02/05 16:38:40 $ $Author: ballan $
23 */
24
25 #ifndef ASC_UNITS_H
26 #define ASC_UNITS_H
27
28 #include <stdio.h>
29 #include <ascend/general/platform.h>
30 #include "compiler.h"
31 #include "fractions.h"
32 #include "dimen.h"
33
34 /** @addtogroup compiler_units Compiler Units
35 @{
36 */
37
38 #ifdef _HPUX_SOURCE
39 #define ACAST char *
40 #define BCAST char *
41 #else
42 #define ACAST const char *
43 #define BCAST char *
44 #endif
45 /**< to shut up the hp lexer */
46
47 /**
48 Value in system units = value in given units * conversion_factor.
49 */
50 struct Units {
51 double conversion_factor; /**< to convert from units to system units */
52 symchar *description; /**< description of units */
53 CONST dim_type *dim; /**< dimenions of units */
54 struct Units *next; /**< not for human consumption */
55 };
56
57 /**
58 Temporary structure for parsing unit definitions in ascParse.y.
59 */
60 struct UnitDefinition {
61 symchar *new_name;
62 CONST char *unitsexpr;
63 CONST char *filename;
64 int linenum;
65 };
66
67 #define UNITS_HASH_SIZE (1023)
68 /**<
69 size of the hash table for unit structs
70 */
71
72 /*
73 * Name of the basic SI units for the 10 dimensions.
74 * If you have better names for them, fix that here.
75 */
76 #define UNIT_BASE_MASS "kg"
77 /**< SI base unit symbol for mass. */
78 #define UNIT_BASE_QUANTITY "mol"
79 /**< SI base unit symbol for quantity. */
80 #define UNIT_BASE_LENGTH "m"
81 /**< SI base unit symbol for length. */
82 #define UNIT_BASE_TIME "s"
83 /**< SI base unit symbol for time. */
84 #define UNIT_BASE_TEMPERATURE "K"
85 /**< SI base unit symbol for temperature. */
86 #define UNIT_BASE_CURRENCY "USD"
87 /**< Base unit (non SI) for currency (US dollar) */
88 #define UNIT_BASE_ELECTRIC_CURRENT "A"
89 /**< SI base unit symbol for current. */
90 #define UNIT_BASE_LUMINOUS_INTENSITY "cd"
91 /**< SI base unit symbol for luminosity. */
92 #define UNIT_BASE_PLANE_ANGLE "rad"
93 /**< Base unit (non SI) for plane angle (radian). */
94 #define UNIT_BASE_SOLID_ANGLE "sr"
95 /**< Base unit (non SI) for solid angle (steradian). */
96
97 ASC_DLLSPEC struct Units *g_units_hash_table[];
98 /**<
99 * The hash table for unit structs.
100 */
101
102 ASC_DLLSPEC void InitUnitsTable(void);
103 /**<
104 This routine initializes some internal variables, so that all the
105 other units functions may be called. It must be called once and
106 only once when the program is starting up.
107 Must be called after dimensions table initiatialization.
108 */
109
110 ASC_DLLSPEC void DestroyUnitsTable(void);
111 /**<
112 This routine can be called to deallocate all of the units in the table.
113 */
114
115 ASC_DLLSPEC struct UnitDefinition *CreateUnitDef(symchar *new_name,
116 CONST char *unitsexpr,
117 CONST char *filename,
118 int linenum);
119 /**<
120 * Create a new unit definition.
121 * @param new_name Should be from the symbol table.
122 * @param unitsexpr A string that we will copy, so it does not
123 * need to be persistent.
124 * @param filename Should be persistent.
125 * @param linenum Line number.
126 */
127
128 ASC_DLLSPEC void DestroyUnitDef(struct UnitDefinition *udp);
129 /**<
130 * Destroys udp and its unitsexpr.
131 */
132
133 ASC_DLLSPEC void ProcessUnitDef(struct UnitDefinition *udp);
134 /**<
135 * Attempts to add the info in udp to the units table.
136 * messages to ascerr if not possible.
137 */
138
139 ASC_DLLSPEC CONST struct Units *LookupUnits(CONST char *c);
140 /**<
141 * Check the units library for units with a description string which
142 * matches c. If it is found, this function will return a non-NULL pointer;
143 * otherwise, it returns NULL to indicate that units c are undefined.
144 * c should not contain any blanks.
145 */
146
147 extern CONST struct Units *DefineUnits(symchar *c, double conv, CONST dim_type *dim);
148 /**<
149 * Define the units c with conversion factor conv and dimensions *dim.
150 * This assumes that *dim was the value returned by FindOrAddDim. This
151 * will check to prevent duplicate entries. The resulting unit structure is
152 * returned. If you enter a duplicate entry and the dimensions or conversion
153 * factor don't match, this function will return NULL. In addition to
154 * the user defined units there is a wild units type which conversion equal
155 * to one and wild dimensions. It is given the name "?".<br><br>
156 *
157 * c should not contain any spaces! It may add c to the symbol table if
158 * it is not already stored there.
159 *
160 * @bug Memory leak if hitting an empty hash bucket. buckets never deallocated
161 * except at shutdown anyway, so not a big deal. 7bytes/hit. Don't off hand
162 * know where to fix it. BAA 6-94
163 */
164
165 ASC_DLLSPEC CONST struct Units *FindOrDefineUnits(CONST char *c,
166 unsigned long * CONST pos,
167 int * CONST error_code);
168 /**<
169 * This function will attempt to parse the string c into a units
170 * description. If the unit type has been defined before, the corresponding
171 * units pointer will be returned. If this type hasn't been defined before,
172 * it will be defined and that pointer will be returned. If it is
173 * unable to parse this string it will return NULL. CheckUnitStr, below,
174 * can be used to diagnose why the unit didn't parse.
175 * This will not modify c in any way. It may add c to the symbol table.
176 * <pre>
177 * RETURN VALUE OF error_code
178 * 0 string is okay, value of pos not specified
179 * 1 undefined unit used in string, pos indicates the first
180 * letter of the first occurence of the undefined unit
181 * 2 unbalanced parenthesis, pos indicates the opening parenthesis
182 * that wasn't closed
183 * 3 illegal character, pos indicates the position of the offending
184 * character
185 * 4 illegal real value, pos indicates the first character of the
186 * real value
187 * 5 oversized identifier or real, pos indicates the start of the
188 * offending token
189 * 6 operator left out real followed by identifier or vice
190 * versa, pos indicates where an operator should have been
191 * inserted
192 * 7 term missing after *,/, or (.
193 * 8 missing term before *,/. pos is left at the operator
194 * 9 too many closing parens. pos is left at the extra paren.
195 * 10 bad fraction exponent. pos is at the left of the fraction field
196 * 11 incompatible unit redefinition. (internal use only; not seen).
197 * </pre>
198 */
199
200 ASC_DLLSPEC char **UnitsExplainError(CONST char *unitsexpr, int code, int pos);
201 /**<
202 Returns an array of strings which may be helpful in
203 explaining the error.
204 - errv[0] is a message.
205 - errv[1] is the unitsexpr.
206 - errv[2] is a pointer to the error -------^ line.
207 aligned with unitsexpr given.
208 The user should never change or free errv or its content,
209 nor should the user keep the pointers.
210
211 UPDATE (JP 2018): you can call UnitsExplainError(NULL,-1,0) to clear
212 memory allocated by this function, but you shouldn't free it yourself
213 because this function is storing the pointer in a global variable which
214 it later tries to access internally.
215 */
216
217 #define UnitsDescription(u) ((u)->description)
218 /**<
219 * Returns the string description attribute of a units structure.
220 */
221
222 #define UnitsConvFactor(u) ((u)->conversion_factor)
223 /**<
224 * Returns the conversion factor for a given units structure.
225 */
226
227 #define UnitsDimensions(u) ((u)->dim)
228 /**<
229 * Returns the dimensions of the units structure.
230 */
231
232 ASC_DLLSPEC char *UnitsStringSI(CONST struct Units *up);
233 /**<
234 * Returns the SI form of the units for the dimensionality of up.
235 * Wild = *, Dimensionless = "", NULL up --> NULL return.
236 * Caller is responsible for freeing the string returned.
237 */
238
239 ASC_DLLSPEC void DumpUnits(FILE *f);
240 /**< Dump all defined units to f. */
241
242 /* @} */
243
244 #endif /* ASC_UNITS_H */
245

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