* Units V1.11 Documentation *

This file consists of the following sections:

1) Legal information
2) Aim of Units
3) Features
3.1) New features since V1.0
3.2) New features since V1.1
4) Conversion Mechanism
4.1) Basic Mechanism
4.2) Currency Conversion
4.3) Prefix Mechanism
5) A few words about the interface
6) Known bugs (or defaults)
7) How to contact me
8) Registration Identifier
9) Compiling Units
10) Acknowledgments
1) Legal information to top

This software is supplied under the GNU General Public Licence. For more information, please read the COPYING file in the accompanying ZIP.

2) Aim of Units to top

Units is a generic, extensible, conversion program.

It's generic, because it can handle various unit categories (volume, distance, currency, temperature, and so on).

It's extensible because you can add, remove or modify units and their conversion factors directly with your PalmPilot.

3) Features to top

"Units" tries to minimize the amount of memory needed for storing unit descriptions and their conversion factors. It tries to make conversions easier by automatic handling of any prefixes associated with each unit. You can configure which choices are available for each unit.

Take distance units as an example. We want to have the "metre", and we also want kilometre, centimetre (and why not nanometre) without having to explicitly enter each of the metre's sub units. When creating the "metre" unit, you can specify that you want "Units" to associate these 3 prefixes (kilo, centi, nano) with the "metre" unit.

However, if you add the "parsec" unit, you may not want the "kilo-parsec" or the "milli-parsec". Hence, you would not select these prefixes for this unit.

Prefixes given in "Units" are the standard International System (SI) ones, that is:

atto, femto, pico, nano, micro, milli, centi, deci, deca, hecto, kilo, mega, giga, tera, peta and exa.
A database containing units along with their conversion factors and applicable prefixes  is supplied, in French and in English. This database currently contains about 109 different basic units, along with suitable prefixes.

3.1) New features since V1.0 to top

Some new features have appeared since the previous version of "Units":

  • The program now remembers which category, units and prefixes are in use when it is closed. When you run "Units" later it will restore these settings.
  • It's now possible to use a non scientific notation for displaying results of conversions.
  • Checks are performed to avoid errors in low memory situations.
  • Some units have been added in the standard database, and other have been corrected.
  • It's now possible to provide the inverse of 'a' factor. This can be useful for currency conversions (see section 4.2 : Currency Conversion).
  • Spelling errors were corrected, both in program and doc.
  • I'm now sure that the database containing units is backed up during HotSync.
  • An HTML version of the documentation is now available (Thank's to Tony Jest for the English file which also served as skeleton for the French one ;-)
  • 3.1) Nouvelles caractéristiques depuis V1.1 retour au début

  • Bug fix in conversion mechanism which caused incorrect results while converting degrees celsius and farenheigt.
  • 4) Conversion Mechanism to top

    4.1) Basic mechanism to top

    To create new conversion units it's best to understand the mechanism used by "Units" to perform its conversions.

    First, let's consider the basic mechanism. We shall say that 1 "kilometre" equals 1000 "metres". So we can model this conversion by the following equation:

    km = 1000 * m
    In some other cases, a simple multiplication is not enough. Let's take the case of temperatures. 0 "Celsius" equals -273 "Kelvins". Hence, this particular conversion corresponds to the equation:
    celsius = kelvin + 273
    "Units" performs conversions using the equation:
    Unit1 = a * Unit2 + b
    In order to convert a quantity from one unit Unit1 to another Unit2, of course the system needs to know the factors to apply for conversion between these two units. Two units give us 2^2 kinds of conversions:
    U1 -> U1,
    U1 -> U2,
    U2 -> U1,
    U2 -> U2
    If one considers more units, let's say n units, the number of possible conversions is given by n^2. Clearly, it's important to find a way to convert between 2 units without having to the appropriate conversion factors between each pair of units.

    The solution is to take a "pivot", or reference unit, into which we will be able to convert each unit, and from which we will be able to go to any other unit.

    In other words, when creating a unit, instead of giving the relation of this unit with all the other units (which would be boring, and would oblige the user to modify each already entered units when adding a new one), we will simply say how to go from this unit to the reference unit. This reference unit is completely arbitrary. It doesn't even need be to entered as a unit with a name in the system. You must remember it though, because of course, every unit of the same category will have to refer to the same reference unit!

    A good obvious choice to use as a reference is the international system reference unit, for example "metre" for distance, "second" for time, and so on. Actually, the database provided in standard with "Units" doesn't exactly use the international system reference for all units. The exact configuration is:

  • Distance: Metre
  • Pressure: Pascal
  • Area: M2 (Metre Squared)
  • Temperature: Degree Celsius
  • Time: Second
  • Volume: Litre
  • Weight: Gramme
  • Energy: Joule
  • Fuel consumption: Litre per 100 km
  • Power: Watt
  • Speed: Metre per second
  • And now : an example...

    Let's consider the unit "mile" which is equal to 1.609344 kilometres.
    Let's choose "metre" as reference unit.
    We shall say that the way for going from a "mile" to our reference unit is:
    y = 1609.344 * x + 0.
    Let's note that we don't have entered in the system any notion of "metre". If now we want to enter "metre", we will give it the following equation:
    y = 1 * x + 0.
    Indeed, in order to convert "metre" to our reference unit (which in fact is the "metre"), we just have to multiply by 1.

    A last example, temperature.
    Let's take "degree Celsius" as reference unit. Hence these "degrees Celsius" will be associated, of course, to the equation: y = 1 * x + 0. For "Kelvins" (where -273 corresponds to 0 degree Celsius ), the equation will be:

    y = 1 * x + 273.
    When one creates a unit in "Units", the user has to enter these values for the "a" and "b" coefficients in the equations. Of course, the "a" factor can't be null, otherwise the conversion would have no meaning!

    4.2) Currency Conversion to top

    Some newspapers and Bureaux de change list currency conversion rates the opposite way to that required by "Units", for example they state how much one UK pound sterling will purchase (2.822DM, 9.43FFr, 1.591USD)
    So now if I use the UK pound sterling as the reference unit I should not enter these figures into the "a" field but their reciprocals (1/2.822 and so on). The "1/a" check box does this calculation automatically for you before entering the result in the "Units" into the "a" field and the database.

    4.3) Prefix mechanism to top

    The mechanism above enables conversions to be handled in a general way. Let's now consider prefixes. One knows that one kilo-metre is equal to 1000 metres, that a "deci-litre" is equal to 10 litres. So we could think that when asking to convert 2 "kilo-things" to another unit, it's as if we had to convert 2 * 1000 "things" toward the other unit. In other words, the "kilo" prefix seems to imply a multiplication of the basic unit by 10^3.

    In fact, that's not correct because  1 "kilo-M2 (metre squared)" is not equal to 1000 "M2", but is equal to 1000000 "M2" (there are 2 digits per column). In other words, here the prefix "kilo" implies a multiplication of the basic unit by 100^3.

    Also note that 1 "kilo-byte" is not equal to 1000 bytes, but 1024 bytes.

    "Units" uses a mechanism allowing to generalize the notion of prefix, by considering that prefixes of the international system are not exclusively based on 10^something, but rather on m^something. So, m is a factor which allows to known how to go to the next prefix. This factor will be powered by the exponent corresponding to the prefix (this exponent is the one universally accepted in the international system, that's to say: kilo => 3, hecto => 2, deca => 1, deci => -1, and so on...)

    For example, let's take the case of distances.

    Deci = 10^-1 Deca = 10^1 Hecto = 10^2 and so on...
    For surfaces:
    Deci = 100^-1 Deca = 100^1 Hecto = 100^2 and so on...
    For volumes:
    Deci = 1000^-1 Deca = 1000^1 Hecto = 1000^2 and so on...
    And finally for bytes:
    Kilo = 10.0793684^3
    (10.0793684 is the cube root of 1024, hence, 10.0793684^3 = 1024 and so, using the prefix "kilo" with bytes will yield to really multiply by 1024, and not by 1000).
     
    When the user creates a unit, he will have to specify the value for this "m" factor. Of course, the "m" factor can't be null, otherwise the conversion would have no meaning !

    This is all that needs to be known about data needed for creating a new unit in the "Units" system, and why they are needed.

    5) A few words about the interface to top

    To specify prefixes available for a unit you should tap on the check boxes required in the form.

    Units are sorted by category. Its impossible to convert between units belonging to different categories. Even when you are in the "All" category, a verification is performed in order to avoid inconsistent conversions.

    Cut/copy/paste is available in the different fields of "Units".

    When a unit is created, it automatically contains the "empty" prefix, that's to say the prefix multiplying by nothing. For example, if you create "metre", with for example "kilo" and "centi" prefixes, 3 prefixes will be available "k", "c" and " ". This last prefix is the one which allows you to speak of simple "metres".

    The database containing the conversion factors is automatically backed up by a HotSync.

    A checkbox in the bottom left of the main screen allow to use either the scientific notation (for example 1.23e2) ot the usual notation (123) for displaying results. Note that when numbers get very big or very little, non scientific notation can use exponent notation if needed. Note that the code which displays numbers with dot notation is currently heavily dependent of the format of the string returned by the internal float to ascii Pilot's routine. So if this feature doesn't work on your Pilot, let me know. My one is a Pilot 5000, and it works... (at least it seems ;-)

    When entering very big (or very litte) number, please prefer scientific notation. For example instead of entering 1000000000000000, enter 1e16. Why ? Because the internal Pilot asci to float routine seems not to handle properly such cases. So, if using the 1e16 notation, all goes fine. Indeed, when using such a number, who enter this without scientific notation ;-) ?

    6) Known bugs (or defaults) to top

    As far as I know, 2 little things are wrong with "Units".

     * Copying/pasting: when copying the result field in order to paste it somewhere else, the "e" character (the exponent character) will be transformed  in the "/" character. That's not my fault. In fact, I used the Pilot's font 6  in order to get these big fonts used in the calculator. And in this font, the  "e" doesn't have the same ASCII code than in other fonts. So just before displaying the result string, I replace the "e" character generated by standard floats conversion routines, by the character whose code is the "e" in the font 6. And then, when one takes this string back to put it in a location using another font, the inverse problem arises and then the "e" looks like a "/". This is not serious and doesn't prevent the conversion from working.

     * If a bad numerical value is entered in the input field (for example something having a bad float format), the resulting number will be 0. I don't check for this, you have to verify yourself that numbers you enter ... are numbers... The system doesn't do this for you.

    7) How to contact me to top

    For any comments, suggestion, bug reports, and so on, you can reach me by email at:

    francois.pessaux@inria.fr
    8) Registration Identifier to top

    This program's identifier is 'UniT', got by standard registration at

    http://palmpilot.3com.com/devzone/crid/cridsub.html
    9) Compiling "Units" to top

    "Units" was written with Gcc under Linux. Its source can be compiled so as to produce messages in either French or in English. This is simply configurable via the Make file, you should comment and uncomment 2 lines in the Make file (look at lines 12 to 19). Then 'make' should to the rest.

    10) Acknowledgments to top

    Thank's to Tony Jest who tested "Units" and reported me *a lot* of bugs, and some improvement ideas. He also corrected, extended (currency part), and formatted in HTML the English documentation file.