string

String array

Description

Starting in R2016b, you can represent text using string arrays instead of character arrays. Each element of a string array stores a sequence of characters. The sequences can have different lengths without padding, such as "yes" and "no". A string array that has only one element is also called a string scalar.

You can index into, reshape, and concatenate string arrays using standard array operations, and you can append text to strings using the + operator. If a string array represents numbers, then you can convert it to a numeric array using the double function.

Creation

You can create a string by enclosing a piece of text in double quotes. Double quotes were introduced in R2017a.

str = "Hello, world"

str = 
"Hello, world"

One way to create a string array is to concatenate strings into an array using square brackets, just as you can concatenate numbers into a numeric array.

str = ["Mercury","Gemini","Apollo";
       "Skylab","Skylab B","ISS"]

str = 2x3 string
    "Mercury"    "Gemini"      "Apollo"
    "Skylab"     "Skylab B"    "ISS"   

You also can convert variables of different data types into string arrays using the string function, described below.

Syntax

str = string(A)

str = string(D)

str = string(D,fmt)

str = string(D,fmt,locale)

Description

str = string(A) converts the input array to a string array.

str = string(D) converts a datetime, duration, or calendar duration array into a string array in the format specified by the Format property of D. The output contains one date or duration in each row.

str = string(D,fmt) represents dates or durations in the specified format, such as 'HH:mm:ss'.

str = string(D,fmt,locale) represents dates or durations in the specified locale, such as 'en_US'. The locale affects the language used to represent strings such as month and day names.

Input Arguments

A — Input array

array

Input array. The data type of A determines how string converts A to a string array.

• If A is a character vector, then string converts A to a string scalar. The output str and input A have the same characters in the same order.

• If A is a cell array or a categorical array, then string converts each element in A to a string element in str.

• If A is a numeric array, then string converts each number to a string element in str.

  Unlike the char function, string does not treat numbers as ASCII or Unicode^® code points.

• If A is a logical array, then string converts each value to either "false" or "true".

• If A is [], then string returns a 0-by-0 string array.

D — Input date and time

datetime or duration array

Input date and time, specified as a datetime or duration array.

Data Types: datetime | duration | calendarDuration

fmt — Date and time format

[] (default) | character vector | string scalar

Date and time format, specified as [], a character vector, or a string scalar. If you specify [], then string represents input D in the format specified by the Format property of D.

The supported formats depend on the data type of D.

• datetime formats can include combinations of units and delimiters, such as 'yyyy-MMM-dd HH:mm:ss.SSS'. For details, see the Format property for datetime arrays.

• duration formats are either single characters ('y', 'd', 'h', 'm', or 's') or one of these combinations:

  • 'dd:hh:mm:ss'

  • 'hh:mm:ss'

  • 'mm:ss'

  • 'hh:mm'

  • Any of the above, with up to nine S characters to indicate fractional second digits, such as 'hh:mm:ss.SSSS'

• calendarDuration formats can include combinations of the characters 'y', 'q', 'm', 'w', 'd', and 't' in order from largest to smallest unit of time, such as 'ym'.

For more information on the duration and calendarDuration formats, see Set Date and Time Display Format.

locale — Locale represented in output

character vector | string scalar

Locale represented in the output, specified as a character vector or a string scalar. The locale affects the language used to represent certain components of dates and times, such as month names.

locale can be:

• 'system', to specify your system locale.

• A character vector in the form xx_YY, where xx is a lowercase ISO 639-1 two-letter code that specifies a language, and YY is an uppercase ISO 3166-1 alpha-2 code that specifies a country.

The locale input argument can be any of the values accepted by the 'Locale' name-value pair argument for the datetime function.

Example: 'en_US'

Example: 'ja_JP'

Output Arguments

str — Output array

string array

Output array, returned as a string array.

MATLAB^® stores all characters as Unicode characters using the UTF-16 encoding. For more information on Unicode, see Unicode.

Examples

Split String and Find Unique Words

To find the unique words in a string, split it on space characters and call the unique function.

First, create a string scalar.

str = "A horse! A horse! My kingdom for a horse!"

str = 
"A horse! A horse! My kingdom for a horse!"

Remove the exclamation point.

str = erase(str,"!")

str = 
"A horse A horse My kingdom for a horse"

Convert all letters in str to lowercase characters.

str = lower(str)

str = 
"a horse a horse my kingdom for a horse"

Split str on space characters using the split function. split discards the space characters and returns the result as a string array.

str = split(str)

str = 9x1 string
    "a"
    "horse"
    "a"
    "horse"
    "my"
    "kingdom"
    "for"
    "a"
    "horse"

Find the unique words in str using the unique function.

str = unique(str)

str = 5x1 string
    "a"
    "for"
    "horse"
    "kingdom"
    "my"

Convert Character Vector

A = 'Four score and seven years ago'

A = 
'Four score and seven years ago'

str = string(A)

str = 
"Four score and seven years ago"

str contains the same characters as A. But while A is a character vector, str is a string scalar.

c = size(A)

c = 1×2

     1    30

s = size(str)

s = 1×2

     1     1

To return the number of characters in str, use the strlength function.

n = strlength(str)

n = 30

Convert Cell Array

Convert a cell array of character vectors to a string array.

A = {'Mercury','Gemini','Apollo';...
     'Skylab','Skylab B','ISS'}

A = 2x3 cell
    {'Mercury'}    {'Gemini'  }    {'Apollo'}
    {'Skylab' }    {'Skylab B'}    {'ISS'   }

str = string(A)

str = 2x3 string
    "Mercury"    "Gemini"      "Apollo"
    "Skylab"     "Skylab B"    "ISS"   

To access the second element in the first row of str, index using smooth parentheses. You can access strings in a string array with matrix indexing, just as you would access elements of a numeric array.

str(1,2)

ans = 
"Gemini"

Access the third column.

str(:,3)

ans = 2x1 string
    "Apollo"
    "ISS"

Convert Numeric Array

A = [77 65 84 76 65 66]

A = 1×6

    77    65    84    76    65    66

str = string(A)

str = 1x6 string
    "77"    "65"    "84"    "76"    "65"    "66"

str is a string array in which each element represents a number from A. Note that string does not treat numbers as ASCII or Unicode® values the way that the char function does.

Convert Strings That Represent Numbers

Create a string array in which each element represents a number. To convert the string array to a numeric array, use the double function.

str = ["256","3.1416","8.9e-3"]

str = 1x3 string
    "256"    "3.1416"    "8.9e-3"

X = double(str)

X = 1×3

  256.0000    3.1416    0.0089

When the input argument is a string array, the double function treats each element as the representation of a floating-point value. However, when the input is a character array, double instead converts each character to a number representing its Unicode® value.

As an alternative, use the str2double function. str2double is suitable when the input argument might be a string array, character vector, or cell array of character vectors.

Y = str2double(str)

Y = 1×3

  256.0000    3.1416    0.0089

C = '2.7183';
Z = str2double(C)

Z = 2.7183

Convert Duration Array

Create a duration array.

D = hours(23:25) + minutes(8) + seconds(1.2345)

D = 1x3 duration
   23.134 hr   24.134 hr   25.134 hr

Convert D to a string array.

str = string(D)

str = 1x3 string
    "23.134 hr"    "24.134 hr"    "25.134 hr"

str is a string array with one duration value per element. str is the same size as D.

Specify the format of the duration values in str.

str = string(D,'hh:mm')

str = 1x3 string
    "23:08"    "24:08"    "25:08"

Tips

• For a list of functions to create and manipulate text in string arrays, see Characters and Strings.

• If the input argument is an object, then it must belong to a class that implements a string method to represent the object as a string.

Extended Capabilities

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

This function fully supports tall arrays. For more information, see Tall Arrays.

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• A cell array input must be scalar at compile time.

• An enumeration input must be scalar at compile time. Arrays of enumerations are not supported.

Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

This function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).