ascend/compiler/units.h

/*  ASCEND modelling environment
    Copyright (C) 2006, 2011 Carnegie Mellon University
    Copyright (C) 1990, 1993, 1994 Thomas Guthrie Epperly

    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.
*//*
    by Tom Epperly 8/18/89
    Last in CVS: $Revision: 1.10 $ $Date: 1998/02/05 16:38:40 $ $Author: ballan $
*/

#ifndef ASC_UNITS_H
#define ASC_UNITS_H

#include <stdio.h>
#include <ascend/general/platform.h>
#include "compiler.h"
#include "fractions.h"
#include "dimen.h"

/** @addtogroup compiler_units Compiler Units
    @{
*/

#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               "kg"
/**< SI base unit symbol for mass. */
#define UNIT_BASE_QUANTITY           "mol"
/**< SI base unit symbol for quantity. */
#define UNIT_BASE_LENGTH             "m"
/**< SI base unit symbol for length. */
#define UNIT_BASE_TIME               "s"
/**< SI base unit symbol for time. */
#define UNIT_BASE_TEMPERATURE        "K"
/**< SI base unit symbol for temperature. */
#define UNIT_BASE_CURRENCY           "USD"
/**< Base unit (non SI) for currency (US dollar) */
#define UNIT_BASE_ELECTRIC_CURRENT   "A"
/**< SI base unit symbol for current. */
#define UNIT_BASE_LUMINOUS_INTENSITY "cd"
/**< SI base unit symbol for luminosity. */
#define UNIT_BASE_PLANE_ANGLE        "rad"
/**< Base unit (non SI) for plane angle (radian). */
#define UNIT_BASE_SOLID_ANGLE        "sr"
/**< Base unit (non SI) for solid angle (steradian). */

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

extern void InitUnitsTable(void);
/**<
    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);
/**<
    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);
/**<
 *  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);
/**<
 * Destroys udp and its unitsexpr.
 */

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

ASC_DLLSPEC CONST struct Units*LookupUnits(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);
/**<
 *  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
 */

ASC_DLLSPEC CONST struct Units*FindOrDefineUnits(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>
 */

ASC_DLLSPEC char**UnitsExplainError(CONST char *unitsexpr, int code, int 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)
/**<
 *  Returns the string description attribute of a units structure.
 */

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

#define UnitsDimensions(u) ((u)->dim)
/**<
 *  Returns the dimensions of the units structure.
 */

ASC_DLLSPEC char *UnitsStringSI(struct Units *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.
 */

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

/* @} */

#endif /* ASC_UNITS_H */

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