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