Main Content

dist2str

Convert numeric distances to character array

collapse all in page

    Syntax

    str = dist2str(dist)
    str = dist2str(dist,format)
    str = dist2str(dist,format,unit)
    str = dist2str(dist,format,n)
    str = dist2str(dist,format,unit,n)

    Description

    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.

    example

    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.

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

    example

    Examples

    collapse all

    Open Live Script

    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'
    Open Live Script

    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'
    Open Live Script

    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 °

    "radians" or "rad"

    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

    See Also

    Functions