NUM2SIP and NUM2BIP Examples

The function NUM2SIP converts a numeric scalar to text with a number value and an SI prefix (aka "metric prefix"), for example 1000 => '1 k'. Optional arguments control the number precision, select the prefix symbol or prefix name, and if trailing zeros are kept or not.

The development of NUM2SIP was motivated by the need for a well-written function to provide this conversion: many of the functions available on FEX do not conform to the SI standard, use buggy conversion algorithms, or are painfully inefficient. NUM2SIP has been tested against a large set of test cases, including many edge-cases and for all of the optional arguments. Feedback and bug reports are welcome!

Magnitude	10^-30	10^-27	10^-24	10^-21	10^-18	10^-15	10^-12	10^-9	10^-6	10^-3	10^0	10^+3	10^+6	10^+9	10^+12	10^+15	10^+18	10^+21	10^+24	10^+27	10^+30
Name	quecto	ronto	yocto	zepto	atto	femto	pico	nano	micro	milli		kilo	mega	giga	tera	peta	exa	zetta	yotta	ronna	quetta
Symbol	q	r	y	z	a	f	p	n	µ	m		k	M	G	T	P	E	Z	Y	R	Q

Contents

Basic Usage

In many cases NUM2SIP can be called with just a numeric value:

num2sip(1000)
num2sip(1.2e+3)
num2sip(456e+7)

ans =
    '1 k'
ans =
    '1.2 k'
ans =
    '4.56 G'

2nd Input: Significant Figures

By default NUM2SIP rounds to five significant figures. The optional second input argument specifies the number of significant figures. Note that NUM2SIP correctly rounds upwards to the next prefix:

num2sip(987654321,4)
num2sip(987654321,3)
num2sip(987654321,2)
num2sip(987654321,1)

ans =
    '987.7 M'
ans =
    '988 M'
ans =
    '990 M'
ans =
    '1 G'

3rd Input: Symbol or Full Prefix

By default NUM2SIP uses the prefix symbol. The optional third input argument selects between the prefix symbol and the full prefix name.

num2sip(1e6,[],false) % default
num2sip(1e6,[],true)

ans =
    '1 M'
ans =
    '1 mega'

3rd Input: Fixed Prefix

By default NUM2SIP selects the most appropriate prefix. The optional third input argument lets the user specify the prefix. For convenience the "micro" symbol may be provided as 'u' or (U+00B5) or (U+03BC).

num2sip(1e-2,[],'u')
num2sip(1e-4,[],'u')
num2sip(1e-6,[],'u')
num2sip(1e-8,[],'u')

ans =
    '10000 µ'
ans =
    '100 µ'
ans =
    '1 µ'
ans =
    '0.01 µ'

4th Input: Trailing Zeros

By default NUM2SIP removes trailing zeros. The optional fourth input argument selects between removing and keeping any trailing zeros:

num2sip(1e3,3,[],false) % default
num2sip(1e3,3,[],true)

ans =
    '1 k'
ans =
    '1.00 k'

4th and 2nd Inputs: Decimal Places

By default the second input control the significant figures used in the output (following the design of MATLAB's inbuilt NUM2STR and MAT2STR). Set the fourth input to 'DP' and the second input instead controls the number of decimal places (including trailing zeros):

num2sip(123456789,4,[],'dp')

ans =
    '123.4568 M'

2nd Output: Values Without a Prefix

If the magnitude of the input value is outside the prefix range, then no prefix is used and the value is returned in exponential notation. The second output is a logical scalar which indicates if a prefix was used:

[str,isp] = num2sip(6e54)
[str,isp] = num2sip(3210)

str =
    '6e+54 '
isp =
  logical
   0
str =
    '3.21 k'
isp =
  logical
   1

3rd and 4th Outputs: Coefficient and Prefix

The third and fourth outputs return the numeric coefficient and the corresponding prefix. If no prefix was used (i.e. 2nd output isp is FALSE ), then the prefix is an empty char.

[str,~,cof,pfx] = num2sip(123456789)

str =
    '123.46 M'
cof =
       123.46
pfx =
    'M'

Values Without a Prefix

If the magnitude of the input value is outside the prefix range, then no prefix is used and the value is returned in exponential notation:

num2sip(9e-87)
num2sip(6e+54)

ans =
    '9e-87 '
ans =
    '6e+54 '

Correct Rounding Up

Unlike many functions available online, NUM2SIP correctly selects the next prefix when the value rounds up to the next power of one thousand:

num2sip(0.99e6,   3,[],true)
num2sip(0.999e6,  3,[],true)
num2sip(0.9999e6, 3,[],true)

ans =
    '990 k'
ans =
    '999 k'
ans =
    '1.00 M'

Micro Symbol

By default NUM2SIP uses the "micro" symbol from ISO 8859-1, i.e. Unicode (U+00B5) 'MICRO SIGN'. Simply edit the Mfile to select an alternative "micro" symbol, e.g. ASCII 'u' or (U+03BC) 'GREEK SMALL LETTER MU'.

num2sip(5e-6) % default = (U+00B5) 'MICRO SIGN'

ans =
    '5 µ'

Space Character

The standard for the International System of Quantities (ISQ) ISO/IEC 80000 (previously ISO 31) specifies that "a single space is always left between the number and the unit". Note that this applies even when there is no SI prefix to the unit. NUM2SIP correctly includes the space character in all cases (by default using (U+00A0) 'NO-BREAK SPACE'):

sprintf('%sV',num2sip(1e-3))
sprintf('%sV',num2sip(1e+0))
sprintf('%sV',num2sip(1e+3))
sprintf('%sV',num2sip(1e99))

ans =
    '1 mV'
ans =
    '1 V'
ans =
    '1 kV'
ans =
    '1e+99 V'

Bonus: NUM2BIP Binary Prefix Function

The bonus function NUM2BIP converts a numeric scalar into text using the ISO 80000 defined binary prefixes instead of SI metric prefixes. Binary prefixes are used for computer memory.

Magnitude	2^+10	2^+20	2^+30	2^+40	2^+50	2^+60	2^+70	2^+80
Name	kibi	mebi	gibi	tebi	pebi	exbi	zebi	yobi
Symbol	Ki	Mi	Gi	Ti	Pi	Ei	Zi	Yi

The function NUM2BIP has exactly the same arguments as NUM2SIP:

num2bip(1280,4,true,true)

ans =
    '1.250 kibi'

Bonus: NUM2RKM RKM-Code Function

The anonymous function NUM2RKM generates basic IEC 60062 RKM code from numeric input. As shown NUM2RKM is for resistors, it may be modified for capacitors.

unit = 'R'; % unit character.
num2rkm = @(varargin) regexprep(num2sip(varargin{:}),{'(\d+)\.?(\d*)\s(\w)','\.|\s','\s','k','m'},{'$1$3$2',unit,'','K','L'},'once');
num2rkm(23)
num2rkm(4700)
num2rkm(15e6,3,0,1)

ans =
    '23R'
ans =
    '4K7'
ans =
    '15M0'

Reverse Conversion: Text to Numeric

The functions SIP2NUM and BIP2NUM convert from text into numeric:

bip2num('1.25 Ki')
sip2num('1.25 k')

ans =
        1280
ans =
        1250

Published with MATLAB® R2021a