num2str - Convert numbers to character array - MATLAB (original) (raw)

Convert numbers to character array

Syntax

Description

Note

string is recommended overnum2str for combining numeric scalars with text. Use the + operator to combine strings and numeric values for improved readability. For additional information, see Alternative Functionality.

[s](#btfaj9t-1-s) = num2str([A](#btfaj9t-1-A)) converts a numeric array into a character array that represents the numbers. The output format depends on the magnitudes of the original values.num2str is useful for labeling and titling plots with numeric values.

example

[s](#btfaj9t-1-s) = num2str([A](#btfaj9t-1-A),[precision](#btfaj9t-1-precision)) returns a character array that represents the numbers with the maximum number of significant digits specified by precision.

example

[s](#btfaj9t-1-s) = num2str([A](#btfaj9t-1-A),[formatSpec](#bu6eywi-formatSpec)) applies a format specified by formatSpec to all elements ofA.

Note

If a format is specified, s will not include spaces between elements of A. To include spaces, add one to the format.

example

Examples

collapse all

Convert the floating-point values returned by pi and eps to character vectors.

Specify the maximum number of significant digits for floating-point values.

rng('default') A = randn([2,2]); s = num2str(A,3)

s = 2×15 char array '0.538 -2.26' ' 1.83 0.862'

Display pi as a floating-point number to a specified precision.

formatSpec = '%.2f'; s = num2str(pi,formatSpec)

Input Arguments

collapse all

Input array, specified as a numeric array.

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical
Complex Number Support: Yes

Maximum number of significant digits in the output string, specified as a positive integer.

Note

If you specify precision to exceed the precision of the input floating-point data type, the results might not match the input values to the precision you specified. The result depends on your computer hardware and operating system.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Format of the output fields, specified using formatting operators. formatSpec also can include ordinary text and special characters.

If formatSpec includes literal text representing escape characters, such as \n, then num2str translates the escape characters.

formatSpec can be a character vector in single quotes, or a string scalar.

Formatting Operator

A formatting operator starts with a percent sign, %, and ends with a conversion character. The conversion character is required. Optionally, you can specify identifier, flags, field width, precision, and subtype operators between % and the conversion character. (Spaces are invalid between operators and are shown here only for readability).

Conversion Character

This table shows conversion characters to format numeric and character data as text.

Optional Operators

The optional identifier, flags, field width, precision, and subtype operators further define the format of the output text.

• Identifier
  Note: Unlike the sprintf function, num2str does not support identifiers.
• Flags

  '–'	Left-justify. Example: %-5.2f Example: %-10s
  '+'	Always print a sign character (+ or –) for any numeric value. Example: %+5.2fRight-justify text. Example: %+10s
  ' '	Insert a space before the value. Example: % 5.2f
  '0'	Pad to field width with zeros before the value. Example: %05.2f
  '#'	Modify selected numeric conversions:For %o, %x, or%X, print 0,0x, or 0X prefix.For %f, %e, or%E, print decimal point even when precision is 0.For %g or %G, do not remove trailing zeros or decimal point.Example: %#5.0f

• Field Width
  Minimum number of characters to print.
  Example: '%5d' prints intmax as 2147483647 because the value returned by intmax exceeds the minimum number of characters to print.
  If the number of characters to print is less than the field width, then thecompose function pads to the field width with spaces before the value unless otherwise specified by flags.
  However, the num2str function does not pad to the field width with spaces.
• Precision
  Number of digits to print.

  For %f, %e, or%E	Number of digits to the right of the decimal point Example: '%.4f' prints pi as'3.1416'
  For %g or%G	Number of significant digits Example: '%.4g' prints pi as'3.142'
  Example: '%6.4f' prints pi as'3.1416'.
  Note
  If you specify a precision operator for floating-point values that exceeds the precision of the input numeric data type, the results might not match the input values to the precision you specified. The result depends on your computer hardware and operating system.

• Subtypes
  You can use a subtype operator to print a floating-point value as its octal, decimal, or hexadecimal value. The subtype operator immediately precedes the conversion character. This table shows the conversions that can use subtypes.

  Input Value Type	Subtype and Conversion Character	Output Value Type
  Floating-point number	%bx or%bX %bo %bu	Double-precision hexadecimal, octal, or decimal value Example: %bx prints pi as400921fb54442d18
  %tx or%tX %to %tu	Single-precision hexadecimal, octal, or decimal value Example: %tx prints pi as40490fdb

Text Before or After Formatting Operators

formatSpec can also include additional text before a percent sign,%, or after a conversion character. The text can be:

• Ordinary text to print.
• Special characters that you cannot enter as ordinary text. This table shows how to represent special characters in formatSpec.

  Special Character	Representation
  Single quotation mark	''
  Percent character	%%
  Backslash	\\
  Alarm	\a
  Backspace	\b
  Form feed	\f
  New line	\n
  Carriage return	\r
  Horizontal tab	\t
  Vertical tab	\v
  Character whose Unicode® numeric value can be represented by the hexadecimal number, N	\xNExample: num2str('\x5A') returns 'Z'
  Character whose Unicode numeric value can be represented by the octal number, N	\NExample: num2str('\132') returns 'Z'

Notable Behavior of Conversions with Formatting Operators

• If you specify a conversion that does not fit the data, such as a text conversion for a numeric value, MATLAB® overrides the specified conversion, and uses%e.
  Example: '%s' converts pi to3.141593e+00.
• If you apply a text conversion (either %c or%s) to integer values, MATLAB converts values that correspond to valid character codes to characters.
  Example: '%s' converts [65 66 67] toABC.

Output Arguments

collapse all

Text representation of the input array, returned as a character array.

Tips

• num2str does not accept positional identifiers in theformatSpec input argument. For example,num2str([14 15],'%2$X %1$o) returns an error.
  Positional identifiers specify the order in which the formatting operator processes input arguments of the function, not the elements of an input array. When you call num2str, there is only one input argument that has numbers to convert.
• If you specify an invalid formatting operator or special character, then num2str prints all text up to the invalid operator or character and discards the rest.
  Example: If formatSpec is 'value = %z', then num2str prints 'value =' because %z is not a formatting operator.
  Example: If formatSpec is'character \x99999 = %s', then num2str prints 'character' because \x99999 is not a valid special character.
• It is recommended to use mat2str when converting numeric values to text as part of the input to eval.

Algorithms

num2str trims any leading spaces from a character array, even when formatSpec includes a space character flag. For example,num2str(42.67,'% 10.2f') returns a 1-by-5 character array'42.67'.

Alternative Functionality

Update code that makes use of num2str to combine numeric scalars with text to use string instead. Numeric values can be combined with strings using the + operator. For example:

Extended Capabilities

expand all

Usage notes and limitations:

• The input precision must be compile time constant.
• For the syntaxnum2str(`A`,`formatSpec`),A and formatSpec must be compile time constants.

The num2str function fully supports GPU arrays. To run the function on a GPU, specify the input data as a gpuArray (Parallel Computing Toolbox). For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Version History

Introduced before R2006a

expand all

You can generate C/C++ code for this function.