si

Written by Balazs Halasy, 02/05/2004 Updated 05/04/2005 by Balazs Halasy

Summary

Handles unit display of values (output formatting).

Usage

input|si( unit [, prefix ] [, decimals ] [, symbol ] [, separator ] )

Parameters

Name	Type	Description	Required
unit	string	The unit that the input value should be converted to.	Yes.
prefix	string	The prefix used to represent the input value.	No.
decimals	integer	The number of decimal digits that should be shown.	No.
symbol	string	The symbol that should be used as the decimal separator.	No.
separator	string	The symbol that should be used as the thousand separator.	No.

Returns

The input value formatted according to the given parameters.

Description

This operator handles formatting of different kind of values (file sizes, lengths, weights, etc.). The value that should be formatted must be provided as the input parameter. The first parameter must reveal the type of the input value. The following list shows the types that can be used.

meter
gram
second
ampere
kelvin
mole
candela
byte
bit

The second parameter is optional and can be used to specify a desired prefix. The rest of the parameters determine how the value should be formatted when it comes to decimals, separators, etc. If these parameters are omitted, the operator will use the settings of the current locale.

Custom units

Custom units can be configured by extending the entries of the "Base" group in a configuration override for "units.ini".

Prefix tables

The prefix is either the name of the size like kilo or one of these

Prefix	Description
binary	Calculate using 2 as base, e.g. 2^8
decimal	Calculate using 10 as base, e.g. 10^6
none	Show value as it is with just the unit appended
auto	Determine base from the type of unit (controlled by the "BinaryUnits" setting, default is "bit" and "byte").

The following table shows the proper binary prefixes.

Prefix	Power of 2	Symbol
kibi	2^10	Ki
mebi	2^20	Mi
gibi	2^30	Gi
tebi	2^40	Ti
pebi	2^50	Pi
exbi	2^60	Ei

The following table shows the commonly used binary prefixes (please note that they may be inaccurate).

Prefix	Power of 2	Symbol
kilo	2^10	k
mega	2^20	M
giga	2^30	G
tera	2^40	T
peta	2^50	P
exa	2^60	E

The following table shows the decimal prefixes.

Prefix	Power of 10	Symbol
yotta	10^24	Y
zetta	10^21	Z
exa	10^18	E
peta	10^15	P
tera	10^12	T
giga	10^9	G
mega	10^6	M
kilo	10^3	k
hecto	10^2	h
deca	10^1	da
deci	10^-1	d
centi	10^-2	c
milli	10^-3	m
micro	10^-6	µ
nano	10^-9	n
pico	10^-12	p
femto	10^-15	f
atto	10^-18	a
zepto	10^-21	z
yocto	10^-24	y

All of these values are defined in the "units.ini" configuration file.

Examples

Example 1

{1025|si( byte )}
{1025|si( byte, binary )}
{1025|si( byte, decimal )}
{1025|si( byte, none )}
{1025|si( byte, auto )}
{1025|si( byte, kibi )}
{1025|si( byte, kilo )}

If the "UseSIUnits" directive in a configuration override for "site.ini" is set to "false" (the default value), the following output will be produced:

1.00 kB
1.00 kB
1.02 kB
1025 B
1.00 kB
1.00 KiB
1.02 kB

If the "UseSIUnits" directive in a configuration override for "site.ini" is set to "true", the following output will be produced:

si