The unit library is for use in engineering or scientific
applications where the user wishes to input numbers in one unit system, and the
application needs numbers in a different system.
Units can be created from an arbitrary combination of the built in units at run time. For example, if an area is required, the user can input "m^2" or "in^2". Error checking can be performed to make sure that a specified unit is of the correct type. For example, "m" is not the same as "m^2".
The code can then convert numbers from this unit to the corresponding SI unit, and visa versa. Typically, an application will be programmed to work in SI units, and do all conversion during input and output. However, conversion can be done at any stage.
Whenever a new unit is created, it is stored in a table of units so that it may be used in the definition of other units, later on.
See the Main Page or the Sourceforge Project Page for more information, and for information about the companion program, a PalmOS application.
To convert numbers from one unit to another, an application would
typically first create two Unit objects representing the desired
units. Second, the two objects may be compared to verify that they are
compatible. Third, the numbers are converted from the first unit to SI units. And
finally the numbers are converted from SI units to the second unit.
To create a unit object you would use one of these:
Unit Unit.newUnit(String def).
This creates a new unit by parsing the string def.
It is given the name def.
Unit Unit.newUnit(String name, double x, String def),
This creates a new unit by parsing the string def, and
then scaling it by x.
It is given the name name.
For example, to define feet in terms of inches, use:
Unit feet = newUnit("ft", 12.0,"in");
It helps to read this as one foot equals 12 inches. Also note that
"ft" is already a built in unit.
Unit.ParseException if the string that is
parsed has an error in it. There are no public constructors for
Unit, you must use one of these static "factory" methods.
Once the units are created, you can use the following three methods:
boolean sameType(Unit other).
To verify that two units are compatible.
double to(double x).
To convert from standard SI units to this unit.
double from(double x).
To convert from this unit to standard SI units.
For example, a subroutine that converts a number into millimeters would look something like this:
double convertToMillimeters(String unit1, double x) throws ParseException {
Unit u1 = Unit.newUnit(unit1);
Unit u2 = Unit.newUnit("mm");
if( ! u1.sameType(u2) ) {
System.out.println("Warning: "+u1+" not compatible with "+u2);
System.exit(1);
}
double x_si = u1.from(x);
double x2 = u2.to(x);
return x2;
}
You may also create new units, which are not named as the product or quotients of other units. You may wish to do this if you are parsing an equation of some sort. The methods to use are:
u3 = u1.product(u2), to make u3 = u1*u2.
u3 = u1.quotient(u2), to make u3 = u1/u2.
u3 in the table of existing units, because it is
not generated with a name.
Since sums and differences should be of equivalent units, you would just use
sameType.
See the list of units page for a list of built in units and prefixs, and a more detailed description of how the string is parsed in order to create a unit.
One last note:
If you would prefer to use lb for pound mass, you can
have the code
Unit.newUnit("lb", 1, "lbm");
before you create any units with a pound in them.
This will create a new unit with the same name as the old one,
but with a new definition. This new Unit is then stored
in the internal table of units under the name "lb". Now, any more
calls to newUnit will use this new definition of "lb".
You may download a jar file from
sourceforge download page.
This jar has all of the class files in the unit package,
as well as those in the jmisc package that are also needed.
The jar file does not include any documentation except for this web page.
Consult the documentation for your java virtual machine on how to install a jar file.
From the same download page, you may also download the source files in either a
compressed tar file (tgz) or a zip file. This file
will include all the java files as well as the C++ source for the PalmOS
application.
The Java code for unit is in the public domain. The PalmOS
application is under the LGPL license.
In order to compile the java code, you will need the jmisc package. A jar file of the jmisc classes is included in the source download.
A makefile is included for compiling. However, the code is standard Java, and may be compiled in the usual manner.
If you wish to add a new built-in unit, you should edit
and run the file UnitList.java, which will create
UnitInit.java. Typically this is only done when a unit is needed
for several different applications.
The parser in this package was created with JavaCC You will need to have this installed if you wish to modify the parser. To compile the existing parser, and the other Java code, you do not need to have JavaCC installed.