num2eng

Convert numbers to engineering notation strings, or use SI-prefixes instead. Offers extensive customisation. Also works on axes tick labels.
795 Downloads
Updated 3 Mar 2024

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 here 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 process 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.
• Optionally uses a comma, instead of a point, as the decimal separator
• 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 21 fields, named as per the options listed above, with the additional options: noExp4Tenths, expWidth, expSign, expForce, unit, noPlural, capE, smallCapE, fracMant, useComma, axes.

Cite As

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

MATLAB Release Compatibility
Created with R2018a
Compatible with R2014b and later releases
Platform Compatibility
Windows macOS Linux
Categories
Find more on Characters and Strings in Help Center and MATLAB Answers

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!
Version Published Release Notes
7.0

Added support for SI prefixes Q (quetta, 10^30), R (ronna, 10^27), r (ronto, 10^-27), and q (quecto, 10^-30)

6.1.1

Fixed bug where input number of 0 could sometimes give an output of '-0'

6.1

Improved error handling/reporting

6.0

Added the useComma option

5.8.2

-- Fixed bug in get_datacursor_manager subroutine
-- Fixed bug that occurs if num2eng is called on a set of axes that are part of a GUI rather than a "normal" MATLAB figure window
-- Improved error reporting

5.8.1

Fixed bugs in save routine for figures that have been processed by num2eng

5.8

-- Datatips now formatted to use same font as that specified for the parent axes of the line on which the datatip appears
-- Mechanism added to recreate listeners when a figure, which has been processed by num2eng and saved as a .fig, is reopened

5.7.4

Documentation update

5.7.3

Documentation update

5.7.2

Documentation fixes

5.7.1

Minor performance tweaks

5.7

- Datatips formatted with units, if supplied
- Existing datatips are updated when axes are processed
- Improved handling of multi-letter unit abbreviations (e.g. "Hz") - it's no longer necessary to set option "noPlural" when using such units

5.6

Added custom data-tip formatting for axes that are processed by num2eng

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

fixed a typo
Updated description
changed FEX icon
updated FEX icon
Updated description
fixed a typo
changed FEX icon
Updated description

1.0.0.0