/[ascend]/trunk/tcltk98/generic/interface/UnitsProc.h
ViewVC logotype

Contents of /trunk/tcltk98/generic/interface/UnitsProc.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 67 - (show annotations) (download) (as text)
Wed Nov 30 16:31:29 2005 UTC (16 years, 5 months ago) by johnpye
File MIME type: text/x-chdr
File size: 14031 byte(s)
Standardised the "if seen" #defines to [ASC|ASCTK|ASCPY|ASCXX]_FILENAME_H
Fixed compile on FC3
1 /*
2 * UnitsProc.h
3 * by Kirk Abbott and Ben Allan
4 * Created: 1/94
5 * Version: $Revision: 1.11 $
6 * Version control file: $RCSfile: UnitsProc.h,v $
7 * Date last modified: $Date: 2003/08/23 18:43:09 $
8 * Last modified by: $Author: ballan $
9 *
10 * This file is part of the ASCEND Tcl/Tk interface
11 *
12 * Copyright 1997, Carnegie Mellon University
13 *
14 * The ASCEND Tcl/Tk interface is free software; you can redistribute
15 * it and/or modify it under the terms of the GNU General Public License as
16 * published by the Free Software Foundation; either version 2 of the
17 * License, or (at your option) any later version.
18 *
19 * The ASCEND Tcl/Tk interface is distributed in hope that it will be
20 * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
22 * General Public License for more details.
23 *
24 * You should have received a copy of the GNU General Public License
25 * along with the program; if not, write to the Free Software Foundation,
26 * Inc., 675 Mass Ave, Cambridge, MA 02139 USA. Check the file named
27 * COPYING. COPYING is found in ../compiler.
28 */
29
30 /** @file
31 * Units procedures.
32 * <pre>
33 * Display precision is handled here. (see Set/Get_Prec below.)
34 *
35 * Base units are the units which correspond to and are displayed
36 * instead of single DIMENSIONs. Numbers which are dimensional but have
37 * no display unit of corresponding dimensionality will be shown in the
38 * appropriate combination of base units, aka fundamental units.
39 * This should keep the number of DIM/units on the internal lists from
40 * getting out of hand when talking about multipliers, derivatives, etc
41 *
42 * Requires: #include "utilities/ascConfig.h"
43 * #include "compiler/interface.h"
44 * #include "compiler/instance_enum.h"
45 * #include "general/list.h"
46 * #include "compiler/dimen.h"
47 * #include "compiler/units.h"
48 * </pre>
49 */
50
51 #ifndef ASCTK_UNITSPROC_H
52 #define ASCTK_UNITSPROC_H
53
54 extern struct Units * g_base_units[NUM_DIMENS];
55 /**< These are the working base units. */
56
57 extern struct Units * g_SI_units[NUM_DIMENS];
58 /**<
59 * These are the backup base units. If a number cannot be displayed
60 * due to floating point error in conversion, it will be displayed in
61 * these units (all of which have conversion factors of 1.)
62 */
63
64 extern char *Asc_UnitValue(CONST struct Instance *i);
65 /**<
66 * Return a pointer to a string containing the value of i in display
67 * units/precision provided i is REAL_ATOM_INST, REAL_INST, REL_INST,
68 * INTEGER_INST, INTEGER_ATOM_INST, otherwise returns null.
69 * This string is not yours and the pointer will only be valid until
70 * the next call to Unit_Value.<br><br>
71 *
72 * The contents of the string are: value units<br><br>
73 *
74 * where value will be to UPREC places for reals, or all places for int*
75 * and units will be consistent with value. Wild dim'd numbers will
76 * have * for units and dimensionless numbers will have nothing. If
77 * Unit_Value is called on an invalid instance kind, return is NULL.
78 * If instance is !AtomAssigned, return is "UNDEFINED units"
79 * To destroy the current display string, call is Unit_Value(NULL).
80 */
81
82 extern char *Asc_UnitlessValue(CONST struct Instance *i, int SI);
83 /**<
84 * <!-- Unitless_Value(i,SI); -->
85 * Like Unit_Value, except that contents of the string returned
86 * do not include the units and the printed value in the string
87 * will be in SI instead of display units if SI is TRUE.
88 * If the number cannot be printed in display units, the SI value
89 * is printed instead with a warning on stderr.
90 */
91
92 extern char *Asc_UnitString(CONST struct Instance *i, int SI);
93 /**<
94 * <!-- Unit_String(i,SI); -->
95 * Like Unit_Value, except that contents of the string returned
96 * do not include the value of the instance. If SI is TRUE, units
97 * returned will be SI units rather than units window specified units.
98 */
99
100 extern char *Asc_UnitDimString(dim_type *dimp, int SI);
101 /**<
102 * <!-- Unit_String(dimp,SI); -->
103 * Like Unit_String, except that the instance is not needed.
104 * If SI is TRUE, units returned will be SI units rather than units
105 * window specified units.
106 * If dimp is NULL, return is NULL.
107 */
108
109 extern int Asc_UnitConvert(struct Units *u, double in,
110 double *out, int direction);
111 /**<
112 * <!-- Unit_Convert(u,in,out,direction); -->
113 * Attempts to unit convert the value in double to/from the units given.
114 * If args are wrong or conversion fails, return value is 1 and *out
115 * may be undefined.
116 * If successful return is 0 and out has the resulting value.
117 * If direction is 0 convert in{units} to out{si}.
118 * If direction != 0 convert in{si} to out{units}.
119 */
120
121 extern int Asc_UnitSetRealAtomValue(CONST struct Instance *i,
122 char *valuestr,
123 char *unitstr,
124 unsigned depth);
125 /**<
126 * Sets value of a real or real atom instance if units are
127 * dimensionally compatible and value fits within a double in SI units.
128 * If atom is wild, dimensionality will be set by this call unless
129 * the second char argument is null/empty/"*".
130 * Return codes:
131 * - 0 => ok
132 * - 1 => Unparseable units given- Not assigned
133 * - 2 => Dimensionally incompatible units- Not assigned
134 * - 3 => Overflow in converting to SI value- Not assigned
135 * - 4 => Called with non-real instance
136 * - 5 => Unparseable value given- Not assigned
137 * depth is passed on to the SetRealAtomValue call inside this call.
138 */
139
140 extern int Asc_UnitGetCPrec(void);
141 /**< Return the current display precision for use in C. */
142
143 extern int Asc_UnitDestroyDisplayList(ClientData cdata, Tcl_Interp *interp,
144 int argc, CONST84 char *argv[]);
145 /**<
146 * Trash the interface units lookup structure. Don't call this if you
147 * aren't about to exit or bad things will happen when next you display.<br><br>
148 *
149 * Registered as: u_destroy_units
150 */
151
152 extern int Asc_UnitDefaultBaseUnits(ClientData cdata, Tcl_Interp *interp,
153 int argc, CONST84 char *argv[]);
154 /**<
155 * Establishes the short form of SI mks as the display
156 * defaults for units. (kg,s,m,K,C,mole,cd,CR)
157 * it needs to be updated if a new dimension is added.
158 * Cares not what args it gets.<br><br>
159 *
160 * Registered as: u_setSIdef
161 */
162
163 extern int Asc_UnitGetBaseUnits(ClientData cdata, Tcl_Interp *interp,
164 int argc, CONST84 char *argv[]);
165 /**<
166 * Returns a list of the current default base units.
167 * If none have been set, calls Unit_default_baseunits before going on.<br><br>
168 *
169 * Registered as: u_getbasedef
170 */
171
172 extern int Asc_UnitDump(ClientData cdata, Tcl_Interp *interp,
173 int argc, char CONST84 *argv[]);
174 /**<
175 * Spew the units defined to stdout, stderr, or a list
176 * if pretty is present. Option 2 list will have nice whitespace
177 * u_dump 2 --> {dimenId unitname convfactor unitsSI dimen} tuples<br><br>
178 *
179 * Registered as: u_dump <0,1,2> [pretty]
180 */
181
182 extern int Asc_DimenDump(ClientData cdata, Tcl_Interp *interp,
183 int argc, CONST84 char *argv[]);
184 /**<
185 * Spew the dimens registered to stdout, stderr, or a list.<br><br>
186 *
187 * Registered as: u_dims <0,1,2>
188 */
189
190 extern int Asc_DimenRelCheck(ClientData cdata, Tcl_Interp *interp,
191 int argc, CONST84 char *argv[]);
192 /**<
193 * Sets relation dim checking to on (1) or off (0).
194 * Applies only to the checking performed in making unit strings.<br><br>
195 *
196 * Registered as: u_dim_setverify $dimconsistency
197 */
198
199 extern int Asc_UnitBaseDimToNum(ClientData cdata, Tcl_Interp *interp,
200 int argc, CONST84 char *argv[]);
201 /**<
202 * Returns the number of a simple dimension.<br><br>
203 *
204 * Registered as: u_dim2num <dimname>
205 */
206
207 extern int Asc_UnitNumToBaseDim(ClientData cdata, Tcl_Interp *interp,
208 int argc, CONST84 char *argv[]);
209 /**<
210 * Returns the Dim of a corresponding number.<br><br>
211 *
212 * Registered as: u_num2dim <dimindex>
213 */
214
215 extern int Asc_UnitMatchBaseDim(ClientData cdata, Tcl_Interp *interp,
216 int argc, CONST84 char *argv[]);
217 /**<
218 * Returns all the unit names which match the dimension number given.
219 * unit names will be in order of decreasing conversion factor
220 * and increasing length and alphabetically
221 * A bit more efficient than using UnitMatch_AtomDim.<br><br>
222 *
223 * Registered as: u_frombasedim <dimindex>
224 */
225
226 extern int Asc_UnitMatchAtomDim(ClientData cdata, Tcl_Interp *interp,
227 int argc, CONST84 char *argv[]);
228 /**<
229 * Returns all the unit names which match the dimension set of
230 * given real atom type, sorted as in Match_BaseDim.<br><br>
231 *
232 * Registered as: u_fromatomdim <atomname>
233 */
234
235 extern int Asc_UnitGetAtomList(ClientData cdata, Tcl_Interp *interp,
236 int argc, CONST84 char *argv[]);
237 /**<
238 * Returns a list of dimensioned atoms and dimensionalities.
239 * Wild and dimensionless are not considered dimensioned.<br><br>
240 *
241 * Registered as: u_getdimatoms
242 */
243
244 extern int Asc_UnitChangeBaseUnit(ClientData cdata, Tcl_Interp *interp,
245 int argc, CONST84 char *argv[]);
246 /**<
247 * Change the default display unit of the dimension implied by unit to
248 * be unit. Will return an error if unit does not have a simple
249 * dimensionality.
250 * Note: This will not catch semantic errors with dimensionless * dimd<br><br>
251 *
252 * Registered as: u_change_baseunit <unit>
253 */
254
255 extern int Asc_UnitSetUser(ClientData cdata, Tcl_Interp *interp,
256 int argc, CONST84 char *argv[]);
257 /**<
258 * Set the user specified units for the dimensionality they imply.
259 * Note: This will not catch semantic errors with dimensionless * dimd.<br><br>
260 *
261 * Registered as: u_set_user <units>
262 */
263
264 extern int Asc_UnitGetAtomsForUnit(ClientData cdata, Tcl_Interp *interp,
265 int argc, CONST84 char *argv[]);
266 /**<
267 * Returns the list of atoms and constants matching the units
268 * given, if any.<br><br>
269 *
270 * Registered as: u_get_atoms <units>
271 */
272
273 extern int Asc_UnitGetPrec(ClientData cdata, Tcl_Interp *interp,
274 int argc, CONST84 char *argv[]);
275 /**<
276 * Gets the display value precision, principally useful for reals.<br><br>
277 *
278 * Registered as: u_getprec
279 */
280
281 extern int Asc_UnitSetPrec(ClientData cdata, Tcl_Interp *interp,
282 int argc, CONST84 char *argv[]);
283 /**<
284 * Sets the display value precision, principally useful for reals.<br><br>
285 *
286 * Registered as: u_setprec <number 4-16>
287 *
288 * @todo Asc_UnitSetPrec() should use ansi prec info instead of 16 upper limit.
289 */
290
291 extern int Asc_UnitGetUnits(ClientData cdata, Tcl_Interp *interp,
292 int argc, CONST84 char *argv[]);
293 /**<
294 * Returns user set (or if never set, then default set) units for dims
295 * of atom type given.<br><br>
296 *
297 * Registered as: u_get_units <atomname>
298 */
299
300 extern int Asc_UnitGetUser(ClientData cdata, Tcl_Interp *interp,
301 int argc, CONST84 char *argv[]);
302 /**<
303 * Returns user set units for dims of atom given or "default" if unset.<br><br>
304 *
305 * Registered as: u_get_user <atomname>
306 */
307
308 extern int Asc_UnitGetList(ClientData cdata, Tcl_Interp *interp,
309 int argc, CONST84 char *argv[]);
310 /**<
311 * Returns user set units for all dims DUList.
312 * Units of defaulted dims not returned.<br><br>
313 *
314 * Registered as: u_get_list
315 */
316
317 extern int Asc_UnitClearUser(ClientData cdata, Tcl_Interp *interp,
318 int argc, CONST84 char *argv[]);
319 /**<
320 * Unsets user set units for dims of atom given.<br><br>
321 *
322 * Registered as: u_clear_user <atomname>
323 */
324
325 extern int Asc_UnitGetVal(ClientData cdata, Tcl_Interp *interp,
326 int argc, CONST84 char *argv[]);
327 /**<
328 * Instance indicated by qlfdid. In general, this is expensive.<br><br>
329 *
330 * Registered as: u_getval <qlfdid> returns as Asc_UnitValue if possible from the
331 */
332
333 extern int Asc_UnitBrowGetVal(ClientData cdata, Tcl_Interp *interp,
334 int argc, CONST84 char *argv[]);
335 /**<
336 * Instance indicated by g_curinst (g_searchinst if "search" given).<br><br>
337 *
338 * Registered as: u_browgetval [search] returns {value} {units} if possible from the
339 */
340
341 extern int Asc_UnitSlvGetRelVal(ClientData cdata, Tcl_Interp *interp,
342 int argc, CONST84 char *argv[]);
343 /**<
344 * Returns as Asc_UnitValue if possible from the relation
345 * indicated by index.<br><br>
346 *
347 * Registered as: u_slvgetrelval <rellist index>
348 */
349
350 extern int Asc_UnitSlvGetVarVal(ClientData cdata, Tcl_Interp *interp,
351 int argc, CONST84 char *argv[]);
352 /**<
353 * Returns as Asc_UnitValue if possible from the variable
354 * indicated by index.<br><br>
355 *
356 * Registered as: u_slvgetvarval <varlist index>
357 */
358
359 extern int Asc_UnitSlvGetObjVal(ClientData cdata, Tcl_Interp *interp,
360 int argc, CONST84 char *argv[]);
361 /**<
362 * Returns as Asc_UnitValue if possible from the obj indicated
363 * by index. Until there is an objlist, this will simply look
364 * at obj and ignore index.
365 *
366 * Registered as: u_slvgetobjval <objlist index>
367 */
368
369 extern int Asc_UnitHelpList(ClientData cdata, Tcl_Interp *interp,
370 int argc, CONST84 char *argv[]);
371 /**<
372 * uhelp command for tcl.
373 * no arg -> return tcl list
374 * "s" -> list names only, "l" -> short explanations also, to stderr.<br><br>
375 *
376 * Registered as: uhelp [s,l]
377 */
378
379 #endif /* ASCTK_UNITSPROC_H */
380

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