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

example

````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"]```.```

example

````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

expand all

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

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

expand all

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

collapse all

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" ```
`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 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" ```
`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.

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

Version History

Introduced in R2016b