# Documentation

### This is machine translation

Translated by
Mouse over text to see original. Click the button below to return to the English verison of the page.

# num2str

Convert numbers to character array

## Syntax

• ``s = num2str(A)``
example
• ``s = num2str(A,precision)``
example
• ``s = num2str(A,formatSpec)``
example

## Description

example

````s = num2str(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 = num2str(A,precision)` returns a character array that represents the numbers with the maximum number of significant digits specified by `precision`.```

example

````s = num2str(A,formatSpec)` applies a format specified by `formatSpec` to all elements of `A`.```

## Examples

collapse all

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

```s = num2str(pi) ```
```s = 3.1416 ```
```s = num2str(eps) ```
```s = 2.2204e-16 ```

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

```A = gallery('normaldata',[2,2],0); s = num2str(A,3) ```
```s = -0.433 0.125 -1.67 0.288 ```

Specify the width, precision, and other formatting for an array of floating-point values.

```A = gallery('uniformdata',[2,3],0) * 9999; s = num2str(A,'%10.5e\n') ```
```s = 9.50034e+03 6.06782e+03 8.91210e+03 2.31115e+03 4.85934e+03 7.62021e+03 ```

The format `'%10.5e'` prints each value in exponential format with five decimal places, and `'\n'` prints a new line character.

## 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.

`formatSpec` can be a character vector in single quotes, or, starting in R2016b, a string scalar. You can create a string with the `string` function.

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.

Value TypeConversionDetails

Integer, signed

`%d` or `%i`

Base 10

Integer, unsigned

`%u`

Base 10

`%o`

Base 8 (octal)

`%x`

Base 16 (hexadecimal), lowercase letters `a``f`

`%X`

Same as `%x`, uppercase letters `A``F`

Floating-point number

`%f`

Fixed-point notation (Use a precision operator to specify the number of digits after the decimal point.)

`%e`

Exponential notation, such as `3.141593e+00` (Use a precision operator to specify the number of digits after the decimal point.)

`%E`

Same as `%e`, but uppercase, such as `3.141593E+00` (Use a precision operator to specify the number of digits after the decimal point.)

`%g`

The more compact of `%e` or `%f`, with no trailing zeros (Use a precision operator to specify the number of significant digits.)

`%G`

The more compact of `%E` or `%f`, with no trailing zeros (Use a precision operator to specify the number of significant digits.)

Characters or strings

`%c`

Single character

`%s`

Character vector or string array. The type of the output text is the same as the type of `formatSpec`.

Optional Operators

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

• Identifier

Order for processing the function input arguments. Use the syntax `n\$`, where `n` represents the positions of the other input arguments in the function call.

Example: ```('%3\$s %2\$s %1\$s %2\$s','A','B','C')``` prints input arguments `'A'`, `'B'`, `'C'` as follows: `C B A B`.

Note: If an input argument is an array, you cannot use identifiers to specify particular array elements from that input argument.

• Flags

 `'–'` Left-justify.Example: `%-5.2f`Example: `%-10s` `'+'` Always print a sign character (+ or –) for any numeric value.Example: `%+5.2f`Right-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. The field width operator can be a number, or an asterisk (`*`) to refer to an input argument.

Example: The input arguments `('%12d',intmax)` are equivalent to `('%*d', 12, intmax)`.

The function pads to field width with spaces before the value unless otherwise specified by flags.

• Precision

 For `%f`, `%e`, or `%E` Number of digits to the right of the decimal pointExample: `'%.4f'` prints `pi` as `'3.1416'` For `%g` or `%G` Number of significant digitsExample: `'%.4g'` prints `pi` as `' 3.142'`

The precision operator can be a number, or an asterisk (`*`) to refer to an argument.

Example: The input arguments ```('%6.4f', pi)``` are equivalent to `('%*.*f', 6, 4, pi)`.

 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` as `400921fb54442d18`

`%tx` or `%tX`
`%to`
`%tu`

Single-precision hexadecimal, octal, or decimal value
Example: `%tx` prints `pi` as `40490fdb`

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 ASCII code is the hexadecimal number, `N`

`\xN`

Character whose ASCII code is the octal number, `N`

`\N`

Notable Behavior of Conversions with Formatting Operators

• Numeric conversions print only the real component of complex numbers.

• 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` to `3.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]``` to `ABC`.

Data Types: `char` | `string`

## Output Arguments

collapse all

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

collapse all

### Tips

`num2str` does not accept positional identifiers in the `formatSpec` 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.

### 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'`.