string

String array

Description

You can represent text in MATLAB^® using string 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 them 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 scalar by enclosing a piece of text in double quotes.

str = "Hello, world"

str = 
"Hello, world"

To create a string array, you can concatenate string scalars 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(A, dateFmt)

Description

str = string(A) converts the input array to a string array. For instance, if A is numeric vector [1 20 300], str is a string array of the same size, ["1" "20" "300"].

str = string(A, dateFmt), where A is a datetime or duration array, applies the specified format, such as "HH:mm:ss". Additionally, you can specify the locale as a separate input, such as "en_US".

Input Arguments

A — Input array

array

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

Input Type	Conversion Notes	Sample Input	Sample Output
char	Each Row becomes a string scalar If A is empty, '', the output is "", a string scalar with no characters	1×3 char array 'foo'	1×1 string array "foo"
		2×3 char array 'foo' 'bar'	2×1 string array "foo" "bar"
Cell array	Every element of a cell array must be convertible to a 1-by-1 string.	{137,'foo'}	["137" "foo"]
Categorical array	Output strings are the category names corresponding to each element of A.	1x3 categorical array red green blue	1x3 string array "red" "green" "blue"
Numeric array	Output format and precision equivalent to using num2str. Use compose to specify more precise formatting. If A is empty, [], the output is a 0-by-0 empty string array. Use char to convert to ASCII or Unicode points.	[137 3.1e-3 8.5e-6]	["137" "0.0031" "8.5e-06"]
datetime array	To specify a format and locale, see dateFmt.	datetime(2020,6,1)	"01-Jun-2020"
Logical array	The logical function does not accept string inputs, so the conversion is one-way.	logical([0 1])	["false" "true"]

Converted missing values, such as NaN, NaT, and <undefined> categorical values, display as <missing>.

dateFmt — Date Format and Locale

character vectors | string scalars

Date format and locale, specified as separate character vectors or string scalars. Input A must be of type datetime, duration, or calendarDuration.

If you do not specify a format, string uses the value in the Format property of A. To specify only the locale, use an empty array as a placeholder for the format, [].

Example: string(A, "yyyy-MM-dd")

Example: string(A, "yyyy-MM-dd","en_US")

Example: string(A, [],"en_US")

The supported formats depend on the data type of A.

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

The locale affects the language used to represent certain components of dates and times, such as month names. Valid values are:

• "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. For sample values, see the Locale name-value argument for the datetime function.

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

Convert from a duration array to string. For more information related to converting from common data types to string see Convert Between Text and datetime or duration Values.

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.

• Converting a char array to a numeric type will produce an array of the corresponding Unicode code values. Text in strings does not convert in this way. Converting a string that does not represent a single numeric value to double will produce a NaN result. For more information, see Unicode and ASCII Values.

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.

HDL Code Generation
Generate VHDL, Verilog and SystemVerilog code for FPGA and ASIC designs using HDL Coder™.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

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

Version History

Introduced in R2016b