# dist2str

Convert numeric distances to character array

## Description

example

str = dist2str(dist) converts numeric distances in kilometers to a character array that represents the distances. This function is useful for displaying distances as text on maps.

example

str = dist2str(dist,format) specifies whether to add a plus sign (+) as a prefix to positive distances. To add a plus sign (+) as a prefix, specify format as "pm". The default for format is "none", which does not add a plus sign (+).

example

str = dist2str(dist,format,unit) includes the unit text of the specified unit in the character array.

str = dist2str(dist,format,n) specifies the number of decimal places to use in the character array. This syntax assumes the distances are in kilometers.

example

str = dist2str(dist,format,unit,n) specifies the unit and the number of decimal places to use in the character array.

## Examples

collapse all

Convert numeric distances to a character array. By default, the dist2str function assumes the distances are in kilometers.

dist = [-9.7 12.95 24];
str = dist2str(dist)
str = 3x8 char array
'-9.70 km'
'12.95 km'
'24.00 km'

Convert the same distances to a character array and prefix a + sign to the positive distances.

strPlus = dist2str(dist,"pm")
strPlus = 3x9 char array
' -9.70 km'
'+12.95 km'
'+24.00 km'

Convert distances in nautical miles to a character array.

dist = [18.5 -9.48 16];
str = dist2str(dist,"none","nm")
str = 3x8 char array
'18.50 nm'
'-9.48 nm'
'16.00 nm'

Convert distances in meters to a character array. Round the distances to the nearest tenth.

dist = [8.523 -348.79 -418];
str = dist2str(dist,"none","m",-1)
str = 3x8 char array
'   8.5 m'
'-348.8 m'
'-418.0 m'

## Input Arguments

collapse all

Distances, specified as a numeric array.

Plus sign for positive distances, specified as one of these options:

• "pm" — Add a plus sign (+) as a prefix to positive distances.

• "none" — Do not add a plus sign (+) as a prefix to positive distances.

Data Types: char | string

Unit text to include in the character array, specified as one of these options.

OptionUnit Text

"kilometers" or "km"

km

"feet" or "ft"

ft

"meters" or "m"

m

"nauticalmiles" or "nm"

nm

"statutemiles", "miles", or "mi"

mi

Note that other Mapping Toolbox™ functions use mi to indicate international miles rather than statute miles.

"degrees" or "deg"

^{\circ}, which is the LaTeX representation of °

R

Data Types: char | string

Number of digits to include in the character array, specified as an integer. When you specify n, the dist2str function rounds dist to the nearest multiple of 10n.

The sign convention for this argument is opposite to the one used by the round function.

Example: dist2str(3132.467,"none",-2) returns '3132.47 km', which is 3132.467 rounded to the nearest hundredth.

Example: dist2str(3132.467,"none",0) returns '3132 km', which is 3132.467 rounded to the nearest integer.

## Output Arguments

collapse all

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

Data Types: char

## Version History

Introduced before R2006a