UNITS OF MEASUREMENT
FOR ADA
version 3.13
by Dmitry A. Kazakov
(mailbox@dmitry-kazakov.de)

This library 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 of the License, or (at your option) any later version. This library 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 library; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

As a special exception, if other files instantiate generics from this unit, or you link this unit with other files to produce an executable, this unit does not by itself cause the resulting executable to be covered by the GNU General Public License. This exception does not however invalidate any other reasons why the executable file might be covered by the GNU Public License.

Foreword

The need of support for handling measurement units does not require any approval. It is in particular true for the Ada programming language with its stress on safety and maintainability. The proposed set of packages represents a possible solution of the unit problem. Dimension checking is performed at run-time, so performance is sacrificed for safety. However, an attempt was made to reduce performance hit. The type Measure used to represent dimensioned values can be constrained to a specific unit. Operations on constrained subtypes of Measure could be potentially as efficient as floating-point operations. They are declared inlined, so that at least theoretically, a decent compiler could perform discriminant calculation and check at compile time. The key features of the approach: The type Unit denotes the dimension of a physical entity. The type Measure represents a dimensioned value; Mixed unit arithmetic. Values in SI (Le Système International d'Unités) units can be mixed with irregular units (such as foot and yard) as long as the result is defined; Shifted unit support (a widely used instance of a shifted unit is degree of Celsius); The type Measure is generic, parameterized by a floating-point type. A non-generic version based on the type Float is also provided; String to Measure conversion supports as wide set of irregular units as possible; Currently the powers of the base unit components lie in the range -8..7. This limitation has an implementation reason (absence of 64-bit modular integers in some Ada compilers). For further discussion of this topic see; GTK+ widgets for a comfortable visual measurement unit editing and selection. The rest of the library can be used independently on this part as well as on GTK+. See also the changes log.

You also may wish to visit this site devoted to the problem of dimensioned values in Ada.

						ARM		Intel
Download Units of Measurements for Ada				Platform:		64-	32-	64-	32bit
Fedora packages			precompiled and packaged using RPM
CentOS packages			precompiled and packaged using RPM
Debian packages			precompiled and packaged for dpkg
Ubuntu packages			precompiled and packaged for dpkg
Source distribution (any platform)			units_3_13.tgz (tar + gzip, Windows users may use WinZip)

The units converter and mapper are small utilities provided as exercises to illustrate use of the software. The unit converter is a small dialog box where you can enter a dimensioned value and then convert it to SI. The unit mapper is a dialog box that converts value from one unit to another as you type it. The source code is discussed in the section 3.2.

ARM Intel Download Units Converter Platform:   64- 32- 64- 32bit Windows      units_converter.exe.gz built using Windows 64-bit API (gzip compressed)          Fedora   binary package     CentOS   binary package         Debian   binary package   Ubuntu   binary package   Download Units Mapper           Windows     units_mapper.exe.gz built using GTK+ API (gzip compressed)   Fedora   binary package   CentOS   binary package       Debian   binary package   Ubuntu   binary package

1. Types

Two types are used for dealing with units. The type Unit denotes the dimension of a physical entity. The type Measure represents a dimensioned value it is defined in a generic package Measures which is instantiated with the desired floating-point type as the parameter:

generic
   type Number is digits <>;
package Measures is
   ...

The package Float_Measures is an instance of Measures for the standard Float type: .

1.1. The type Unit

The type Unit is defined in the package Units. A value of the type Unit corresponds to a kind of physical entity, like energy, charge or velocity. The package itself is rather useless, because there are few things one can do with units. They are:

• Exponentiation, the power is an integer;
• Multiplication;
• Division;
• Square root;
• Conversion to String.

Or in Ada terms the following functions are defined:

function "**" (Left : Unit; Right : Integer) return Unit;
function "*"  (Left, Right : Unit) return Unit;
function "/"  (Left, Right : Unit) return Unit;
function Sqrt (X : Unit) return Unit;

Values of the type Unit build a group. A value of Unit type can be viewed as an unordered set of seven base components (mass, length, time, current etc.). Each component has integer exponent part. The function Sqrt is defined for only units which components have even exponent parts. The exception Constraint_Error is propagated when the result of an operation is illegal.

The package also declares the exception Unit_Error and the type:

type Code_Set is (ASCII_Set, Latin1_Set, UTF8_Set);

and the procedure:

procedure Split
          (  SI           : Unit;
             Current      : out Natural;
             Luminescence : out Natural;
             Temperature  : out Natural;
             Mass         : out Natural;
             Length       : out Natural;
             Quantity     : out Natural;
             Time         : out Natural
          );

The procedure returns base unit powers of the argument SI.

1.1.1. Base units

The child package Units.Base defines constants for the base SI units:

Current       : constant Unit;
Luminescence  : constant Unit;
Temperature   : constant Unit;
Mass          : constant Unit;
Length        : constant Unit;
Quantity      : constant Unit;
Time          : constant Unit;
Unitless      : constant Unit;

1.1.2. Unit constants

The child package Units.Constants defines some of more complex units. Geometric units are:

Area          : constant Unit := Length ** 2;
Volume        : constant Unit := Length ** 3;

Units used in mechanics:

Velocity      : constant Unit := Length / Time;
Acceleration  : constant Unit := Length / Time ** 2;
Force         : constant Unit := Mass * Acceleration;
Pressure      : constant Unit := Force / Area;
Energy        : constant Unit := Force * Length;
Power         : constant Unit := Energy / Time;

Electricity units:

Charge        : constant Unit := Current * Time;
Potential     : constant Unit := Energy / Charge;
Capacitance   : constant Unit := Charge / Potential;
Resistance    : constant Unit := Potential / Current;
Conductance   : constant Unit := Current / Potential;
Inductance    : constant Unit := Potential * Time / Current;

Chemistry units:

Concentration : constant Unit := Quantity / Volume;
Density       : constant Unit := Mass / Volume;

Optic units:

Luminance     : constant Unit := Luminescence / Area;

Other units:

Frequency     : constant Unit := Unitless / Time;

1.1.3. Conversion to ASCII and Latin-1 strings

The package Units.Edit provides the function Image is used to convert Unit to String:

function Image
         (  Value  : Unit;
            Latin1 : Boolean := True
         )  return String;

The syntax of the result string is:

<result>	::=	<list>/<list> | 1/<list> | <list> | 1
<list>	::=	<item> [<*><list>]
<item>	::=	<base-unit>[<power>]
<base-unit>	::=	A | cd | K | kg | m | mol | s

Here <*> is either * (if Latin1 is false), or · from Latin-1 character set. When Latin1 is false <power> is always ^<number>. With Latin-1 character set enabled, powers 2 and 3 are indicated using the corresponding superscript characters: ² and ³. The following table lists the Latin-1 characters used for output:

1.1.4. Conversion to UTF-8 encoded strings

The package Units.UTF8_Edit provides the function Image used to convert Unit to an UTF-8 encoded string:

function Image (Value : Unit) return String;

The syntax of the result string is:

<result>	::=	<list>/<list> | <list> | 1
<list>	::=	<item> [·<list>]
<item>	::=	<base-unit>[<power>]
<base-unit>	::=	A | cd | K | kg | m | mol | s
<power>	::=	[-]<number>
<number>	::=	<digit>[<number>]
<digit>	::=	2 | 3 | 4 | 5 | 6 | 7 | 8 | 9

Powers are output as superscript digits. When all powers are negative, the output uses no fraction but negative powers instead. For example: m^-2 instead of 1/m². The following table summarizes the list of special characters and their encodings in UTF-8:

1.1.5. Design notes

Some words about the design. I didn't make the type Unit private because then it could not be used as a discriminant of the type Measure (see the package Measures). To have Measure discriminated seems to be very important. It allows to define subtypes of Measure with fixed Unit component. For the same reason and for performance sake too, Unit is a modular number. As the result it inherits a number of operations which are disallowed by making them abstract. In the current implementation the type Interfaces.Unsigned_32 is used. This determines the range of the exponent part of a base component as -8..7. With Interfaces.Unsigned_64 the range would be -512..511. The following fragment of the file units.ads can be modified if the compiler supports modular numbers larger than Interfaces.Unsigned_32:

Rational powers are not allowed, because the choice of base units in SI ensures whole powers of all physical values. Examples like Schottky-Langmuir equation can be easily written in a correct form with whole powers. Often it is argued that rational powers might be useful for dealing with intermediate results. A simple example x = ln e^x shows that in general case it cannot be done anyway.

1.2. The type Measure

A value of the type Measure (defined in the package Measures) represents some quantity of a physical unit:

type Measure (SI : Unit := Units.Base.Unitless) is record
   Gain   : Number;
   Offset : Number'Base := 0.0;
end record;

Measures can be added, subtracted, multiplied, divided and exponentiated. The type Measure is a discriminated record type. The discriminant SI has the type Unit. Its value defines the dimension of a Measure. Unconstrained instances of Measure can be declared as:

Entity : Measure;      -- May hold value of any measurement unit
. . .
Entity := 5.0 * A / s; -- Set value 5 A/s
Entity := 3.0 * km;    -- Set value 3.0 km
Entity := Entity + s;  -- Illegal (km + s), Unit_Error

It is possible however, to create constrained subtypes of Measure capable to hold values of only a specific dimension. For instance:

subtype Speed is Measure (Velocity);
Car_Speed : Speed;          -- Only velocities are allowed
. . .
Car_Speed := 10.0 * km / h; -- OK
Car_Speed := A;             -- Illegal, Constraint_Error

The type Measure has two components: Gain and Offset. To get a SI equivalent of the value one should sum Gain and Offset. This is what the function Get_Value actually does. For instance:

Meter : Measure := (Length, Gain => 1.0,    Offset => 0.0);
Foot  : Measure := (Length, Gain => 0.3048, Offset => 0.0);

The subtype Dimensionless for dimensionless measures.

1.2.1. Shifted and unshifted Measures

The field Offset of the type Measure defines the value shift. Measures with zero offset are called unshifted. They form a field with addition and multiplication operations:

Meter : Measure := (Length, Gain => 1.0,    Offset => 0.0);
Foot  : Measure := (Length, Gain => 0.3048, Offset => 0.0);
. . .
Meter * Foot -- 0.3048 square meters
Meter + Foot -- 1.3048 m
Meter ** 2   -- 1 square meter

Most of physical units and all SI units are unshifted. Shifted measurement units are rare. Degrees of Celsius and Fahrenheit is an example of shifted units. The degree of Celsius can be defined as:

Celsius : Measure := (Temperature, Gain => 1.0, Offset => 273.15);

Actually, the field Offset should also be a discriminant of the type Measure. Unfortunately it is illegal in Ada. Measures of same dimension and shift form a set closed relatively addition, subtraction and multiplication to a number (i.e. a group). Therefore:

5.0 * Celsius     -- Legal, 5ºC = 278.15 K
Celsius + Celsius -- Legal, 2ºC = 275.15 K
Celsius * Celsius -- Illegal, Unit_Error is propagated

In other words, shifted measures can be neither multiplied nor divided, except when a shifted measure is multiplied to or divided by a dimensionless unshifted value as in the first example above. Note that addition and subtraction are only legal when dimension and shift are same for both operands:

Kelvin  : Measure := (Temperature, Gain => 1.0, Offset => 0.0);
Celsius : Measure := (Temperature, Gain => 1.0, Offset => 273.15);
. . .
Celsius + Kelvin -- Illegal, Unit_Error is propagated
Celsius * Kelvin -- Illegal, Unit_Error is propagated

Mixing of differently shifted measures is ambiguous. In the given example Celsius and Kelvin could be added if one would be converted to another:

Convert (Celsius, Kelvin) + Kelvin  -- +275.15 K (unshifted) = 2ºC
Celsius + Convert (Kelvin, Celsius) -- -271.15ºC (shifted)   = 2 K

Note that the numeric equivalent of the result depends on whether Celsius is converted to Kelvin or inversely. Even if two zeros (0ºC and 0 K) are added the results will differ:

Convert (0.0 * Celsius, Kelvin) + 0.0 * Kelvin  -- +273.15 K (0ºC)
0.0 * Celsius + Convert (0.0 * Kelvin, Celsius) -- -273.15ºC (0 K)

1.2.2. Operations defined on Measures

Unary operations:

function "abs" (Right : Measure) return Measure;
function "+"   (Right : Measure) return Measure;
function "-"   (Right : Measure) return Measure;

Exponentiation:

function "**" (Left : Measure; Right : Integer) return Measure;

Multiplication:

function "*" (Left : Number'Base; Right : Measure) return Measure;
function "*" (Left : Measure; Right : Number'Base) return Measure;
function "*" (Left, Right : Measure)               return Measure;

Division:

function "/" (Left : Number'Base; Right : Measure) return Measure;
function "/" (Left : Measure; Right : Number'Base) return Measure;
function "/" (Left, Right : Measure)               return Measure;

Addition and subtraction:

function "+" (Left, Right : Measure) return Measure;
function "-" (Left, Right : Measure) return Measure;

Comparisons:

function ">"  (Left, Right : Measure) return Boolean;
function "<"  (Left, Right : Measure) return Boolean;
function "="  (Left, Right : Measure) return Boolean;
function ">=" (Left, Right : Measure) return Boolean;
function "<=" (Left, Right : Measure) return Boolean;

The equality operator can be applied to any pair of measures. The inequality operation is implicitly defined by the compiler.

Scale shift (value destructive):

function "and" (Left : Measure; Right : Number'Base) return Measure;

The result of scale shift is formed by adding the value of the parameter Right to the field Offset. Note that the numeric SI equivalent of the result will differ from one of the parameter Left. For instance:

Celsius : constant Measure := K and 273.15; -- 1ºC (is not equal to 1 K)

See also the functions Normalize and Shift which perform scale shifts retaining the value.

The exception Constraint_Error is raised by the operations when the corresponding numeric operation does. This behaviour depends on whether Number’Machine_Overflows is true, as Ada Reference Manual states in 4.5.5 (22). Also Constraint_Error is propagated out of multiplicative operations "*", "/" and "**" when the dimension of the result cannot be represented as Unit because of a base unit power overflow.

1.2.3. Unit conversions

The function Get_Value returns a SI equivalent of the argument:

function Get_Value (Value : Measure) return Number;

The function Get_Value_As returns a numeric equivalent of the first argument in the measurement units defined by the second argument:

function Get_Value_As (Value, Scale : Measure) return Number;

For instance Get_Value_As (T, Celsius) returns the value of T in degrees of Celsius. The arguments Value and Scale should have same units. Otherwise the exception Unit_Error is propagated.

function Normalize (Value : Measure) return Measure;

The function Normalize returns an unshifted measure with the numeric equivalent same as one of the argument. For example:

Zero : Measure := Normalize (0.0 * Celsius); -- 273.15 K (non-shifted)

Here 0ºC is converted to its non-shifted equivalent 273.15 K.

function Shift (Value : Measure, Shift : Number'Base) return Measure;

The function Shift returns the argument shifted to Shift items. Unlike the operation and, the numeric equivalent of the result is same as one of the first argument. The value of the parameter Shift is subtracted from the field Gain and added to the field Offset to produce the result:

Zero : Measure := Shift (0.0 * Celsius, -273.15); -- 273.15 K

Here 0ºC is converted to its unshifted equivalent 273.15 K. Note that Normalize (X) is equivalent to Shift (X, X.Offset).

function Convert (Value, Scale : Measure) return Measure;

The function Convert is used for measurement unit conversions. The value of the first argument is converted to the measurement units of the second argument. The arguments Value and Scale should have same dimension. Otherwise the exception Unit_Error is propagated. Convert (X, Y) is an equivalent of Shift (X, Y.Offset - X.Offset). This is null operation if both arguments have same Offsets. Otherwise, the result has the shift of the second argument.

function To_Measure (Value : Number) return Measure;

This function returns a dimensionless unshifted measure corresponding to Value.

1.2.4. Constants

Few constants of the type Measure are defined in the package Measures. They correspond to the base SI measurement units: 

and dimensionless SI units:

^* Neper is not a SI unit. It is put here to have a constant for 1 SI other than rad. Actually Np = rad = sr

The generic package Measures_Derived defines the constants corresponding to the derived SI measurement units:

generic
   with package Measures is new Standard.Measures (<>);
package Measures_Derived is ...

The package defines the following constants:

The package Float_Measures_Derived is an instance of Measures_Derived for the standard type Float.

Further constants are defined in the generic package Measures_Irregular:

generic
   with package Derived_Measures is new Measures_Derived (<>);
package Measures_Irregular is ...

The package provides constants corresponding to various irregular units: 

The package Float_Measures_Irregular is an instance of Measures_Irregular for the type Float.

1.2.5. Elementary functions

The generic package Measures_Elementary_Functions

generic
   type Number is digits <>;
   with package The_Measures is new Measures (Number);
package Measures_Elementary_Functions is
   ...

provides the following functions:

function Sqrt (X : Measure) return Measure;

The function Sqrt is defined for the measures which unit has components with even exponent part. The exception Unit_Error is propagated otherwise. For instance:

Area : Measure := 25.0 * m**2;
Side : Measure;
. . .
Side := Sqrt (Area); -- OK, the result is 5 m
Side := Sqrt (Side); -- Error, Unit_Error propagates

Exponent and log functions require a dimensionless argument. The result is also dimensionless. Note that integer exponentiation is defined for all unshifted measures.

function Exp (X : Dimensionless) return Dimensionless;
function Log (X : Dimensionless) return Dimensionless;
function Log (X : Dimensionless; Base : Number'Base)
   return Dimensionless;

function "**" (Left : Dimensionless; Right : Dimensionless)
   return Dimensionless;
function "**" (Left : Dimensionless; Right : Number'Base)
   return Dimensionless;
function "**" (Left : Number'Base; Right : Dimensionless)
   return Dimensionless;

The trigonometric functions:

function Sin (X : Dimensionless) return Dimensionless;
function Cos (X : Dimensionless) return Dimensionless;
function Tan (X : Dimensionless) return Dimensionless;
function Cot (X : Dimensionless) return Dimensionless;

The argument of trigonometric functions is measured in radians (dimensionless). No variants with the parameter Cycle as in Ada.Numerics.Generic_Elementary_Functions are necessary, because arguments in degrees can be naturally expressed using units:

Cos (180.0 * degree); -- degree is declared in Measures_Irregular
Cos (3.1415 * rad);

The inverse trigonometric functions return the result measured in radians:

function Arcsin (X : Dimensionless) return Dimensionless;
function Arccos (X : Dimensionless) return Dimensionless;
function Arctan (X : Dimensionless) return Dimensionless;
function Arccot (X : Dimensionless) return Dimensionless;
function Arctan (Y, X : Measure) return Dimensionless;
function Arccot (X, Y : Measure) return Dimensionless;

Arctan and Arccot are defined for any pair of compatible unshifted measures (Unit_Error is propagated otherwise). For instance:

subtype Height is Measure (Length);
subtype Width is Measure (Length);
X : Width;
Y : Height;
Angle : Dimensionless; -- Radians
. . .
X := 25.0 * m;
Y := 30.1 * ft; -- ft (foot) is declared in Measures_Irregular
Angle := Arctan (Y, X);

Hyperbolical functions are defined on dimensionless argument:

function Sinh (X : Dimensionless) return Dimensionless;
function Cosh (X : Dimensionless) return Dimensionless;
function Tanh (X : Dimensionless) return Dimensionless;
function Coth (X : Dimensionless) return Dimensionless;

function Arcsinh (X : Dimensionless) return Dimensionless;
function Arccosh (X : Dimensionless) return Dimensionless;
function Arctanh (X : Dimensionless) return Dimensionless;
function Arccoth (X : Dimensionless) return Dimensionless;

The package instance for the type Float is named Float_Measures_Elementary_Functions.

1.2.6. Conversion from String

There are two encoding-specific generic packages responsible conversions of Measure to and from strings and one universal generic package for handling any encoding. The package Measures_Edit and the package Measures_UTF8_Edit are encoding-specific. Both packages have same formal parameters:

generic
   with package Irregular_Measures is new Measures_Irregular (<>);
   with package Float_Edit is
      new Strings_Edit.Float_Edit (Irregular_Measures.Measures_Of.Number);
package Measures_[UTF8_]Edit is ...

The package Measures_Edit is used for dealing with strings encoded in either ASCII or Latin-1 character sets. The package Measures_UTF8_Edit is used for the strings encoded in UTF-8 (see Unicode Transformation Format). The package Measures_UTF8_Edit instantiates Measures_Universal_Edit in its public part under the name Universal_Edit.

The routines provided by both packages are almost identical and differ only the sets of symbols supported. (The packages Float_Measures_Edit and Float_Measures_UTF8_Edit are instantiations of Measures_Edit and Measures_UTF8_Edit for the standard type Float.)

The following subroutines are used for measures input:

procedure Measures_Edit.Get
          (  Source  : String;
             Pointer : in out Integer;
             Value   : out Measure;
             Latin1  : Boolean := True
          );
procedure Measures_UTF8_Edit.Get
          (  Source  : String;
             Pointer : in out Integer;
             Value   : out Measure
          );

The procedures Get input a measure from the string Source. The process starts from the Source (Pointer) position. After successful completion Pointer is advanced to the position following the measure taken from the string. The parameter Value accepts the measure. The flag Latin1 of Measures_Edit.Get indicates Latin-1 character set support. With Latin1 = true the set of recognized symbols is extended as shown in the table below. The variant Measures_UTF8_Edit.Get is used for UTF-8 encoded strings. It supports an even larger set of symbols:

The measure syntax is:

<measure>	::=	( <measure> )
<measure>	::=	<measure> [<dyadic-operation>] <measure>
<measure>	::=	<prefix-operation><measure>
<measure>	::=	<measure><postfix-operation>
<measure>	::=	<number>
<measure>	::=	<unit>
<dyadic-operation>	::=	** | ^ | * | · | / | + | - | and
<prefix-operation>	::=	+ | -
<postfix-operation>	::=	<superscript-integer>

Space and tabs can be used as delimiters. Two consequent lexemes shall be separated by at least one delimiter if the first one ends with a letter while the second starts with a letter. For instance: 

As		Illegal, there is no any delimiter between A and s
A s		OK, A*s
A·s		OK, A*s
5A		OK, 5*A

The exponentiation operation (** or ^) has the highest priority. Then the multiplication (*, · or empty) follows. The division (/) has lower priority than the multiplication, therefore kg/m*s is an equivalent to kg/(m*s). The lowest priority has the shift (and). The right argument of the exponentiation operation should be dimensionless and have zero fraction, i.e. be convertible to an integer without a precision loss. <superscript-integer> is recognized only in UTF-8 variant and when Latin1 = true, but then only the powers 1, 2 and 3 are supported. <unit> is a name denoting a measurement unit, such as foot: 

<unit>	::=	<short-regular-unit> | <full-regular-unit> | <irregular-unit>
<short-regular-unit>	::=	[<short-SI-prefix>] <short-unit-name>
<full-regular-unit>	::=	[<full-SI-prefix>] <full-unit-name>

The following table defines <short-unit-name> and <full-unit-name>. Beware, all names are case sensitive:

Any regular unit name can be used with a SI prefix. The following table defines <short-SI-prefix> and <full-SI-name> (all names are case sensitive):

Note that short prefixes are used with short names, full prefixes are used with full names. For instance, the only legal notations of km are: km, kilometer, kilometre, kilometers, kilometres. The irregular unit names (<irregular-unit>) cannot be used with SI prefixes. They are (all names are case sensitive):

Examples:

34.5 * mm
65·km/h		65 km/h
65km/h		65 km/h
K and 273.15		degree Celsius
yd^2		one square yard
lb·yd²/s²		use of Latin-1 superscripts

procedure Measures_Edit.Get
          (  Source  : String;
             Pointer : in out Integer;
             Value   : out Scaled;
             Latin1  : Boolean := True
          );
procedure Measures_UTF8_Edit.Get
          (  Source  : String;
             Pointer : in out Integer;
             Value   : out Scaled
          );

These procedures input a measure in the form of a numeral multiplied by dimensioned scale. The syntax of measure and the parameters except Value are identical to corresponding procedures Get. The parameter Value has the type Scaled declared in the package Measures as follows:

type Value_Format is (Scalar, Numeric, Canonic, Jumbled);
type Scaled (Format : Value_Format := Canonic) is record
   Numeral : Number'Base;
   Scale   : Measure;
end record;

The input may fall into one of the following categories:

• Scalar is a numeric value with no scale specified. The field Numeral contains the value. The field Scale is 1 SI.;
• Numeric is a numeric value with numeric scale. The field Numeral is the value, the field Scale is the dimensionless scale of, with zero offset;
• Canonic is a numeric value with dimensioned scale. The field Numeral is the value, the field Scale is the scale of;
• Jumbled is any other value. The field Numeral is 1.0. The field Scale contains the value.

An input is Numeric or Canonic when the expression's outermost dyadic operation is either multiplication or division and its left argument is a number. Examples:

Scalar values:

		Numeral
2**2 + 1		5
45		45

Numeric values:

		Numeral		Scale
10*4		10		4
2 / 4 / 2		2		0.125 = (1/4)/2

Canonic values:

		Numeral		Scale
-34.5 * mm		-34.5		mm
3/s		3		Hz
10*4 feet		10		4 feet
1*(4 and 3)		1		4 shifted by 3
(2**2 + 1) m		5		m

Jumbled values:

km/h		There is no numeral given
(1 m)*s		The numeral is not a number
(1 m/m)*s		Same as above, even though it is dimensionless it is not a number

procedure Measures_Edit.Get_Unit
          (  Source  : String;
             Pointer : in out Integer;
             Value   : out Measure;
             Latin1  : Boolean := True
          );
procedure Measures_UTF8_Edit.Get_Unit
          (  Source  : String;
             Pointer : in out Integer;
             Value   : out Measure
          );

These procedures are restricted variant of the corresponding Gets. They recognize only measure units such as foot or meter. Irregular units and units with SI prefixes are recognized as well. No numbers or unit operations are recognized. Blanks are not skipped. This can be useful in syntax analyzers that may have different rules about operations and spaces. Such analyzer would rather use Get_Unit and then apply unit arithmetic for the operations it recognize. The meaning of the parameters is same as described for Get.

function Measures_Edit.Value
         (  Source : String;
            Latin1 : Boolean := True
         )  return Measure;
function Measures_UTF8_Edit.Value
         (  Source : String
         )  return Measure;

These functions get the measure from the string Source. They are simplified versions of the corresponding Get-procedures. The whole string should be matched. Otherwise the exception Data_Error is propagated. The following exceptions are propagated out of the functions:

1.2.7. Conversion to String

The packages Measures_Edit and Measures_UTF8_Edit provide the following subroutines for measures output:

procedure Measures_Edit.Put
          (  Destination : in out String;
             Pointer     : in out Integer;
             Value       : Measure;
             Latin1      : Boolean  := True;
             Derived     : Boolean  := True;
             RelSmall    : Positive := Strings_Edit.MaxSmall;
             AbsSmall    : Integer  :=-Strings_Edit.MaxSmall;
             Field       : Natural  := 0;
             Justify     : Strings_Edit.Alignment := Strings_Edit.Left;
             Fill        : Character := ' '
          );
procedure Measures_UTF8_Edit.Put
          (  Destination : in out String;
             Pointer     : in out Integer;
             Value       : Measure;
             Derived     : Boolean  := True;
             RelSmall    : Positive := Strings_Edit.MaxSmall;
             AbsSmall    : Integer  :=-Strings_Edit.MaxSmall;
             Field       : Natural  := 0;
             Justify     : Strings_Edit.Alignment := Strings_Edit.Left;
             Fill        : Character := ' '
          );

These procedures place the measure specified by the parameter Value into the output string Destination. The string is written starting from Destination (Pointer). The procedure from the package Measures_Editt has the parameter Latin1, which when true, allows using of Latin-1 characters listed in the table above, otherwise the output is done in ASCII. The procedure from the package Measures_UTF8_Edit uses UTF-8 encoded characters from the table. In all cases only the code positions in the table having white background are used in output. So for example in UTF-8 for Ohm, Greek omega is used rather than the Ohm sign.

The parameter Derived if true, allows derived SI units (such as N, F etc.) to appear in the output, and, additionally to them, °C. These units appear only alone or else with a numeric factor. They are not mixed with other units, like in N/s.

The parameters RelSmall and AbsSmall specify the precision of numeric output (see Strings_Edit.Float_Edit for further information). The procedure from the package Measures_Edit has additional optional parameters Field, Justify, Fill. When the parameter Field is not zero then Justify specifies alignment and Fill is the character used for filling. When Field is greater than Destination'Last - Pointer + 1, the latter is used instead. The UTF-8 variant from the package Measures_UTF8_Edit does not have these parameters because they would be meaningless for a UTF-8 encoded output. After successful completion Pointer is advanced to the first character following the output or to Destination'Last + 1. A measure can be output in one of the following forms:

For instance:

Text    : String (1..80);
Pointer : Positive := 1;
. . .
Put (Text, Pointer, 25.0*N, Derived => False, AbsSmall => 0);

will put 25·kg·m/s² into the string Text starting from the position 1. The parameter Derived=false forbids use of N (newton) in the output. Otherwise the result would be 25·N. The parameter AbsSmall=0 tells that the value has the precision ±0.5·10^AbsSmall-1, so only the digits before the decimal point are output. For further information about floating-point I/O see the description of the package Strings_Edit.

The procedure factors out SI prefixes of power 10^±3n. The prefix is then applied to the first unit, like for example in

25.7·km/s

Note that the parameter AbsSmall is corrected according to the prefix, so the effective small used for the output of <gain> (divided by 10^±3n) is AbsSmall - 3n. The choice of the prefix is influenced by AbsSmall to avoid, when possible, representations of gain with an exponent.

function Measures_Edit.Image
         (  Value    : Measure;
            Latin1   : Boolean  := True;
            Derived  : Boolean  := True;
            RelSmall : Positive := Strings_Edit.MaxSmall;
            AbsSmall : Integer  :=-Strings_Edit.MaxSmall
         )  return String;
function Measures_UTF8_Edit.Image
         (  Value    : Measure;
            Derived  : Boolean  := True;
            RelSmall : Positive := Strings_Edit.MaxSmall;
            AbsSmall : Integer  :=-Strings_Edit.MaxSmall
         )  return String;

The functions Image convert the parameter Value to string. The parameters Latin1, Derived, RelSmall and AbsSmall have same meaning as in Put (see).

1.2.8. Handling I/O in multiple encodings

The generic package Measures_Universal_Edit provides unified subroutines for string I/O with arbitrary encodings:

generic
   with package Irregular_Measures is new Measures_Irregular (<>);
   with package Float_Edit is
      new Strings_Edit.Float_Edit (Irregular_Measures.Measures_Of.Number);
package Measures_Universal_Edit is ...

The package provides a set of subroutines similar to ones of Measures_Edit and Measures_UTF8_Edit. They differs from the corresponding subroutines of these package in one additional parameter Mode, which for each subroutine determines the character set to be used. 

procedure Get
          (  Source  : String;
             Pointer : in out Integer;
             Value   : out Measure;
             Mode    : Code_Set
          );
procedure Get
          (  Source  : String;
             Pointer : in out Integer;
             Value   : out Scaled;
             Mode    : Code_Set
          );
procedure Get_Unit
          (  Source  : String;
             Pointer : in out Integer;
             Value   : out Measure;
             Mode    : Code_Set
          );
function Image
         (  Value    : Measure;
            Mode     : Code_Set;
            Derived  : Boolean  := True;
            RelSmall : Positive := Strings_Edit.MaxSmall;
            AbsSmall : Integer  := -Strings_Edit.MaxSmall
         )  return String;
function Value
         (  Source : String;
            Mode   : Code_Set
         )  return Measure;
procedure Put
          (  Destination : in out String;
             Pointer     : in out Integer;
             Value       : Measure;
             Mode        : Code_Set;
             Derived     : Boolean  := True;
             RelSmall    : Positive := Strings_Edit.MaxSmall;
             AbsSmall    : Integer  := -Strings_Edit.MaxSmall
          );

The parameter Mode has the enumeration type Code_Set. The meaning of the values is as follows:

• ASCII_Set is same as the corresponding subroutine of Measures_Edit with Latin1 false.
• Latin1_Set is same as Measures_Edit with Latin1 true.
• UTF8_Set is same as Measures_UTF8_Edit.

This package has a non-generic instance Float_Measures_Universal_Edit for the measures based on the standard type Float.

1.3. The type Complex_Measure

The generic package Generic_Complex_Measures provides complex dimensioned values:

generic
   with package Complex_Types is new Ada.Numerics.Generic_Complex_Types (<>);
   with package Real_Measures is new Measures (Complex_Types.Real);
package Generic_Complex_Measures is ...

The package provides the type Complex_Measure:

type Complex_Measure (SI : Unit := Units.Base.Unitless) is record
   Gain   : Complex;
   Offset : Number'Base := 0.0;
end record;

Here Number corresponds to the floating-point type used for instantiation of the complex and dimensioned types. The package Complex_Measures is an instance of Generic_Complex_Measures for the standard type Float.

1.3.1. Operations defined on Complex_Measures

Unary operations:

function "abs" (Right : Complex_Measure) return Measure;
function "+"   (Right : Complex_Measure) return Complex_Measure;
function "-"   (Right : Complex_Measure) return Complex_Measure;

The absolute value of a complex number is the square root of Re²+Im² with the same dimension.

Exponentiation:

function "**" (Left : Complex_Measure; Right : Integer) return Complex_Measure;

Multiplication:

function "*" (Left : Number'Base; Right : Complex_Measure) return Complex_Measure;
function "*" (Left : Imaginary;   Right : Measure)         return Complex_Measure;
function "*" (Left : Imaginary;   Right : Complex_Measure) return Complex_Measure;
function "*" (Left : Complex;     Right : Complex_Measure) return Complex_Measure;
function "*" (Left : Measure;     Right : Complex_Measure) return Complex_Measure;
function "*" (Left : Complex_Measure; Right : Number'Base) return Complex_Measure;
function "*" (Left : Measure;         Right : Imaginary)   return Complex_Measure;
function "*" (Left : Complex_Measure; Right : Imaginary)   return Complex_Measure;
function "*" (Left : Complex_Measure; Right : Complex)     return Complex_Measure;
function "*" (Left : Complex_Measure; Right : Measure)     return Complex_Measure;
function "*" (Left, Right : Complex_Measure)               return Complex_Measure;

Division:

function "/" (Left : Number'Base; Right : Complex_Measure) return Complex_Measure;
function "/" (Left : Imaginary;   Right : Measure)         return Complex_Measure;
function "/" (Left : Imaginary;   Right : Complex_Measure) return Complex_Measure;
function "/" (Left : Complex;     Right : Complex_Measure) return Complex_Measure;
function "/" (Left : Measure;     Right : Complex_Measure) return Complex_Measure;
function "/" (Left : Complex_Measure; Right : Number'Base) return Complex_Measure;
function "/" (Left : Measure;         Right : Imaginary)   return Complex_Measure;
function "/" (Left : Complex_Measure; Right : Imaginary)   return Complex_Measure;
function "/" (Left : Complex_Measure; Right : Complex)     return Complex_Measure;
function "/" (Left : Complex_Measure; Right : Measure)     return Complex_Measure;
function "/" (Left, Right : Complex_Measure)               return Complex_Measure;

Addition and subtraction:

function "+" (Left : Measure; Right : Complex_Measure) return Complex_Measure;
function "+" (Left : Complex_Measure; Right : Measure) return Complex_Measure;
function "+" (Left, Right : Complex_Measure)           return Complex_Measure;
function "-" (Left : Measure; Right : Complex_Measure) return Complex_Measure;
function "-" (Left : Complex_Measure; Right : Measure) return Complex_Measure;
function "-" (Left, Right : Complex_Measure)           return Complex_Measure;

Comparisons:

function "=" (Left, Right : Complex_Measure) return Boolean;

The equality operator can be applied to any pair of measures. The inequality operation is implicitly defined by the compiler.

Scale shift (value destructive):

function "and" (Left : Complex_Measure; Right : Number'Base) return Complex_Measure;

The result of scale shift is formed by adding the value of the parameter Right to the field Offset. Note that the numeric SI equivalent of the result will differ from one of the parameter Left.

function Conjugate (X : Complex_Measure) return Complex_Measure;

This function negates the imaginary part.

The exception Constraint_Error is raised by the operations when the corresponding numeric operation does. This behaviour depends on whether Number’Machine_Overflows is true, as Ada Reference Manual states in 4.5.5 (22). Also Constraint_Error is propagated out of multiplicative operations "*", "/" and "**" when the dimension of the result cannot be represented as Unit because of a base unit power overflow.

1.3.2. Unit conversions

function Get_Value (Value : Complex_Measure) return Complex;

The function Get_Value returns a SI equivalent of the argument:

function Get_Value_As (Value : Complex_Measure; Scale : Measure) return Complex;

The function Get_Value_As returns a numeric equivalent of the first argument in the measurement units defined by the second argument:

function Normalize (Value : Complex_Measure) return Complex_Measure;

This function returns an unshifted measure with the numeric equivalent same as one of the argument.

function Shift (Value : Complex_Measure; Shift : Number'Base) return Complex_Measure;

This function returns the argument shifted to Shift items.

function Convert (Value : Complex_Measure; Scale : Measure) return Complex_Measure;

The function Convert is used for measurement unit conversions. The value of the first argument is converted to the measurement units of the second argument. The arguments Value and Scale should have same dimension. Otherwise the exception Unit_Error is propagated.

function To_Measure (Value : Complex) return Complex_Measure;

This function returns a dimensionless unshifted measure corresponding to Value.

1.3.3. Cartesian

function Re (X : Complex_Measure) return Measure;
function Im (X : Complex_Measure) return Measure;

These functions extract the real and imaginary parts of the complex number.

function Compose_From_Cartesian (Re, Im : Measure) return Complex_Measure;
function Compose_From_Cartesian (Re     : Measure) return Complex_Measure;

These functions create a complex number from its real and imaginary parts. The parts must have exactly same units otherwise Units_Error is propagated.

procedure Set_Re (X : in out Complex_Measure; Re : Measure);
procedure Set_Im (X : in out Complex_Measure; Im : Measure);

These functions change an individual part of the complex number. The units must be compatible otherwise Units_Error is propagated.

1.3.4. Polar

function Modulus (X : Complex_Measure) return Measure;

This function returns the square root of Re²+Im² with the same dimension. It is same as "and".

function Argument (X : Complex_Measure) return Number'Base;
function Argument
         (  X     : Complex_Measure;
            Cycle : Number'Base
         )  return Number'Base;;

These functions return the complex number angle. The form with Cycle specifies the angle cycle if different from 2π.

function Compose_From_Polar
         (  Modulus  : Measure;
            Argument : Number'Base
         )  return Complex_Measure;
function Compose_From_Polar
         (  Modulus  : Measure;
            Argument : Number'Base;
            Cycle    : Number'Base
         )  return Complex_Measure;;

These functions create a complex number from the modulus and angle. The form with Cycle specifies the angle cycle if different from 2π.

1.4. GTK+ widgets

The described here packages use GtkAda, an Ada bindings to GTK+, a portable platform-independent graphical framework. To make use of this packages you need installed:

• GTK+ run-time and developing libraries installed;
• GtkAda installed. If you get a distribution of GtkAda it typically contains GTK+ run-time and libraries in it;
• GtkAda contributions. You can place the files of in the same directory as the source files of the measurements units for Ada.

1.4.1. Unit selection widget

The generic package Measures_Gtk_Edit provides an interactive unit selection widget. The widget might look like:

The widget consists of:

• an edit field, where a measurement unit can be directly input;
• an tree view widget that provides commonly used units divided into sections;
• a spin box, where the unit factor can be adjusted, if the unit selected is regular. The box disappears for irregular units or when the user starts to type the unit into the edit field.

The widget can be composed with other GTK+ widgets using standard widget packing techniques (see). It is also possibly to select a measurement unit in the form of a dialog, see the child package Measures_Gtk_Edit.Dialogs for further information.

The widget emits two signals, which are usually handled by a dialog window containing it. The dialog translates them into a response so that user could select a unit using simple button press or double click:

• commit is emitted when an enter key is pressed within the widget or else when upon a double click on a unit row in the tree view;
• reject is emitted when an escape key is pressed.

Selection of a unit in the tree view is intelligent. When the value in the edit field can interpreted as a numeral multiplied by a scale then the selected unit replaces the scale. If additionally the new unit is compatible with the old one, the numeral part is modified to retain the integral value. When the value in the edit field is not interpretable in the described form then the selected unit replaces it completely.

The package is declared as follows:

generic
   Class_Name : String;
   with package UTF8_Edit is new Measures_UTF8_Edit (<>);
package Measures_Gtk_Edit is ...

The formal parameters of the package is the name of the GTK+ class the widget will have. Class names are used in GTK+ to associate external resources like styles with the widget. The second parameter is an instance of the package Measures_UTF8_Edit.

There exists an instantiated version of Measures_Gtk_Edit for the standard floating point type: Gtk.Float_Measures_Edit..It is a child package of Gtk to make its naming consistent with the naming scheme used in GtkAda.

The package Measures_Gtk_Edit defines the following types:

type Gtk_Unit_Selection_Record is
   new Gtk_Box_Record with private;
type Gtk_Unit_Selection is
   access all Gtk_Unit_Selection_Record'Class;

The type Gtk_Unit_Selection_Record is the type of the widget object. The type Gtk_Unit_Selection is a reference type used to deal with the widget. This is the standard scheme used in GtkAda. One might need Gtk_Unit_Selection_Record only when a new widget type were derived from it. The following operations are defined in the package:

function Filter
         (  Widget : Gtk_Unit_Selection_Record;
            Value  : Measure
         )  return Boolean;

This is a primitive operation of Gtk_Unit_Selection_Record. A derived type might wish to override it. The function is used to filter out the measurement units, which cannot be selected. Such units do not appear in the tree view and are not accepted as direct input. The parameter Widget is the widget object. The parameter Value is a measurement unit to check. The function returns true if Value is acceptable. The default implementation returns false if Value is incompatible with the unit constraint set on Widget. Otherwise, or when no constraint is set, the result is true.

function Get
         (  Widget : not null access Gtk_Unit_Selection_Record
         )  return Measure;
function Get
         (  Widget : not null access Gtk_Unit_Selection_Record
         )  return GLib.UTF8_String;

These functions return the currently selected or otherwise input measure. It is the content of unit entry box. The value is checked using the function Filter and Constraint_Error is propagated when it does not match. The result is either the measure or its textual equivalent.

function Get_Entry
         (  Widget : not null access Gtk_Unit_Selection_Record
         )  return Gtk_Entry;

This functions returns the edit field of Widget.

function Get_Tree_View
         (  Widget : not null access Gtk_Unit_Selection_Record
         )  return Gtk_Tree_View;

This functions returns the tree view field of Widget.

function Get_Type return Gtk_Type;

This functions returns the GTK+ type of the widget.

procedure Gtk_New
          (  Widget     : out Gtk_Unit_Selection;
             Constraint : Unit;
             Initial    : UTF8_String := ""
          );
procedure Gtk_New
          (  Widget  : out Gtk_Unit_Selection;
             Initial : UTF8_String := ""
          );

These functions create a new widget. The parameter Initial specifies the initial selection. It can be any string. Note that Initial is not checked to be a valid measurement unit, neither it is passed through Filter. Instead it is accepted as-is. When Initial contains a valid measure that can be found in the tree view box, it is additionally selected there. This search is takes into account SI prefixes when measurement unit is regular. So, Initial "km" would select "m" with the SI prefix k for 10³. The parameter Constraint is optional. It specifies the unit to which the widget must be constrained. When specified, the default implementation of Filter will accept only the measures compatible with Constraint. The parameter Widget is the result.

procedure Initialize
          (  Widget     : not null access Gtk_Unit_Selection_Record'Class;
             Constraint : Unit;
             Initial    : UTF8_String := ""
          );
procedure Initialize
          (  Widget  : not null access Gtk_Unit_Selection_Record'Class;
             Initial : UTF8_String := ""
          );

These procedures perform initialization of the widget. In fact Gtk_New call to them internally. Any derived type shall call to them from its Initialize.

Style properties of the selection widget. All texts appearing in the widget can be changed using the style properties of the widget. The following table summarizes them:

The formal parameters of the package is the name of the GTK+ class the widget will have. Class names are using in GTK+ to associate external resources like styles with the widget. The second parameter is an instance of the package Measures_UTF8_Edit.

1.4.2. Dimensioned value entry

The child generic package Measures_Gtk_Edit.GEntry provides a widget having the functionality of a combo box for dimensioned values input. The widget is a descendant of Gtk_Entry. It also implements the GtkCellEditable interface and thus can be used with a tree view cell renderer to provide unit input in a tree view control. When focused a drop down box containing the unit selection list appears. The user can selecting a unit from the list and directly edit the content of the entry box.

generic
   type Custom_Unit_Selection_Record is
      new Gtk_Unit_Selection_Record with private;
package Measures_Gtk_Edit.GEntry is ...

The formal generic parameter is a unit selection widget type derived from Gtk_Unit_Selection_Record. This widget will be used within the entry. The class name of the widget is constructed from the class name specified in the actual generic parameter by adding "Entry" to it.

There exists an instantiated version of Measures_Gtk_Edit.GEntry for the standard floating point type: Gtk.Float_Measures_Entry..It is a child package of Gtk to make its naming consistent with the naming scheme used in GtkAda.

The package defines the type of the unit selection entry widget:

type Gtk_Unit_Entry_Record is
   new Gtk_Entry_Record with private;
type Gtk_Unit_Entry is
   access all Gtk_Unit_Entry_Record'Class;

The widget is a specialized entry. The entry is not directly editable. When user attempts to edit it a pop down window containing Custom_Unit_Selection_Record is shown. When the entry contains a text it is shown there. When the text is a valid measure it is selected in the unit selection tree. The user can change the selection or manually edit the measure. The editing is committed by pressing enter or cancelled by pressing escape keys. It is also cancelled by leaving the focus. When the editing is successful the result of becomes the new content of the entry. The following subprograms are defined in the package:

function Editing_Canceled (Widget : not null access Gtk_Unit_Entry_Record)
   return Measure;

This function return true if the last editing was cancelled by user. It is used in a cell renderer when it handles editing-done signal. At this point it would take the value from the widget when Editing_Canceled returns false, and ignore it otherwise.

function Get
         (  Widget : not null access Gtk_Unit_Entry_Record
         )  return Measure;
function Get
         (  Widget : not null access Gtk_Unit_Entry_Record;
            Scale  : Measure
         )  return Measure;

This function parses the entry text and returns it as a measure. The result is checked against the Widget's constraint if any. Constraint_Error is propagated if unit does not match. When the parameter Scale is specified is shall have the units compatible with the Widget's constraint. Otherwise Constraint_Error is propagated. When the widget is unconstrained Scale is ignored. When the widget is constrained and Scale is specified then a numeric content of the widget is treated as a valid measure by multiplying to Scale. When the content is dimensioned, Scale is ignored. Note that the Set_Numeric has no effect on this behaviour.

function Get_Constraint
         (  Widget : not null access Gtk_Unit_Entry_Record
         )  return Unit;

This function returns the current widget constraint. Constraint_Error is propagated when Widget is unconstrained.

function Get_Type return Gtk_Type;

This functions returns the GTK+ type of the widget.

procedure Gtk_New
          (  Widget     : out Gtk_Unit_Entry_Record;
             Constraint : Unit;
             Initial    : GLib.UTF8_String := ""
          );
procedure Gtk_New
          (  Widget  : out Gtk_Unit_Entry_Record;
             Initial : GLib.UTF8_String := ""
          );

These functions create a new widget. The parameter Initial specifies the initial content of the entry. It can be any string. Note that Initial is not checked to be a valid measurement unit, neither it is passed through Filter of the type Custom_Unit_Selection_Record as specified in the generic formal parameter of the package. The parameter Constraint is optional. It specifies the unit to which the widget must be constrained. When specified, the default implementation of Filter will accept only the measures compatible with Constraint. The parameter Widget is the result.

procedure Initialize
          (  Widget     : not null access Gtk_Unit_Entry_Record'Class;
             Constraint : Unit;
             Initial    : GLib.UTF8_String := ""
          );
procedure Initialize
          (  Widget  : not null access Gtk_Unit_Entry_Record'Class;
             Initial : GLib.UTF8_String := ""
          );

These procedures perform initialization of the widget. In fact Gtk_New call to them internally. Any derived type shall call to them from its Initialize.

function Is_Constrained
         (  Widget : not null access Gtk_Unit_Entry_Record
         )  return Boolean;

This function returns true if the widget is constrained to a specific unit.

function Is_Numeric
         (  Widget : not null access Gtk_Unit_Entry_Record
         )  return Boolean;

This function returns true if the widget allows numeric values when editable. This is the default.

procedure Reset_Constraint
          (  Widget : not null access Gtk_Unit_Entry_Record
          );

This procedure removes the unit constraint if any. Note that if the drop-down window is visible, the operation will not have effect on its content.

procedure Set_Constraint
          (  Widget     : not null access Gtk_Unit_Entry_Record;
             Constraint : Unit
          );

This procedure sets/replaces widget's unit constraint. The parameter Constraint is the new constraint to set. Note that if the drop-down window is visible, the operation will not have effect on its content.

procedure Set_Numeric
          (  Widget  : not null access Gtk_Unit_Entry_Record;
             Allowed : Boolean
          );

This procedure controls the Widget's behaviour when the input is a plain number and the widget is constrained to non-dimensionless values. In this case specifying a plain number is allowed, otherwise such input causes unit mismatch error.

Style properties of the unit entry widget. The following table summarizes them:

1.4.3. Dimensioned value cell renderer

The child generic package Measures_Gtk_Edit.GEntry.Cell_Renderer provides an editable cell renderer for GTK+ tree view widget. The renderer indicates dimensioned values as fixed-point numbers in using the specified scale. When edited, the renderer drops down a unit selection list. The user can select a unit from the list and edit the value entry. The input when the dimensioned is automatically converted to the scale of the renderer. When the input contains no units there the value is assumed specified in the renderer's scale. The renderer rejects any improperly dimensioned input. The renderer class name of the widget is constructed from the class name specified in the actual generic parameter of its parent by adding "CellRenderer" to it.

generic
package Measures_Gtk_Edit.GEntry.Cell_Renderer is ...

There exists an instantiated version of Measures_Gtk_Edit.GEntry.Cell_Renderer for the standard floating point type: Gtk.Float_Measures_Cell_Renderer..It is a child package of Gtk to make its naming consistent with the naming scheme used in GtkAda.

The package defines the type of the renderer:

type Gtk_Cell_Renderer_Measure_Record is
   new Gtk_Abstract_Renderer_Record with private;
type Gtk_Cell_Renderer_Measure is
   access all Gtk_Cell_Renderer_Measure_Record'Class;

The following subprograms are defined:

function Get (Cell : not null access Gtk_Cell_Renderer_Measure_Record)
   return Number;
function Get (Cell : not null access Gtk_Cell_Renderer_Measure_Record)
   return Measure;
function Get (Cell : not null access Gtk_Cell_Renderer_Measure_Record)
   return GValue;
function Get (Cell : not null access Gtk_Cell_Renderer_Measure_Record)
   return UTF8_String;

These functions are used to query the rendered value. It can be obtained as:

• a plain number scaled to the renderer's scale;
• measure;
• GTK+ value of the type GType_Double scaled to the renderer's scale;
• String composed out of the rendered value followed by the scale specification text of the renderer.

function Get_Type return Gtk_Type;

This functions returns the GTK+ type of the renderer.

procedure Gtk_New
          (  Cell  : out Gtk_Cell_Renderer_Measure;
             Scale : UTF8_String := "";
             After : Natural     := 0;
          );

This procedure creates a new renderer. The result is returned through the parameter Cell .The parameter Scale determines the dimension and the multiplier of the edited values. It must be a valid measure specification for Measures_UTF8_Edit. Further the gain of the measure has to be non-negative otherwise Constraint_Error is propagated. When Scale is specified empty, it assumed to be 1 SI. The parameter After specifies the number of decimal positions after the decimal point for the rendered values. Observe that the values are rendered in Scale.

procedure Initialize
          (  Cell  : not null access Gtk_Cell_Renderer_Measure_Record'Class;
             Scale : UTF8_String := "";
             After : Natural     := 0;
          );

This procedure is called by any derived type from its Initialize.

procedure Put
          (  Cell  : not null access Gtk_Cell_Renderer_Measure_Record;
             Value : Number
          );
procedure Put
          (  Cell  : not null access Gtk_Cell_Renderer_Measure_Record;
             Value : Measure
          );
procedure Put
          (  Cell  : not null access Gtk_Cell_Renderer_Measure_Record;
             Value : UTF8_String
          );
procedure Put
          (  Cell  : not null access Gtk_Cell_Renderer_Measure_Record;
             Value : GValue
          );

These functions are used to set the rendered value. It can be one of the following types:

• a plain number scaled to the renderer's scale;
• measure, Unit_Error is propagated when Value has the units incompatible with Cell;
• GTK+ value of the type GType_Double scaled to the renderer's scale or else GType_String. When the value is of GType_String, the effect is same as if it were passed as string;
• String containing a measure in the format of Measures_UTF8_Edit. The value when dimensioned is treated as if it were passed as a measure. When the value is dimensionless the effect is same as if it was passed as a plain number.

Properties of the renderer. The following table summarizes them:

1.4.4. Unit selection dialogs

The child generic package Measures_Gtk_Edit.Dialogs provides a simple way to query for a measurement unit from a dialog box:

generic
   type Custom_Unit_Selection_Record is
      new Gtk_Unit_Selection_Record with private;
package Measures_Gtk_Edit.Dialogs is ...

The formal generic parameter is a unit selection widget type derived from Gtk_Unit_Selection_Record. This widget will be used within the dialog. The package provides the following subprograms:

function Get
         (  Constraint   : Unit;
            Initial      : GLib.UTF8_String := "";
            Title        : GLib.UTF8_String := "Unit selection";
            Confirm      : GLib.UTF8_String := "gtk-ok";
            Cancel       : GLib.UTF8_String := "gtk-cancel";
            Parent       : Gtk_Window       := null;
            Flags        : Gtk_Dialog_Flags := Modal;
            Missing      : GLib.UTF8_String := "No unit specified";
            Erroneous    : GLib.UTF8_String := "Illegal unit";
            Incompatible : GLib.UTF8_String := "Incompatible unit"
         )  return GLib.UTF8_String;
function Get
         (  ... -- Same parameters as above
         )  return Measure;
function Get
         (  ... -- Same parameters as above, without Constraint
         )  return GLib.UTF8_String;
function Get
         (  ... -- Same parameters as above, without Constraint
         )  return Measure;

These function cause a dialog to appear. The dialog has the unit selection widget in it and up to two buttons. A function does not return until the dialog closes. When the user presses the OK button, which label is specified by the parameter Confirm, the selected measurement unit is checked for validity and it is the result of the function. The result is either a string or a measure. On failed checks the dialog does not end and an appropriate message text is shown as the parameters Missing, Erroneous and Incompatible specify. When the parameter Cancel is not an empty string, the Cancel button is shown. When the dialog box is closed using the window manager or the Cancel button, the functions propagate End_Error exception. The button names can refer to GTK+ stock buttons, as the default values do. Otherwise, the underline character within the name refer to the hot-key character. The parameter Constraint limits the measurement unit to a specific dimension. In the example shown on the figure it was Units.Base.Length. When Constraint is omitted, any valid measurement unit is acceptable. An additional or alternative constraint can be imposed by the type Cunstom_Unit_Selection_Record, as Filter describes. Title is the dialog window title. Parent is the parent window of. The parameter Flags is the dialog flags.

The package has an instantiated version for the standard floating-point type: Gtk.Float_Measures_Dialogs.

2. Packages

Two separate sets of packages implement the types Unit and the type Measure. There is also a set of supporting packages used internally.

2.1. The packages related to the type Unit

The packages related to the type Unit:

2.2. The packages related to the type Measure

The following packages are related to the type Measure:

The following example shows how the generic packages are instantiated:

with Measures;
with Measures_Derived;
with Measures_Irregular;
with Measures_Edit;
with Strings_Edit.Float_Edit;
   . . .
type Real is digits ...;
--
-- Instantiation of Measures with the type Real as the parameter
--
package Real_Measures is new Measures (Real);
--
-- Instantiation of Measures_Derived
--
package Real_Measures_Derived is new Measures_Derived (Real_Measures);
--
-- Instantiation Measures_Irregular
--
package Real_Measures_Irregular is
   new Measures_Irregular (Real_Measures_Derived);
--
-- Instantiation Measures_Edit
--
package Real_Edit is new Strings_Edit.Float_Edit (Real);
--
-- Instantiation Measures_Edit
--
package Real_Measures_Edit is
   new Measures_Derived
       (  Real_Measures_Irregular,
          Real_Edit
       );

2.3. Packages defined for internal use

The software uses the packages Strings_edit and Tables. The following table shows the packages defined for internal use:

3. Examples

3.1. Self-tests

The subdirectory test_units contains various tests.

The file test_measures.adb contains a test program for the packages Measures and Units. It also estimates the performance hit when the type Measure is used for calculations instead of Float. With GNAT compiler the program can be built using gnatmake:

>gnatmake -I.. test_measures.adb

The file test_gtk_unit_selection.adb is a test program for GTK+. To build it one needs installed:

• GTK+;
• GtkAda;
• GtkAda contributions.

Provided that GtkAda contributions is placed in the directory gtkada on the same level as the root directory of this software the command line to build test_gtk_unit_selection might look under Linux as:

>gnatmake -I.. -I../../gtkada test_gtk_unit_selection.adb `gtkada-config`

Under Windows instead of automatic configuration of GtkAda paths, you should specify the install directory of GtkAda implicitly:

>gnatmake -I.. -I../../gtkada -IC:/GtkAda/include/gtkada test_gtk_unit_selection.adb

3.2. Unit converters and mappers

The subdirectory units-examples contains a simple sample programs which convert dimensioned values.

3.2.1. Unit converter for Win32

The following is the full source code of the converter. It is located in units-examples→units-converter→win32. The fragments relevant to dealing with units are highlighted yellow. The rest is dealing with Windows API. The program uses Windows Unicode support. For this measures input and output is performed in UTF-8 format using the package Float_Measures_UTF8_Edit. Note that Windows uses UTF-16 encoding therefore all strings are converted from Wide_String to UTF-8 and back using subroutines of the package Strings_Edit.UTF8.Handling.

Implementation, file units_converter.adb:

3.2.2. Unit converter for GTK+

GTK+ is a platform-independent library for creating graphical applications. It is available for a wide range of platforms which includes Windows and Linux. The following is the full source code of the converter based on GTK+. It is located in units-examples→units-converter→gtk. The fragments relevant to dealing with units are highlighted yellow. The rest is dealing with GTK+. Note that GTK+ natively supports UTF-8, so the package Float_Measures_UTF8_Edit is used without any further translation.

Implementation, file units_converter.adb:

To compile this example you will need GTK+, and GtkAda bindings installed.

3.2.3. Unit mapper for GTK+

Unit mapper is a small GUI program that converts values from one unit to another. It is located in units-examples→units-mapper. The source code:

Implementation, file units_mapper.adb:

Here we do standard GTK+ stuff plus the variables for from and to fields of the mapper.

Implementation, file units_mapper.adb (continued):

This piece is used to circumvent accessibility checks in order to keep the program in one file. Normally if the signal handler is declared at the library level no unchecked conversion is needed.

Implementation, file units_mapper.adb (continued):

This is the procedure called when the from field gets changed. It converts it to the units of the to field and changes the corresponding entry box. The variable Ignore is used prevent an infinite recursion of reactions on changes in the entry boxes.

Implementation, file units_mapper.adb (continued):

This is the procedure called when the to field gets changed. It converts it to the units of the from field and changes the corresponding entry box.

Implementation, file units_mapper.adb (continued):

This is the procedure called when a unit field gets changed. It converts the from field. The to field update automatically follows per change notification.

Implementation, file units_mapper.adb (continued):

4. Installation

The software does not require special installation. The archive's content can be put in a directory and used as-is. For users of GNAT compiler the software provides gpr project files, which can be used in the Gnat Programming Studio (GPS).

For CentOS, Debian, Fedora, Ubuntu Linux distributions there are pre-compiled packages see the links on the top of the page.

The packages based on GtkAda require it and the GtkAda Contributions installed. When these packages are not planned for use, the corresponding failures during the installation can be safely ignored.

5. Changes log

The following versions were tested with the compilers:

• GNAT Studio Community 2020 (20200427)
• GNAT Community 2018 (20180523-73)
• GNAT 8-12

and the GtkAda versions:

• GtkAda 3.14.15
• GtkAda April 5, 2022 (GTK 3.24.33)

Changes (22 April 2023) to the version 3.12:

• The package Generic_Complex_Measures was added to provide dimensioned complex values;
• The package Complex_Measures added as an instance of Generic_Complex_Measures with the type Float.

Changes (26 November 2022) to the version 3.11:

• Added four new SI prefixes adopted by General Conference on Weights and Measures (CGPM) in November 2022.

Changes (22 May 2022) to the version 3.10:

• Adapted to GNAT 12.1 and Fedora 36.

Changes (16 April 2022) to the version 3.9:

• GNAT Studio Community 2021 bugs worked around;
• GTK 3.24.x support.

Changes (31 May 2020) to the version 3.8:

• Code cleanup;
• Adapted to GNAT Studio Community 2020;

The following versions were tested with the compilers:

• GNAT Community 2018 (20180523-73)
• GNAT 8

and the GtkAda versions:

• GtkAda 3.14.15

Changes (5 Aug 2018) to the version 3.7:

• Compatibility with GtkAda 3.14.15;
• All Windows examples changed to 64-bit;
• The example Units_Converter was changed to be independent on Win32Ada bindings as they are no more available for GNAT Community 2018;
• Units_Converter for Windows can be built using gprbuild only.

The following versions were tested with the compilers:

• GNAT GPL 2016 (20160515-49)
• GNAT 6

and the GtkAda versions:

• GtkAda 3.14.2

Changes (25 July 2016) to the version 3.6:

• Compatibility with GtkAda 3.14

The following versions were tested with the compilers:

• GNAT GPL 2015 (20150428-49)
• GNAT 5.3

and the GtkAda versions:

• GtkAda 3.8.3

Changes (29 June 2015) to the version 3.5:

• Adapted to GNAT GPL 2015 and GtkAda 3.8.3.

The following versions were tested with the compilers:

• GNAT GPL 2014 (20140331)
• GNAT 4.8.2 (20131212)
• GNAT 4.9.0

and the GtkAda versions:

• GtkAda 3.8.2

Changes (2 April 2015) to the version 3.4:

• ARMv7 (AKA armhf) support.

Changes  (1 June 2014) to the version 3.3:

• The widgets and renderers are adapted for the GTK 3.x. GTK 2.x is no more supported;
• Procedure Split is added to the package Units;
• Only Ada 2005 and Ada 2012 are supported when widgets and renderes are used. The non-GUI parts of the software remain Ada 95 conform;
• Bug fix in text conversion that led to false output of values with units like square meter;
• Compiled with GNAT 4.9.

The following versions were tested with the compilers:

• GNAT Pro 6.4.2 (20110614-4)
• GNAT 4.6.2 (20111027)

and the GtkAda versions:

• GtkAda 2.18, 2.24

Changes to the version 3.2 (27 April 2013):

• The value of the constant hp (Horsepower) fixed in the package Measures_Irregular.

Changes to the version 3.1:

• The procedure Put in Measures_UTF8_Edit has additional parameters Field, Justify, Fill;
• Fedora and Debian packages are provided for both 32- and 64-bit architectures.

Changes to the version 3.0:

• Packaged for Debian and Fedora.

The following versions were tested with the compilers:

• GNAT Pro 6.2.1 (20090115-43)
• GNAT GPL 2009 (20090519)

and the GtkAda:

• GtkAda GPL 2.14

Changes to the version 2.9.

• Output of exact zero values uses power 1 with any small. E.g. 0W is output as 0·W rather than 0·yW.

Changes to the version 2.8.

• SI prefixes are used for dimensioned output;
• GNAT project files reworked;
• Minor bug fixes;
• Installation instructions added.

The following versions were tested with the compilers:

• GNAT GPL 2008 (20080521)

and the GtkAda:

• GtkAda GPL 2.10.2

Changes to the version 2.7.

• Added irregular units dram, gill, league;
• Added SI derived unit katal (kat);
• Removed irregular unit candle;
• Bq was moved to derived SI units;
• Unicode ounce sign is now supported;
• Bug fix in Get_Value_As;
• Conversion factors verified and corrected, references to the sources provided in the documentation.

Changes to the version 2.6.

• The implementations of popup windows were modified in order to fit GtkAda 2.10.2.

The following versions were tested with the compilers:

• GNAT  4.1.2 20070502;
• GNAT GPL 2007 (20070405-41).

and the GtkAda:

• GtkAda GPL 2.10.0 (An unofficial binary release for Windows can be found at www.ada-ru.org/win_bin_en, For Linux it is officially available in sources and can be routinely compiled from.)

Changes to the version 2.5.

• This version is aimed to work with GtkAda 2.10.0. Note that it is not compatible with earlier GtkAda 2.8.0;
• The widget Gtk_Unit_Selection was modified to keep track of the value set in it. When the value is interpretable as a value with the scale, then selection of another unit retains its numeral component.

The following versions were tested with the compilers:

• GNAT  4.1.2 20070502;
• GNAT GPL 2007 (20070405-41).

and the GtkAda:

• GtkAda GPL 2.8.0

Changes to the version 2.4.

• The procedure Get was added for parsing measures as a numeral multiplied by dimensioned scale.

Changes to the version 2.3.

• A GTK program sample for mapping dimensioned values;
• The package Measures_UTF8_Edit publicly instantiates Measures_Universal_Edit;
• The package Measures_Gtk_Edit.GEntry provides dimensioned values editing entry;
• The package Measures_Gtk_Edit.GEntry.Cell_Renderer provides dimensioned values tree view cell renderer.

Changes to the version 2.2.

• For GNAT users GPS project files were added.

The following versions were tested with the compilers:

• GNAT 4.1.1 20070105;
• GNAT GPL 2006 (20060522-34).

Note that GNAT GPL 2006 distribution for Windows has a bug in the installation files that prevents GtkAda programs from being linked. To fix it you should replace all GTK+ DLLs in the directory GNAT/bin with the same named DLLs from the directory GtkAda/bin.

and the GtkAda:

• GtkAda GPL 2.8.0

Changes to the version 2.1.:

• GTK+ unit selection widget added

The following versions were tested with the compilers:

• GNAT 2005, GCC 4.0.2 (20051125);
• GNAT 3.15p.

Changes to the version 2.0.:

• Conformity with Ada 2005

The following versions were tested with GNAT 3.15p compiler.

Changes to the version 1.8:

• The exception Unit_Error was moved to the package Units;
• GetValue, GetValueAs, GetUnit functions were renamed to Get_Value, Get_Value_As, Get_Unit to be conform with the established naming tradition in Ada;
• Instantiation of generic packages was simplified;
• The package Measures_Universal_Edit was added to provide string I/O for multiple character sets.

Changes to the version 1.7:

• Get_Unit procedure was added for input pure measurement units (expression terms) rather than measures (arbitrary expression);
• To_Measure was added for explicit number to measure conversion;
• Documentation bugs were fixed.

Changes to the version 1.6:

• Change in multiplication and division of shifted measures. An unshifted dimensionless measure can now be mixed with a shifted one in * and /;
• UTF-8 encoding support;
• Minor bug fix in units converter examples: Unit_Error is now caught;
• The package Units has the new child Units.Edit. The function Image is moved there;
• Units converter for GTK is now statically linked for i686 target;
• Units converter for Windows supports Unicode.

Changes to the version 1.5:

• Platform independent units converter sample for GTK;
• Bug fix in unit input, the conflict between SI prefix and unit name in cases P(petto) vs. Pa is now correctly resolved.

Changes to the version 1.4:

• Licensing wording was corrected to comply with GMGPL

Changes to the version 1.3:

• The Get procedures will raise Constraint_Error on numeric errors even if T’Machine_Overflows is not true

6. Table of Contents