generic/compiler/units.h

/*  ASCEND modelling environment
    Copyright (C) 2006 Carnegie Mellon University

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2, or (at your option)
    any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place - Suite 330,
    Boston, MA 02111-1307, USA.
*//**
    @file
    Ascend Units Type definitions.

    Requires:
    #include <stdio.h>
    #include "utilities/ascConfig.h"
    #include "fractions.h"
    #include "compiler.h"
    #include "dimen.h"
*//*
    by Tom Epperly
    8/18/89
    Version: $Revision: 1.10 $
    Version control file: $RCSfile: units.h,v $
    Date last modified: $Date: 1998/02/05 16:38:40 $
    Last modified by: $Author: ballan $
*/

#ifndef ASC_UNITS_H
#define ASC_UNITS_H

#include <utilities/ascConfig.h>

#ifdef _HPUX_SOURCE
#define ACAST char *
#define BCAST char *
#else
#define ACAST const char *
#define BCAST char *
#endif
/**< to shut up the hp lexer */

/**
 *  Value in system units = value in given units * conversion_factor.
 */
struct Units {
  double conversion_factor; /**< to convert from units to system units */
  symchar *description;     /**< description of units */
  CONST dim_type *dim;      /**< dimenions of units */
  struct Units *next;       /**< not for human consumption */
};

/**
 * Temporary structure for parsing unit definitions in ascParse.y.
 */
struct UnitDefinition {
  symchar *new_name;
  CONST char *unitsexpr;
  CONST char *filename;
  int linenum;
};

#define UNITS_HASH_SIZE (1023)
/**<
 *  size of the hash table for unit structs
 */

/*
 * Name of the basic SI units for the 10 dimensions.
 * If you have better names for them, fix that here.
 */
#define UNIT_BASE_MASS               "kilogram"
/**< Name of basic SI unit for mass. */
#define UNIT_BASE_QUANTITY           "mole"
/**< Name of basic SI unit for quantity. */
#define UNIT_BASE_LENGTH             "meter"
/**< Name of basic SI unit for length. */
#define UNIT_BASE_TIME               "second"
/**< Name of basic SI unit for time. */
#define UNIT_BASE_TEMPERATURE        "Kelvin"
/**< Name of basic SI unit for temperature. */
#define UNIT_BASE_CURRENCY           "currency"
/**< Name of basic SI unit for currency. */
#define UNIT_BASE_ELECTRIC_CURRENT   "ampere"
/**< Name of basic SI unit for current. */
#define UNIT_BASE_LUMINOUS_INTENSITY "candela"
/**< Name of basic SI unit for luminosity. */
#define UNIT_BASE_PLANE_ANGLE        "radian"
/**< Name of basic SI unit for plane angle. */
#define UNIT_BASE_SOLID_ANGLE        "steradian"
/**< Name of basic SI unit for solid angle. */

extern struct Units *g_units_hash_table[];
/**<
 *  The hash table for unit structs.
 */

extern void InitUnitsTable(void);
/**<
 *  <!--  void InitUnitsTable()                                        -->
 *  This routine initializes some internal variables, so that all the
 *  other units functions may be called.  It must be called once and
 *  only once when the program is starting up.
 *  Must be called after dimensions table initiatialization.
 */

extern void DestroyUnitsTable(void);
/**<
 *  <!--  void DestroyUnitsTable()                                     -->
 *  This routine can be called to deallocate all of the units in the table.
 */

extern struct UnitDefinition *CreateUnitDef(symchar *new_name,
                                            CONST char *unitsexpr,
                                            CONST char *filename,
                                            int linenum);
/**<
 * <!--  udptr = CreateUnitDef(new_name,unitsexpr,filename,linenum);   -->
 * <!--  new_name should be from the symbol table.                     -->
 * <!--  unitsexpr is a string that we will copy, so it does not       -->
 * <!--  need to be persistent.                                        -->
 * <!--  filename should be persistent.                                -->
 *  Create a new unit definition.
 *  @param new_name  Should be from the symbol table.
 *  @param unitsexpr A string that we will copy, so it does not
 *                   need to be persistent.
 *  @param filename  Should be persistent.
 *  @param linenum   Line number.
 */

extern void DestroyUnitDef(struct UnitDefinition *udp);
/**<
 * <!--  DestroyUnitDef(udp);                                          -->
 * Destroys udp and its unitsexpr.
 */

extern void ProcessUnitDef(struct UnitDefinition *udp);
/**<
 * <!--  ProcessUnitDef(udp);                                          -->
 * Attempts to add the info in udp to the units table.
 * messages to ascerr if not possible.
 */

extern ASC_DLLSPEC(CONST struct Units*) LookupUnits(CONST char *c);
/**<
 *  <!--  const struct Units *LookupUnits(c)                           -->
 *  <!--  const char *c;                                               -->
 *  Check the units library for units with a description string which
 *  matches c.  If it is found, this function will return a non-NULL pointer;
 *  otherwise, it returns NULL to indicate that units c are undefined.
 *  c should not contain any blanks.
 */

extern CONST struct Units *DefineUnits(symchar *c, double conv, CONST dim_type *dim);
/**<
 *  <!--  const struct Units *DefineUnits(c,conv,dim)                  -->
 *  <!--  const char *c;                                               -->
 *  <!--  double conv;                                                 -->
 *  <!--  const dim_type *dim;                                         -->
 *  Define the units c with conversion factor conv and dimensions *dim.
 *  This assumes that *dim was the value returned by FindOrAddDim.  This
 *  will check to prevent duplicate entries.  The resulting unit structure is
 *  returned.  If you enter a duplicate entry and the dimensions or conversion
 *  factor don't match, this function will return NULL.  In addition to
 *  the user defined units there is a wild units type which conversion equal
 *  to one and wild dimensions.  It is given the name "?".<br><br>
 *
 *  c should not contain any spaces!  It may add c to the symbol table if
 *  it is not already stored there.
 *
 *  @bug Memory leak if hitting an empty hash bucket. buckets never deallocated
 *       except at shutdown anyway, so not a big deal. 7bytes/hit. Don't off hand
 *       know where to fix it. BAA 6-94
 */

extern ASC_DLLSPEC(CONST struct Units*) FindOrDefineUnits(CONST char *c,
                                             unsigned long * CONST pos,
                                             int * CONST error_code);
/**<
 *  <!--  struct Units *FindOrDefineUnits(c,pos,error_code)            -->
 *  <!--  CONST char *c;                                               -->
 *  <!--  unsigned long * const pos;                                   -->
 *  <!--  int * const error_code;                                      -->
 *  This function will attempt to parse the string c into a units
 *  description.  If the unit type has been defined before, the corresponding
 *  units pointer will be returned.  If this type hasn't been defined before,
 *  it will be defined and that pointer will be returned.  If it is
 *  unable to parse this string it will return NULL.  CheckUnitStr, below,
 *  can be used to diagnose why the unit didn't parse.
 *  This will not modify c in any way.  It may add c to the symbol table.
 *  <pre>
 *  RETURN VALUE OF error_code
 *    0   string is okay, value of pos not specified
 *    1   undefined unit used in string, pos indicates the first
 *           letter of the first occurence of the undefined unit
 *    2   unbalanced parenthesis, pos indicates the opening parenthesis
 *           that wasn't closed
 *    3   illegal character, pos indicates the position of the offending
 *           character
 *    4   illegal real value, pos indicates the first character of the
 *         real value
 *    5   oversized identifier or real, pos indicates the start of the
 *           offending token
 *    6   operator left out real followed by identifier or vice
 *           versa, pos indicates where an operator should have been
 *           inserted
 *    7   term missing after *,/, or (.
 *    8   missing term before *,/. pos is left at the operator
 *    9   too many closing parens.  pos is left at the extra paren.
 *   10   bad fraction exponent.  pos is at the left of the fraction field
 *   11   incompatible unit redefinition. (internal use only; not seen).
 *  </pre>
 */

extern ASC_DLLSPEC(char**) UnitsExplainError(CONST char *unitsexpr, int code, int pos);
/**<
 *  <!--  errv = UnitsExplainError(unitsexpr,code,pos);                -->
 *  Returns an array of strings which may be helpful in
 *  explaining the error.
 *  - errv[0] is a message.
 *  - errv[1] is the unitsexpr.
 *  - errv[2] is a pointer to the error -------^ line.
 *            aligned with unitsexpr given.
 *  The user should never change or free errv or its content,
 *  nor should the user keep the pointers.
 */

#define UnitsDescription(u) ((u)->description)
/**<
 *  <!--  macro UnitsDescription(u)                                    -->
 *  <!--  struct Units *u;                                             -->
 *  Returns the string description attribute of a units structure.
 */

#define UnitsConvFactor(u) ((u)->conversion_factor)
/**<
 *  <!--  macro UnitsConvFactor(u)                                     -->
 *  <!--  struct Units *u;                                             -->
 *  Returns the conversion factor for a given units structure.
 */

#define UnitsDimensions(u) ((u)->dim)
/**<
 *  <!--  macro UnitsDimensions(u)                                     -->
 *  <!--  struct Units *u;                                             -->
 *  Returns the dimensions of the units structure.
 */

extern char *UnitsStringSI(struct Units *up);
/**<
 *  <!--  UnitsStringSI(up);                                           -->
 *  Returns the SI form of the units for the dimensionality of up.
 *  Wild = *, Dimensionless = "", NULL up --> NULL return.
 *  Caller is responsible for freeing the string returned.
 */

extern void DumpUnits(FILE *f);
/**<  Dump all defined units to f. */

#endif /* ASC_UNITS_H */

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