| 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 |
|
Parent Directory
| 
Revision Log