The si unit operator #

si writes a number with a unit and a prefix: 5242880 bytes as 5.00 MB, 1500 meters as 1.50 km. It is registered by eZTemplateUnitOperator (lib/eztemplate/classes/eztemplateunitoperator.php) through lib/eztemplate/classes/eztemplateautoload.php. Units and prefixes come from settings/units.ini; the choice between binary and decimal prefixes from [UnitSettings] in site.ini.

Contents #

1. Parameters
2. Units and prefixes
3. Examples
4. Related pages

Parameters #

si #

Input: the number, piped. Returns a string: the number, a space, the prefix symbol and the unit symbol. An unknown unit logs "No such unit" and leaves the number unchanged; an unknown prefix logs "Prefix ... not found". Generated reference: si.

Units and prefixes #

[Base] in units.ini maps unit names to symbols: meter m, gram g, second s, ampere A, kelvin K, mole mol, candela cd, byte B and bit b.

The prefix auto picks binary for the units in [UnitSettings] BinaryUnits (byte;bit on a development installation) and decimal for all others. Then:

• decimal uses [DecimalPrefixes] (powers of 10, from yocto to yotta, including hecto and deca) and takes the largest prefix not bigger than the number. That is why 150|si( 'meter' ) is 1.50 hm: name a prefix when you want a familiar one.
• binary uses powers of 2. With [UnitSettings] UseSIUnits=false, as on a development installation, it uses [FakeBinaryPrefixes], which divide by 1024 but print the familiar k, M, G; with true it uses [BinaryPrefixes] and prints Ki, Mi, Gi.
• Numbers whose absolute value is below 10 get no prefix and are printed as they are.
• A named prefix (kilo, mebi...) is looked up in [BinaryPrefixes] first, then [DecimalPrefixes]; none prints the whole number with separators.

Negative numbers get the prefix of their magnitude (-2000 seconds is -2.00 ks).

Examples #

File sizes:

5|si( 'byte' ) = {5|si( 'byte' )}
2048|si( 'byte' ) = {2048|si( 'byte' )}
5242880|si( 'byte' ) = {5242880|si( 'byte' )}
5242880|si( 'byte', 'kibi' ) = {5242880|si( 'byte', 'kibi' )}
5242880|si( 'byte', 'mega' ) = {5242880|si( 'byte', 'mega' )}
5242880|si( 'byte', 'none' ) = {5242880|si( 'byte', 'none' )}
5242880|si( 'byte', 'auto', 1 ) = {5242880|si( 'byte', 'auto', 1 )}

Output:

5|si( 'byte' ) = 5 B
2048|si( 'byte' ) = 2.00 kB
5242880|si( 'byte' ) = 5.00 MB
5242880|si( 'byte', 'kibi' ) = 5,120.00 KiB
5242880|si( 'byte', 'mega' ) = 5.24 MB
5242880|si( 'byte', 'none' ) = 5,242,880 B
5242880|si( 'byte', 'auto', 1 ) = 5.0 MB

Decimal units, a fixed prefix and a decimal symbol of your own:

1500|si( 'meter' ) = {1500|si( 'meter' )}
150|si( 'meter' ) = {150|si( 'meter' )}
150|si( 'meter', 'kilo', 3 ) = {150|si( 'meter', 'kilo', 3 )}
2500|si( 'gram', 'kilo', 1, ',' ) = {2500|si( 'gram', 'kilo', 1, ',' )}
-2000|si( 'second' ) = {-2000|si( 'second' )}

Output:

1500|si( 'meter' ) = 1.50 km
150|si( 'meter' ) = 1.50 hm
150|si( 'meter', 'kilo', 3 ) = 0.150 km
2500|si( 'gram', 'kilo', 1, ',' ) = 2,5 kg
-2000|si( 'second' ) = -2.00 ks

An unknown unit:

[{100|si( 'furlong' )}]

Output:

[100]

Logged by the template engine:

WARNING eZTemplateUnitOperator: No such unit 'furlong'

The examples gave the same output interpreted and compiled on a development installation.

Related pages #

• Locale operators: l10n( 'number' ) without a unit
• PHP string functions: encode and format: number_format
• All template operators (generated)
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.