File Exchange

image thumbnail

num2eng

version 5.5 (497 KB) by Harry Dymond
Convert numbers to engineering notation strings, or use SI-prefixes instead. Offers extensive customisation. Also works on axes tick labels.

12 Downloads

Updated 30 Jul 2020

View License

Converts an input numerical value into an engineering-formatted string (as a character vector), in either scientific format with multiples-of-three exponent, or using SI prefixes e.g. k, M, n, p etc. It can also process the tick labels of graphs and colorbars. Please see the Examples tab for an extensive list of num2eng examples.

What makes this submission unique amongst the several num2eng and num2si functions on the file exchange is that it:
• Supports scalar, vector, and matrix inputs
• Can processes axes and colorbar tick labels, including keeping the tick labels up-to-date if the ticks change (e.g. due to limit change, figure resize, etc.)
• Supports complex number inputs
• Properly handles edge-cases such as rounding, empty inputs, Inf, NaN, non-numerical inputs etc.
• Uses either SI prefixes or engineering-formatted scientific notation
• Optionally uses the Greek lower-case mu (Unicode U+03BC) as the SI prefix for numbers with magnitude in the range [1e-6, 1e-3)
• Optionally uses the true minus character (Unicode U+2212) instead of hyphen-minus (U+002D) for negative numbers
• Optionally uses the infinity symbol (Unicode U+221E) for infinite inputs
• Optionally pads output strings using left or right justification
• Optionally inserts trailing zeros to pad output string to the specified number of significant figures
• Optionally outputs as a unified character vector for vector and 2D array inputs, rather than the default cell array of character vectors
• Optionally prevents use of exponent or SI prefix for numbers with magnitude in the range [0.1, 1) (i.e., tenths)
• When not using SI prefixes:
-- Optionally pads the exponent with zeros to a specified width
-- Optionally only shows a sign character in the exponent for negative exponents
-- Optionally forces the exponent to always be included, even if it is zero
-- Offers the choice of lower-case e, capital E, or small capital E (Unicode U+1D07) for the exponent
• Optionally forces the mantissa to lie in the range [0.001, 1), rather than the more usual [1, 1000). One reason to use this option is to unambiguously convey accuracy via the number of significant figures in the output.
• Allows the user to specify the units, to be appended to the end of the string (with additional control over whether this word is automatically pluralised or not)

The function has two alternative call syntaxes:

1. string = num2eng(number,[useSI],[useMu],[spaceAfterNum],[sigFigs],[fullName],[useMinus],[useInf],[trailZeros],[pad],[cellOutput]), where input variables in square brackets are optional - i.e. The function accepts anywhere from 1 to 11 inputs, inclusive.

2. string = num2eng(number,optionsStruct), where the control options are passed in a structure. This syntax offers more options than syntax one.

Using an options structure instead of individual option inputs:
When num2eng was originally developed, the individual option-input approach was selected in order to make function hints as helpful as possible. However, as the number of options has grown, the function call has become unwieldy, especially if you only want to set one of the later options and leave the others at the default value. It’s also difficult to see at a glance what options are being used in a call to num2eng, when reading code that you’ve written earlier. This is where using syntax 2 comes in. You can pass num2eng an options structure as the second input. This structure can have anywhere from one to 20 fields, named as per the options listed above, with the additional options: noExp4Tenths, expWidth, expSign, expForce, unit, noPlural, capE, smallCapE, fracMant, and axes.

Cite As

Harry Dymond (2020). num2eng (https://www.mathworks.com/matlabcentral/fileexchange/67740), MATLAB Central File Exchange.

Comments and Ratings (7)

Daniel Hinrichsen

Josh Philipson

Angelos Kalitzeos

Chang hsiung

Great, now it works. Thanks a lot.

Harry Dymond

Hello again @Chang hsiung. I believe the problem was with use of the iptnum2ordinal function. Somehow, my copy of MATLAB managed to execute the iptnum2ordinal function without checking out a license to the image processing toolbox! Anyway, I have now replaced calls to that function so you should be able to use num2eng now.

Harry Dymond

@Chang hsiung, thank you for your interest in my function. What version of MATLAB are you using? The function was developed in MATLAB version 2016a, and according to my testing, should not require the Image Processing Toolbox. If you are using at least version 2016a of MATLAB, please could you let me know the exact num2eng call you are making?

Chang hsiung

Do you have a version that does not require Image Processing toolbox ???

Updates

5.5

-- Fixed bug with handling non-double numeric inputs (e.g. integer data types): these are now converted to double before processing

5.4

Options trailZeros and expForce are now respected when input number is zero

5.3.1

Improved documentation

5.3

Added workaround for MATLAB memory-leak bug related to listener lifecycle

5.2

Can now handle arrays of figure handles

5.1

Added support for colorbars

5.0.1

Documentation fix

5.0

Can now process axes tick labels directly. Creates listeners to keep tick labels up-to-date if the ticks are changed.

3.3

- Added options capE, smallCapE, and fracMant
- Other minor code clean-ups as noted in the m file

3.0

- Added options noExp4Tenths, expWidth, expSign, expForce, unit, and noPlural. (only available with optionStruct call syntax).
- Other minor changes as detailed in the.m file

2.2

- Infinite inputs now return strings with Inf correctly capitalised.
- Added the "useInf" option. NOTE: This is now option 7, meaning trailZeros, pad, and cellOutput have "moved". Code using these options with syntax 1 will have to be updated.

2.1

- Now uses repmat to generate space padding (no change in functionality; code just easier to read)
- Updated compatibility

2.0.2

Documentation update

2.0.1

Documentation fix

2.0

- New trailZeros, pad, and cellOutput options.
- Optional alternative call syntax where options are passed in a structure instead of list.
- Function remains backwards compatible with existing code.
- See m file for full list of changes.

1.1.4

- Reverted to using U+03BC (greek letter mu) for micro character.
- Added commas to code as suggested by the code parser in MATLAB 2018. This will result in versions prior to this suggesting that the commas can/should be removed.

1.1.3

If input number is minus infinity, the useMinus option is now respected

1.1.2

Minor code cleanup (no changes in functionality)

1.1.1

Changed icon

1.1

Added the option to use the true minus character (U+2212) in returned strings. The new option is added in such a way that the function will remain backwards compatible - code using earlier versions of num2eng does not need to be changed.

1.0.6

function input no longer uses varargin, to make function hints more useful. Inputs 2 to 6 remain optional.

1.0.4.0

Function should no longer require the Image Processing Toolbox

1.0.3.0

Option "fullName" now overrides option "useMu"
If input is a column vector, output will now be a column vector of cells instead of a row vector of cells

1.0.2.0

Updated description

1.0.1.0

Updated description

1.0.1.0

Updated description

1.0.1.0

Updated description

1.0.1.0

updated FEX icon

1.0.1.0

changed FEX icon

1.0.1.0

changed FEX icon

1.0.1.0

fixed a typo

1.0.1.0

fixed a typo

MATLAB Release Compatibility
Created with R2018a
Compatible with R2014b to any release
Platform Compatibility
Windows macOS Linux

num2eng documentation