eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'UnitConverter':

Home

Documentation
www.exept.de
Everywhere
for:
 [back]

Class: UnitConverter

Inheritance:

   Object
   |
   +--UnitConverter
Package:
stx:libbasic2
Category:
Magnitude-General
Version:
rev: 1.68 date: 2021/11/13 13:31:13
user: cg
file: UnitConverter.st directory: libbasic2
module: stx stc-classLibrary: libbasic2

Description:


In order to collect various unit conversions into one central
manageable (and especially: browsable) place, all previously
spread knowledge about metric (and other) conversions has been
brought into this class.

This class is purely functional, abstract and has no instances;
all queries are via class protocol.
Choosing the Magnitudes category as its home is arbitrary.

The supported units are setup in the classes initialize method;
supported are:
    meter - inch - feet - foot - yard
    meter2 - acre - 'german-ar' 'german-hektar' are
    liter - gallon - barrel - floz
    celsius - fahrenheit
and many others.

The converter does a recursive search for a conversion;
thus, if there is a conversion from #inch to #millimeter and another 
from #millimeter to #kilometer, conversion from #inch to #kilometer
is found automatically.

No Warranty:
    The numbers and conversion factors were obtained from the Unix
    units command. Please check before using it - there might be
    typos or wrong conversions in the setup code.

Notice:
    This class is *much* older than the younger and more object oriented
    Measurements or PhysicalValues packages. 
    Other than solving similar problems, these two packages are not related.


see also:
    examples
    /usr/share/lib/unittab (if present on your system)
    Measurement Unit Physic::PhysicalUnit


copyright
COPYRIGHT (c) 1996 eXept Software AG
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

Class protocol:

accessing
o  scalings
return the set of known scaling prefixes

Usage example(s): 

     UnitConverter scalings

o  units
return the set of known units

Usage example(s): 

     UnitConverter units

conversion
o  convert: howMany from: sourceUnit to: destUnit
given a value in sourceUnit (symbolic), try to convert it
to destUnit (symbolic); return nil, if the conversion is
unknown.

Usage example(s): 

direct - how many meters are there in two inches:
     UnitConverter convert:2 from:#inch to:#meter   
     
     reverse - how many inches are there in one meter
     UnitConverter convert:1 from:#meter to:#inch   

     with alias:
     UnitConverter convert:1 from:#inch to:#m    
     UnitConverter convert:1 from:#inch to:#mm          
     UnitConverter convert:1 from:#inch to:#millimeter   
     UnitConverter convert:1 from:#inch to:#nanometer 
     UnitConverter convert:1 from:#mm to:#km  
     UnitConverter convert:1 from:#km to:#foot   

     indirect:
     UnitConverter convert:1 from:#mm   to:#twip  
     UnitConverter convert:1 from:#inch to:#twip  
     UnitConverter convert:1 from:'letterH' to:#point  
     UnitConverter convert:1 from:'letterlH' to:#point  

     UnitConverter convert:5 from:#barrel to:#liter  
     UnitConverter convert:10 from:#kilogram to:#carat  

     UnitConverter convert:1 from:#liter to:#floz  
     UnitConverter convert:1 from:#floz to:#liter  
     UnitConverter convert:1 from:#oz to:#gram  
     UnitConverter convert:1 from:#ounce to:#gram  

     UnitConverter convert:37 from:#celsius to:#fahrenheit  -> 98.6    
     UnitConverter convert:37 from:#celsius to:#kelvin      -> 310.15
     UnitConverter convert:0 from:#celsius to:#kelvin       -> 273.15  
     UnitConverter convert:0 from:#kelvin to:#celsius       -> -273.15 
     UnitConverter convert:0 from:#kelvin to:#fahrenheit    -> -459.67    
     UnitConverter convert:0 from:#fahrenheit to:#celsius   -> -17.7777777777778    
     UnitConverter convert:0 from:#fahrenheit to:#kelvin    -> 255.372222222222

o  convert: howMany from: sourceUnit to: destUnit pairsAlreadyTried: pairsAlready
given a value in sourceUnit (symbolic), try to convert it
to destUnit (symbolic); return nil, if the conversion is
unknown.

Usage example(s): 

direct - how many meters are there in two inches:
     UnitConverter convert:2 from:#inch to:#meter     
     UnitConverter convert:37 from:#degrees to:#fahrenheit     

     reverse - how many inches are there in one meter
     UnitConverter convert:1 from:#meter to:#inch   

     with alias:
     UnitConverter convert:1 from:#inch to:#m    
     UnitConverter convert:1 from:#inch to:#mm          
     UnitConverter convert:1 from:#inch to:#millimeter   
     UnitConverter convert:1 from:#inch to:#nanometer 
     UnitConverter convert:1 from:#mm to:#km  
     UnitConverter convert:1 from:#km to:#foot   

     indirect:
     UnitConverter convert:1 from:#mm   to:#twip  
     UnitConverter convert:1 from:#inch to:#twip  
     UnitConverter convert:1 from:'letterH' to:#point  
     UnitConverter convert:1 from:'letterlH' to:#point  

     UnitConverter convert:5 from:#barrel to:#liter  
     UnitConverter convert:10 from:#kilogram to:#carat  

     UnitConverter convert:1 from:#liter to:#floz  
     UnitConverter convert:1 from:#liter to:'m^3'  
     UnitConverter convert:1 from:'m^3' to:#liter  
     UnitConverter convert:0 from:#fahrenheit to:#kelvin  
     UnitConverter convert:0 from:#fahrenheit to:#celsius  
     UnitConverter convert:0 from:#celsius to:#kelvin  
     UnitConverter convert:0 from:#kelvin to:#celsius

o  fileSizeBinaryStringFor: nBytes
return a useful string for a size-in-bytes in programmer's notation;
Scales by Ki (*1024), Mi (*1024*1024) or Gi (*1024*1024*1024) or even Ti
as required and useful.
Provided here since this is so common...
Notice: the scale is 1024
the 1024 scale has been standardized in 1998 by IEC to MiB, GiB, etc.
See https://en.wikipedia.org/wiki/Mebibyte

o  fileSizeFromString: fileSizeString
given a fileSize string (i.e. a number followed by optional kB, MB, GB etc. or KiB, MiB, GiB,...).
Notice that in 1998, IEC standardized the scales to 1000 for k,M,G,... and 1024 for Ki, Mi, Gi, etc.
See https://en.wikipedia.org/wiki/Mebibyte.
Provided here since this is so common...

Usage example(s): 

     self fileSizeFromString:'1234'          
     self fileSizeFromString:'10 k'            
     self fileSizeFromString:'10 kB'            
     self fileSizeFromString:'10 KiB'            
     self fileSizeFromString:'0.6 k'            
     self fileSizeFromString:'1.8 M'            
     self fileSizeFromString:'1.8 MB'            
     self fileSizeFromString:'1.8 MiB'            
     self fileSizeFromString:'0.5 G'            
     self fileSizeFromString:'0.5 T'            
     self fileSizeFromString:'0.5 P'            
     self fileSizeFromString:'0.5 E'

o  fileSizeSIStringFor: nBytes
return a useful string for a size-in-bytes in SI standard notation;
Scales by K (*1000), M (*1000*1000) or G (*1000*1000*1000) or even T
as required and useful.
Provided here since this is so common...
Notice: the scale is 1000
the 1000 scale has been standardized in 1998 by IEC to MB, GB, etc.
See https://en.wikipedia.org/wiki/Mebibyte

o  fileSizeStringFor: nBytes
return a useful string for a size-in-bytes.
Scales either by 1000 or 1024, depending on the user preferences.
See https://en.wikipedia.org/wiki/Mebibyte

Usage example(s): 

     self fileSizeStringFor:nil          
     self fileSizeStringFor:10          
     self fileSizeStringFor:100            
     self fileSizeStringFor:1000            
     self fileSizeStringFor:8192            
     self fileSizeStringFor:10000          
     self fileSizeStringFor:100000          
     self fileSizeStringFor:1000000        
     self fileSizeStringFor:10000000       
     self fileSizeStringFor:100000000      
     self fileSizeStringFor:1000000000      
     self fileSizeStringFor:10000000000      
     self fileSizeStringFor:100000000000      
     self fileSizeStringFor:1000000000000      
     self fileSizeStringFor:10000000000000      
     self fileSizeStringFor:10000000000000000      
     self fileSizeStringFor:100000000000000000000      
     self fileSizeStringFor:1000000000000000000000

o  frequencyFromString: frequencyString
given a frequency string (i.e. a number followed by optional kHz, Mhz or Hhz as required.
Provided here since this is so common...

Usage example(s): 

     self frequencyFromString:'1234'          
     self frequencyFromString:'10 kHz'            
     self frequencyFromString:'0.6 k'            
     self frequencyFromString:'1.8 Mhz'            
     self frequencyFromString:'0.5 Ghz'            
     self frequencyFromString:'0.5 Thz'            
     self frequencyFromString:'1000/s'            
     self frequencyFromString:'10/s'            
     self frequencyFromString:'10/min'            
     self frequencyFromString:'10/hr'

o  frequencyStringFor: hertz
return a useful string for a frequency;
Scales by K (*1000), M (*1000*1000) or G (*1000*1000*1000) or even T
as required and useful.
Provided here since this is so common...

Usage example(s): 

     self frequencyStringFor:0.1          
     self frequencyStringFor:10          
     self frequencyStringFor:100            
     self frequencyStringFor:1000            
     self frequencyStringFor:8192            
     self frequencyStringFor:10000          
     self frequencyStringFor:100000          
     self frequencyStringFor:1000000        
     self frequencyStringFor:10000000       
     self frequencyStringFor:100000000      
     self frequencyStringFor:1000000000      
     self frequencyStringFor:10000000000      
     self frequencyStringFor:100000000000      
     self frequencyStringFor:1000000000000      
     self frequencyStringFor:10000000000000

o  inchToMillimeter: inches
convert inches to mm. Made this an extra method, since its so common.

o  millimeterToInch: mm
convert mm to inches. Made this an extra method, since its so common.

o  unitStringFor: nIn scale: k rounded: rounded unitStrings: unitStrings
common helper for SI (1000-based) and binary (1024-based) human readable string generators.
Notice that both forms are often encountered and useful.
If rounded is true, round to nearest integer

Usage example(s): 

     self fileSizeStringFor:nil          
     self fileSizeStringFor:10          
     self fileSizeStringFor:100            
     self fileSizeStringFor:900            
     self fileSizeStringFor:1100            
     self fileSizeStringFor:1400            
     self fileSizeStringFor:1499            
     self fileSizeStringFor:1500            

     self unitStringFor:1000 scale:1000 rounded:true unitStrings:#('' 'kB' 'MB' 'GB' 'TB' 'PB' 'EB' )           
     self unitStringFor:1000 scale:1000 rounded:true unitStrings:#('' 'k' 'M' 'G' 'T' 'P' 'E' )           
     self unitStringFor:8192 scale:1000 rounded:true unitStrings:#('' 'k' 'M' 'G' 'T' 'P' 'E' )           
     self unitStringFor:10000 scale:1000 rounded:true unitStrings:#('' 'k' 'M' 'G' 'T' 'P' 'E' )          
     self unitStringFor:100000 scale:1000 rounded:true unitStrings:#('' 'k' 'M' 'G' 'T' 'P' 'E' )          
     self unitStringFor:1000000 scale:1000 rounded:true unitStrings:#('' 'k' 'M' 'G' 'T' 'P' 'E' )        
     self unitStringFor:10000000 scale:1000 rounded:true unitStrings:#('' 'k' 'M' 'G' 'T' 'P' 'E' )       
     self unitStringFor:100000000 scale:1000 rounded:true unitStrings:#('' 'k' 'M' 'G' 'T' 'P' 'E' )      
     self unitStringFor:1000000000 scale:1000 rounded:true unitStrings:#('' 'k' 'M' 'G' 'T' 'P' 'E' )      
     self unitStringFor:10000000000 scale:1000 rounded:true unitStrings:#('' 'k' 'M' 'G' 'T' 'P' 'E' )      
     self unitStringFor:100000000000 scale:1000 rounded:true unitStrings:#('' 'k' 'M' 'G' 'T' 'P' 'E' )      
     self unitStringFor:1000000000000 scale:1000 rounded:true unitStrings:#('' 'k' 'M' 'G' 'T' 'P' 'E' )      
     self unitStringFor:10000000000000 scale:1000 rounded:true unitStrings:#('' 'k' 'M' 'G' 'T' 'P' 'E' )      
     self unitStringFor:10000000000000000 scale:1000 rounded:true unitStrings:#('' 'k' 'M' 'G' 'T' 'P' 'E' )      
     self unitStringFor:100000000000000000000 scale:1000 rounded:true unitStrings:#('' 'k' 'M' 'G' 'T' 'P' 'E' )      
     self unitStringFor:1000000000000000000000 scale:1000 rounded:true unitStrings:#('' 'k' 'M' 'G' 'T' 'P' 'E' )      

     self unitStringFor:8192 scale:1024 rounded:true unitStrings:#('' 'Ki' 'Mi' 'Gi' 'Ti' 'Pi' 'Ei' )           
     self unitStringFor:81920000 scale:1024 rounded:true unitStrings:#('' 'Ki' 'Mi' 'Gi' 'Ti' 'Pi' 'Ei' )           
     self unitStringFor:819200000000 scale:1024 rounded:true unitStrings:#('' 'Ki' 'Mi' 'Gi' 'Ti' 'Pi' 'Ei' )

initialization
o  initializeConversions
initialize common conversions

Usage example(s): 

     Conversions := nil.
     UnitConverter initializeConversions

o  initializePrintValues
inch to (roughly) a typesetter point

o  initializeScaleFactors
10^24

missing conversion
o  noConversionFrom: sourceUnit to: destUnit

private
o  addConversion: factorOrBlock from: sourceMetric to: destMetric
add a conversion

o  convertDirect: howMany from: sourceMetric to: destMetric
given a value in sourceMetric (symbolic), try to convert it
to destMetric (symbolic);
Only direct conversions are tried; return nil, if the conversion is unknown.

Usage example(s): 

     UnitConverter convertDirect:1 from:#inch to:#meter 
     UnitConverter convertDirect:1 from:#inch to:#millimeter 
     UnitConverter convertDirect:1 from:#degrees to:#fahrenheit

o  unscaled: what
given a unit, return the base and a factor as assoc,
or nil if not found

Usage example(s): 

     UnitConverter unscaled:#millimeter
     UnitConverter unscaled:#nanometer 
     UnitConverter unscaled:#kilometer   
     UnitConverter unscaled:#fuzzymeter

queries
o  isUtilityClass
(comment from inherited method)
a utility class is one which is not to be instantiated,
but only provides a number of utility functions on the class side.
It is usually also abstract

Examples:


ever wanted to know, how many floz's are there in a european Coce bottle ? 
    Transcript showCR:
        (UnitConverter convert:1 from:#liter to:#floz)

    Transcript showCR:
        (UnitConverter convert:43.5 from:#oz to:#gram)
or, how many square-meters an acre is: 
    Transcript showCR:
        (UnitConverter convert:1 from:#acre to:#'meter^2')
or europeans might want to know, what those fahrenheit numbers mean in an US weather report ;-): 
    Transcript showCR:(
        (UnitConverter convert:80 from:#fahrenheit to:#celsius)
            asFixedPoint:1)
how fast do I drive ? :-) 
    Transcript showCR:(
            UnitConverter convert:200 from:#'km/hr' to:#'mile/hr')
how fast does Chris drive ? :-) 
    Transcript showCR:(
            UnitConverter convert:65 from:#'mile/hr' to:#'km/hr')
calories or joule ? 
    Transcript showCR:(
            UnitConverter convert:0.18 from:#'kilocalorie' to:#'kilojoule')

    Transcript showCR:(
            UnitConverter convert:2000 from:#'kilocalorie' to:#'kilojoule')
distances: 
    Transcript showCR:(
        UnitConverter convert:1 from:#'lightsecond' to:#'kilometer')
that's the same: 
    Transcript showCR:(
        UnitConverter convert:1 from:#'lightspeed*s' to:#'kilometer')
a days travel ... 
    Transcript showCR:(
        UnitConverter convert:1 from:#'lightspeed*dy' to:#'kilometer')
a year travel ... 
    Transcript showCR:(
        UnitConverter convert:1 from:#'lightyear' to:#'kilometer')
wonna race on the autobahn ? 
    Transcript showCR:(
        UnitConverter convert:200 from:#'km/h' to:#'mph') 

    Transcript showCR:(
        UnitConverter convert:13 from:#'m/s' to:#'km/h')
real estate buyers might want to know, how many acres a german ar is: 
    Transcript showCR:
        (UnitConverter convert:1 from:#'german-ar' to:#acre)
- or how many square-feet are there in your living room: 
    Transcript showCR:
        (UnitConverter convert:100 from:#'meter^2' to:#'foot^2')
- or how about: 
    Transcript showCR:
        (UnitConverter convert:3600 from:#'ft*ft' to:#'m*,')
how many tea spoons are there in a cubic meter ? (roughly, since a teaspoon is not a standard unit) 
    Transcript showCR:
        (UnitConverter convert:1 from:#'meter^3' to:#teaspoon)
how wide is a US page in inches: 
    Transcript showCR:
        (UnitConverter convert:1 from:#'letterW' to:#inch)
- in millimeter: 
    Transcript showCR:
        (UnitConverter convert:1 from:#'letterW' to:#mm)
the height of a US page in inches: 
    Transcript showCR:
        (UnitConverter convert:1 from:#'letterH' to:#inch)
- in millimeter: 
    Transcript showCR:
        (UnitConverter convert:1 from:#'letterH' to:#mm)
the same for european A4 standard page: 
    Transcript showCR:
        (UnitConverter convert:1 from:#'a4H' to:#mm)   

    Transcript showCR:
        (UnitConverter convert:1 from:#'a4H' to:#inch)
the mass of a proton: 
    Transcript showCR:
        (UnitConverter convert:1 from:#'proton' to:#eV)
the energy of a single proton in the LHC (as of 2010) 
    Transcript showCR:
        (UnitConverter convert:7 from:#'TeV' to:#joule)

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Mon, 18 Nov 2024 04:43:04 GMT